# AWP Documentation

## Markdown is canonical

Every document under `docs/` is a Markdown file, and the Markdown **is** the document. There is no generated or authored HTML twin to keep in sync.

Until 2026-08-21 nearly every `.md` here had a paired `.html` viewer shell beside it. Those shells were not renderings — they were near-empty pages that fetched the Markdown at runtime through `docs/specs/assets/spec-runtime.js`. They failed silently on `file://` (the browser blocks `fetch` for local files), and each carried hardcoded hero/status text that drifted away from the Markdown it claimed to present. They have been deleted. One generic viewer replaces all of them.

## Browsing the rendered specs

```bash
pnpm docs:serve
# then open http://localhost:4173/specs/view.html?doc=INDEX.md
```

`docs:serve` runs `python3 -m http.server 4173 -d docs`. Any static file server works; the only requirement is HTTP rather than `file://`, because the viewer fetches the Markdown at runtime.

The viewer takes the document as a query parameter, resolved relative to `docs/specs/`:

```text
specs/view.html?doc=INDEX.md
specs/view.html?doc=adr/0001-control-plane-and-three-plane-topology.md
specs/view.html?doc=architecture/module-boundaries.md
specs/view.html?doc=../plans/I0-I1-AUTHORITY.md
specs/view.html?doc=../VISION.md
```

It renders headings, lists, tables, code blocks and callouts; builds a table of contents; rewrites relative `.md` links so navigation stays inside the viewer; and auto-links domain concept names (`Task`, `ChangeSet`, `FactoryRun`, …) to the spec that owns them.

The viewer is a convenience. Reading the Markdown directly — in an editor, on GitHub, or with `cat` — is equally correct and is what agents should do.

## What lives where

```text
docs/specs/       target-state specification: architecture, ADRs, domains,
                  workflows, UI/IA, schemas
docs/specs/adr/   the 8 ADRs — BINDING
docs/specs/assets/  viewer stylesheet + runtime (spec.css, spec-runtime.js)
docs/specs/view.html  the single generic viewer page
docs/plans/       planning, decisions, evidence, governance records
docs/mockups/i1/  approved U1-U6 high-fidelity screens (standalone HTML,
                  self-contained, open directly)
docs/standards/   coding and engineering standards
docs/reports/     progress and review reports
docs/evidence/    evidence records
docs/VISION.md    owner-authored product intent
```

`docs/mockups/` HTML is genuinely standalone — self-contained pages with no Markdown twin — and is not affected by any of the above. Open those files directly.

## Which documents are binding

Most of `docs/` is **reference material**. The binding set is deliberately small enough to read in full before writing code:

- `docs/specs/adr/` — the 8 ADRs
- `docs/plans/I0-I1-AUTHORITY.md` — the distilled implementation digest
- repo-root `GOLIVE.md` — the go-live journey
- `docs/plans/AWP-PAIN-INVARIANTS.md` — pain chains, invariants, required regression arms
- `docs/plans/AWP-GOVERNANCE-AMENDMENT-2026-08-21.md` — current gate state and authority rule

See the source-of-truth rule in the [repository README](../README.md) for precedence.

## Adding a document

Write the `.md`, link it from the relevant `INDEX.md`, and stop. Do not create a paired `.html`.