Reader session — get up to speed, then think out loud

In short

A reader session is how someone joining Qren — Zeeshan, Ali, anyone we invite — gets up to speed and tells us what they think. Claude sits with them in this repo: first it explains what Qren is, what this repository is, how it is organised and how we work, and answers any question they have. Then it walks them through the record in the right order and writes down their reactions, ideas, objections and questions in their own words. Nothing is decided in the session and nothing in the record is changed by it. At the end there is one short document of that person’s notes for Hisham to read later — and a person who understands the project.

Before you start (reader)

1. Accept the GitHub invitation to hishamalhadi/qren (check your email).
2. git clone https://github.com/hishamalhadi/qren.git && cd qren
3. Run claude in that folder and say: “Start the reader session.”
4. Optional: open https://qren.ai/docs in a browser — it asks for your email and sends you a code; it is the same record, rendered.

Voice-to-text is fine. Take as long as you like; stop whenever — the notes are saved as you go. Ask anything at any point.

The session (instructions to Claude)

You have two jobs, in this order: get the reader up to speed, then capture their thinking. The reader is a developer joining the project (Zeeshan Bari or Ali Eddeb, or someone Hisham names). Read docs/specs/docs-platform.md, docs/vision.md, docs/roadmap.mdx, docs/design/decisions-2026-08-20.md and CONTEXT.md yourself before you say anything, so you can answer questions without guessing.

Part 1 — Orientation (10–15 minutes, conversational)

Greet them by name. Then cover, in plain English, pausing for questions after each:

1. What Qren is — an operating system for AI agents, shipped as a Mac appliance the client owns; people and agents side by side; the successor to AOS. One paragraph from docs/vision.md, in your words.
2. Where we are — the destination (RunRec live, our own companies as the test bed), what is decided (six ADRs, the decision record), what is drafted (work core, front door), what is open. Use docs/roadmap.mdx.
3. What this repository is — the long-term home of Qren: today the record (vision, decisions, specs, plans, boards), the qren.ai front door, and the docs site that renders the record at qren.ai/docs. The product code arrives here in slices.
4. How it is organised — the ladder (vision → glossary → ADRs → decision records → design → specs → plans → reference → runbooks → changelog), one status per document, indexes computed from those statuses. Show docs/ in the terminal.
5. How we work — spec first, approved before a plan; thin horizontal slices; behaviour and spec change in the same commit; every document opens with an “In short” a non-technical reader can follow; bun run docs:lint in docs-site/ before pushing; PR template. Hisham approves specs; Chief (Hisham’s Claude) drafts and coordinates; developers pick up pieces from approved specs.
6. What we would love from them — honest first reactions, objections, better ideas, what they would build first, and where they see risk. Nothing is too small; nothing is final except the ADRs, and even those can be challenged with a reason.

Answer every question fully from the record. If the record does not answer it, say so plainly (“that isn’t decided yet — I’ll note it as a question for Hisham”) and write it down. Never invent a decision.

Part 2 — Reading, thinking out loud

Open each document for them, summarise it in two or three sentences, then let them react. Order: docs/roadmap.mdx → docs/vision.md → docs/design/decisions-2026-08-20.md → docs/adr/0001 … 0006 → docs/boards/from-invite-to-home.mdx (describe it; it is visual) → docs/specs/work-core.md → docs/specs/front-door.md → docs/specs/docs-platform.md → CONTEXT.md. Skip ahead if they want to.

Ask one question at a time, only when they go quiet: “What do you think?” · “What would you build differently?” · “What worries you?” · “What is missing?” · “Where would you start?” Answer questions; do not argue with opinions. If they disagree with a decision, capture the disagreement and the reason — do not defend it with the research. Plain English, short turns; they should be talking most of the time.

What to capture

Their words first, lightly tidied. Under each document: reactions, ideas, objections, questions, and anything they say they would volunteer to build. Keep a running list of themes that cut across documents, and a list of questions the record could not answer.

Files

At the start create a branch feedback/<firstname>-<YYYY-MM-DD>. Write docs/feedback/<firstname>-<YYYY-MM-DD>.md (frontmatter: title “Reader notes — , ”, status living, layer design, owner , created/updated ) and append after every document so nothing is lost. Structure: ## In short (five lines: who, what they read, the three strongest reactions) · ## Questions they asked (with the answers given, and which ones the record could not answer) · one section per document · ## Themes · ## Ideas worth a spec · ## Objections to answer · ## Questions for Hisham · ## What they would build first. Commit after each section and push the branch (never main). Touch nothing else in the repo.

Ending

Read their “In short” back to them and adjust until they say it is fair. Tell them what happens next: Hisham reads the notes, the good ideas become specs or questions in the record, and they will hear back. Thank them.