Docs platform — the living record and qren.ai/docs

In short

This describes the documentation system you are reading right now. Every decision, specification and plan lives as an ordinary text file alongside the code, and the website is rebuilt from those files whenever a change is merged — so the site cannot disagree with the truth. The pages showing the current state (what is decided, what is being built, what is still open) are worked out by the machine from the documents themselves; nobody maintains a status page by hand. If a document is missing something it needs, or points at a page that does not exist, the site refuses to build, so drift is caught before anyone reads it. It is private to the people building Qren, and it is written to be read by the owner without being technical.

The first spec, because every other spec is written inside it.

Purpose

Everyone building Qren — Hisham, Chief, Zeeshan, Eddeb, later partners who co-develop — can open one place and understand the current state of decisions top to bottom, visually and cleanly, and trust that it is true. The mechanism that makes it true is structural, not discipline: the repo’s docs/ folder is the record; qren.ai/docs is a gated rendering of it rebuilt on every merge; “current state” pages are computed from the documents, never hand-maintained.

Principles

1. One source. Markdown in docs/, git-versioned. The site cannot disagree with the repo because it is built from it.
2. Declare, never report. Every document carries a status in its frontmatter; indexes and state pages are generated from those fields and from git. Nobody edits a status page.
3. Approval is a status change, in git. draft → approved is a commit by the operator (or on his word, by Chief, attributed). Reviewable, revertible, dated.
4. Behaviour and spec change together. A commit that changes what a system does changes its spec in the same commit — the atomic-migration rule applied to documents. Reviewers check this; a PR template asks.
5. Reference is generated. Schema, CLI, API, design tokens are rendered from code by scripts at build time. They physically cannot drift.
6. The build fails on drift. Invalid frontmatter, a broken internal link, an ADR number collision, a spec with no status — the site does not build. Drift is caught before it is published.
7. Readable by the owner. Every decision, spec, plan and board opens with an “In short” section: what this is, why it matters, what it changes — in plain English a non-technical reader understands without the rest of the page. Technical terms link to the glossary on first use. The detail below it is for the people building; the top is for the person deciding. A document whose “In short” a non-technical reader cannot follow is not finished. (Lint: required heading in adr / spec / plan / board — follow-up.)
8. Team-shared, not public. The docs are for people building or co-developing Qren. Business-private material (pricing, moat analysis, client specifics) stays in the operator’s vault and never enters docs/.

The ladder

(the shelves a document can sit on, from the broadest idea down to the exact detail)

Layer	Folder	Answers	status values
Vision	docs/vision.md	why Qren exists, what it is (product vision — business strategy stays in the vault)	living
Glossary	CONTEXT.md (repo root, rendered into the site)	what words mean	canonical
Decisions (ADRs)	docs/adr/NNNN-*.md	what is irreversible, and why	proposed · accepted · superseded
Decision records	docs/design/decisions-YYYY-MM-DD.md	what a session settled; feeds ADRs and specs	dated (no status)
Design notes	docs/design/*.md	shape proposals before they are specs (e.g. the target tree)	proposed · approved · superseded
Specs	docs/specs/<system>.md	what one system does — model, behaviour, interfaces, explicitly what it does not do	draft · approved · building · shipped · retired
Plans	docs/plans/<slice>.md	ordered steps for one slice, each with acceptance	active · done · abandoned
Reference	docs/reference/	exact schema, CLI verbs, Control API, tokens — generated	generated (commit hash)
Runbooks	docs/runbooks/	how to operate: deploy an appliance, rotate a credential, restore from shadow	living
Changelog	docs/changelog.md	what shipped, when	per release
Boards	docs/boards/	one visual page that explains one thing — built from the record	draft · current · outdated
Brand	docs/brand/	brief, direction, boards	as today

A spec is approved before its plan exists; a plan is done before the changelog names it. Each document links down to the layer below and up to the layer above (related:), so the site can draw the chain: vision → ADR → spec → plan → reference → release.

Frontmatter contract

(the small block of labels at the top of every document — title, status, owner, dates — that the site reads)

title: ""            # required, human
status: ""           # required except decision records; values per layer above
layer: ""            # adr | design | spec | plan | runbook | reference | board | brand
owner: ""            # a person, not a team
created: YYYY-MM-DD  # required
updated: YYYY-MM-DD  # required; CI rejects a content change without it
supersedes: []       # optional
superseded_by: ""    # required when status is superseded
related: []          # paths relative to docs/

Enforced by the site’s content-collection schema at build (Astro/Starlight content collections validate frontmatter with a schema; a violation fails the build) and by a local bun run docs:lint so it fails on the desk, not in CI.

The current-state view (/docs/)

(the front page, assembled by the machine, showing where everything stands today)

The landing page, fully generated:

• Decisions — ADRs grouped by status; superseded ones struck through with a link to their successor.
• Systems — one card per spec: status, owner, last updated, its plan (if any) and the plan’s step count done/total.
• In flight — active plans, newest activity first.
• Open questions — collected from a ## Open questions section in any approved spec or design note (the build extracts them).
• Recent changes — the last 20 commits touching docs/, with author and the documents touched.
• Diagrams that earn their place — the target tree, the agent model, the data flow; Mermaid in markdown for simple ones, committed SVG (D2) for rich ones. Every diagram is next to the document it illustrates, not in a gallery.

Footer on every page: as of <short commit hash> · <date> — the version is the git commit, and release tags mark milestones.

Boards — the artifact layer

(a board is one visual page that explains one thing better than paragraphs would)

The operator likes Claude’s artifacts: a single visual page that explains one thing — a journey, a system, a state — better than prose. The docs platform has a native equivalent so they are ours: our tokens, our brand, gated, versioned, and never stale.

• A board is one page under docs/boards/<slug>.mdx — markdown with components (Astro islands; React where interaction is needed). It carries the same frontmatter (layer: board, status, related:) and links to the decisions and specs it illustrates.
• Boards are built from the record, not beside it: a journey board reads its stage list from the spec it illustrates; a state board reads statuses from frontmatter; a data board reads a JSON file committed next to it with its own as_of date. A board that hand-copies facts is a bug.
• Styling comes from the tokens file — monochrome, light + dark, the app’s type and spacing — so a board looks like the product, not like a slide. Motion only for arrival and state; no decoration.
• Board components are a small, reusable kit in docs-site/components/: journey lanes (paths with built / next states), a system map, a state grid, a product mock frame, a timeline, a comparison table. New boards compose these; new components are added sparingly.
• The first board: “From Invite to Home” — the successor to the 2026-08-17 artifact “From Download to Home” (now outdated): the staged admission path (invite → approved → network → owner grants → live), the three install paths (fresh Mac / existing AOS install crossing via the Gardener / member), and the walking-skeleton Home. Its stages come from the decision record and the admission spec when written.
• Claude artifacts remain a scratch medium for one-off thinking; anything worth keeping is ported to a board.

The site

Generator: Astro + Starlight. Markdown/MDX in, static HTML out; content collections give the frontmatter schema for free; Pagefind search is built in; sidebars are configurable; CSS variables are the theming surface, so it adopts the app’s tokens file when that exists (monochrome, light + dark — Starlight ships both modes). Alternatives considered: VitePress (lighter, weaker schema enforcement), MkDocs Material (Python toolchain we are leaving), Docusaurus (React-heavy for a docs site), Mintlify/GitBook (hosted — conflicts with “one source, gated by us”). Verify on install: Mermaid rendering at build time (rehype plugin) and the link-validator plugin; both exist for Starlight, versions to be pinned.

Where it lives in the repo: docs-site/ (the Astro project — config, theme, schema, generators) reading content from ../docs/ and ../CONTEXT.md. docs/ stays plain markdown that reads fine in GitHub and any editor; the site is a view.

Build & deploy: the existing Deploy Site GitHub Action gains a step: build docs-site/ → output into the deploy directory under /docs/ → publish with the existing site/ to the existing Pages project qren. One project, one token (qren-pages-ci, Pages-edit only — unchanged). Triggers: pushes touching docs/**, CONTEXT.md, docs-site/**, site/**. PR previews come from Pages for free.

Gate: a Cloudflare Access application scoped to qren.ai/docs*, identity by one-time email PIN (and Google if wanted), policy = an allow list of email addresses. Start: Hisham, Zeeshan, Eddeb, Faisal. Later the admission flow (invite → approved) writes to this list through the Access API via the broker — the same gate, automated. The public site at / stays public. Note: this amends docs/context/website.md (“don’t add frameworks or build steps”) — the docs site is the deliberate exception, and site/ itself stays pure assets.

Generated reference, day one: CONTEXT.md rendered as the glossary; the decision record; ADRs 0001–0005 (and 0006 when written); the target tree. Generators for schema / CLI / tokens are added when those exist — each generator is a small script in docs-site/generators/ and runs in the build.

What it explicitly does not do

• No comments, no editing in the browser — changes are commits.
• No separate wiki; no Notion; no Google Docs for anything that is a decision, a spec, or a plan.
• No public docs. Marketing copy belongs to site/.
• No business-private material (see principle 8).

Open questions

• Starlight’s Mermaid-at-build plugin vs. client-side rendering — pick on install after checking CSP on Pages.
• Whether decision records should expire into ADRs/specs (they are history; proposal: keep, mark folded: true once their contents live in ADRs/specs, and the index hides folded ones by default).

Plan (the slice for this spec — once approved)

1. Scaffold docs-site/ (Astro + Starlight), content collection schema from the frontmatter contract, monochrome tokens, light + dark.
2. Move existing docs/ content into the ladder: frontmatter added to the five ADRs, the target tree (design, approved), the decision record, the brand docs; CONTEXT.md rendered as the glossary; docs/vision.md written as the product vision (no business numbers).
3. docs:lint locally; build-failing checks for frontmatter, links, ADR numbering, updated freshness.
4. Current-state index generator (statuses, plans, open questions, recent changes, commit footer). 4b. Board kit (journey lanes, system map, state grid, mock frame, timeline) and the first board, “From Invite to Home”.
5. Deploy step in the existing action → qren.ai/docs; Access application and first allow list (operator action in the dashboard — needs a token scope the CI token deliberately lacks).
6. PR template with the “spec updated?” check. Acceptance: a teammate with an allow-listed email opens qren.ai/docs, sees every decision and spec with its status, and the build refuses a document with a missing status.