docs: rebuild docs site from docs-lab

.agents/skills/draft-openspec-docs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: draft-openspec-docs
+description: Collaborative page-drafting mode for the OpenSpec docs. Builds a scratch plan inside the target page (purpose, structure, numbered draft steps), iterates on it with the user, then drafts one section per approved step and cleans up after itself. Use when a page needs a from-scratch rewrite or a new page is being shaped with the user in the loop.
+argument-hint: target page
+---
+
+# Draft OpenSpec docs (scratch-plan workflow)
+
+You are shaping a docs page with the user in the loop. The page is planned and reviewed inside the page itself, then drafted one section at a time. Load `write-openspec-docs` (the style authority) and `no-ai-slop` before drafting anything.
+
+## 1. Set up the scratch section
+
+Strip the page to its title and `>` goal line, then add a working section below them:
+
+```md
+## Scratch: page plan (delete before publish)
+
+### Purpose
+
+### Structure
+```
+
+- **Purpose**: 3-5 dot points. Who the reader is and what they come to look up, what the page covers, what it links out to. Check `docs-lab/README.md` (the page's goal line) and `docs-lab/message-map.md` (the questions routed here) before writing it.
+- **Structure**: a numbered list of the page's sections, one line each naming the section and the shape of its content (table, fence, tree, bullets).
+- Say what the page will do, never what it won't. Plain words and short bullets; the user reads this in their editor.
+
+## 2. Iterate until the plan is approved
+
+- Plan edits are cheap; page edits aren't. Reshape the plan as many times as the user asks before drafting.
+- Record every decision in the plan itself, not only in chat. Add a `### Notes` list for follow-ups that belong to other pages and product observations found along the way.
+- The user may edit the file directly between turns; their edits are decisions, not drift to revert.
+- Surface one open call at a time, with a recommendation.
+
+## 3. Add the draft plan, then draft step by step
+
+Once the structure holds, add a `### Draft plan` below the notes: one step per page section, each with an ID and a readable title (`**D1. Goal line and intro**`), ending with a consolidation step (cross-page updates) and a cleanup step. Then:
+
+- Wait for the user to call a step ID. Draft exactly that step, into the page above the scratch block.
+- Verify each fact against source before writing it; a cheap grep beats trust. Reference content shows the raw contract (templates, instructions, config) verbatim in fences, linked to the file on GitHub, rather than paraphrasing it.
+- Keep sibling sections on a repeatable sub-structure so the page scans as one system.
+- Mark the step `(done)` in the plan, report what landed, and name the next step.
+
+## 4. Consolidation and cleanup
+
+- **Consolidation**: update everything that points at the page. The README goal line (verbatim match with the page's `>` line), the message map, the sync config (`website/docs.sync.config.mjs`), and any cross-links found by grepping the tree. Run `node website/scripts/sync-docs.mjs` to validate.
+- **Cleanup**: delete the scratch block, run the retrievability and glance tests from `write-openspec-docs` at desktop and narrow widths, and flip the page's message-map row to Answered if its prose landed.

.agents/skills/verify-openspec-docs/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: verify-openspec-docs
+description: Fact-checks OpenSpec user documentation with a fresh-context subagent that re-runs commands and checks claims against source. Manually triggered; not part of the drafting loop. Use when the user asks to verify, fact-check, or accuracy-check a docs page, section, or set of changed claims.
+argument-hint: page or section
+---
+
+# Verify OpenSpec docs
+
+Check finished docs prose against reality. The point of a fresh context is that the reviewer hasn't watched the prose get written, so it can't be talked into the author's assumptions.
+
+This skill runs only when the user asks for it. Drafting is owned by `write-openspec-docs`; don't invoke this from inside a drafting session unless the user requests a verification pass.
+
+## Scope the run
+
+1. Confirm the target: a page, one `##` section, or a list of changed claims. If invoked without a target, ask.
+2. Read the README at the root of the docs tree the target lives in; its invariants and page map are part of what gets checked.
+3. One subagent per unit (one `##` section, or the stated claim list). A full page is several subagents, run in parallel.
+
+## Spawn the reviewer
+
+General-purpose subagent. Subagents don't inherit skills, so the prompt hands the reviewer everything by path. Fill every placeholder, make every path absolute, and send:
+
+```
+You are reviewing one unit of OpenSpec's user documentation before it reaches the docs owner. Be the two hardest readers it will meet: a skeptical developer reading it cold, and a fact-checker with the repo open.
+
+Repo root: <ABSOLUTE REPO ROOT>. Use absolute paths with every tool.
+
+Read first:
+1. <DOCS TREE ROOT>/README.md: the page map and standing invariants.
+2. <ABSOLUTE REPO ROOT>/.agents/skills/write-openspec-docs/writing.md: the house writing rules.
+3. <PAGE PATH>: review only <the section "<HEADING>" | these changed claims: <LIST>>; read the rest of the page for context.
+
+Then check, in this order:
+
+1. Facts. Every command, flag, path, config key, output block, default, and behavior claim. Re-run the terminal commands shown: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Commands for the AI chat surface (like /opsx:propose) can't run in a shell; verify their names and behavior against the skill sources this repo ships. Check names against src/ and the CLI's own --help. An output block must match what the command actually prints.
+2. Examples. Any example spec or change must pass `openspec validate`. Run it when the example exists on disk.
+3. Structure. Flag anything that re-explains a topic whose canonical home is another page, or breaks a rule the docs tree's README states.
+4. Job fit. Does the unit serve the page's stated job (the one-line statement under the title, if present)? Does the arriving reader get what they came for quickly?
+5. Trust and slop. Flag: hype or comfort adjectives (easy, simple, powerful, seamless), claims with no shown evidence, vague generalization where a specific fact belongs, binary contrasts ("not X, it's Y"), colon reveals, importance puffery, summary endings, em dashes, bullet lists that should be prose, and three parallel punchy sentences in a row.
+
+Report findings only, most severe first. For each: quote the line, say what is wrong, and give the fix in one line. For every fact you verified, say how (the command you ran, or the file and line you checked). List any claim you could not verify and why. Do not rewrite the unit. If the unit is clean, say so and list exactly what you verified.
+```
+
+## Handle the report
+
+- Default is report, not rewrite: show the user the findings ranked most severe first, each with the quoted line and one-line fix, plus what was verified and how, and any claim the reviewer couldn't verify.
+- Apply fixes only when the user asked for a verify-and-fix run or approves the findings. A verifier can also be wrong: rejections go in the report with your reason, so the user can overrule you.
+- If an applied fix changed a factual claim, verify again, scoped to the changed claims. Typo and wording fixes don't need a second pass.
+- Two passes without converging means stop and take it to the user. Don't polish in a loop.

.agents/skills/write-openspec-docs/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: write-openspec-docs
+description: Switches into OpenSpec docs-writing mode; loads the house style guide and drafts or revises pages in its voice (action-first, no preamble, scannable). Use when writing or editing pages in the OpenSpec docs tree.
+argument-hint: page or section
+---
+
+# Write OpenSpec docs
+
+You are now writing OpenSpec's user docs. Read [writing.md](writing.md); it is the style authority for everything drafted here. The short version, in effect immediately:
+
+- A page is a retrieval surface, not an essay. Structure decides whether the reader finds the answer; prose only decides how it reads. Open every section with the answer, never a running story.
+- Choose the page type before the outline. Guides follow the reader's task; reference mirrors the product's structure and uses exact field, command, and file names as scan anchors. Reference needs complete coverage without compressing several facts into one sentence, cell, or paragraph.
+- Draft the shortest version that answers; expanding a spare page is cheap, cutting a bloated one is a rewrite. Plain words, the fewest of them: an idea that fits in one line takes one line. Depth most readers skip goes behind a link, and the payload (commands, real output, failures and fixes) stays whole.
+- Dumb sentences, smart structure. Write the obvious sentence (actor, verb, object, stating the literal event); never compress extra facts in or take an angle. No hype adjectives, no preamble, no em dashes.
+- One job per slot: one fact per sentence, list intros only announce the list, one reader question or lookup target per section. A related fact gets its own slot, never a ride in someone else's.
+- Ground items in what the reader can verify: path or folder first, concept as the gloss, real output shown honestly.
+- No house template. Inventories open with a list naming every item, then expand each in its own unit after the list, never inline. Sequences take numbered steps (numbers mean order; inventories take bullets). Single ideas and reasoning stay in short prose.
+- Every load-bearing fact sits on a scan anchor: code fence, numbered bold lead-in, `**Term**: fact` bullet, table, file tree. Never only mid-paragraph.
+- Before finishing, run two backstop tests. Retrievability: can each question or exact product name be found by scanning alone? The glance: inspect the rendered page as shapes; does it look finishable, or like work? Check table-heavy changes at desktop and narrow widths. A failure means a slot got written without being earned; fix it now, don't leave it for review.
+
+## Ground rules
+
+- Load the `no-ai-slop` skill before drafting; it owns the generic slop patterns, while [writing.md](writing.md) owns what OpenSpec's docs specifically look and sound like.
+- Read the target page in full before editing it.
+- Real facts only: flags, paths, and output as they exist in source. If a claim can't be checked cheaply, still write it, but name it as unchecked when you show the work; never bridge a gap with a plausible-sounding sentence.
+- A fact lives on one page; everywhere else links to it. The docs tree's README owns the page map and structural invariants; check it before restructuring or adding pages.
+- For reference pages, inventory the contract from source before drafting prose. Follow the reference process in [writing.md](writing.md#reference-pages).
+- When unsure how something should scan or sound, match the exemplars: `docs-lab/start/setup.md` for section shape and inventories, `docs-lab/start/installation.md` (Uninstalling) for multi-step tasks.
+
+## When done
+
+Show the user what changed and name any unchecked claims.
+
+If the user asks for the deep, evidence-first drafting session (run every command, one section per sitting, formal checkpoints), follow [full-process.md](full-process.md).

.agents/skills/write-openspec-docs/full-process.md

@@ -0,0 +1,49 @@
+# Full drafting process (opt-in)
+
+The evidence-first, checkpointed way to draft a page. Use this only when the user asks for the deep process; the default mode is SKILL.md alone.
+
+## Orient (every session, before any writing)
+
+1. Read the README at the root of the docs tree you're writing in. Where it states invariants or a page map, it wins over this skill.
+2. Read the target page top to bottom, plus anything its comments cite.
+3. Read the sibling pages this page links to or overlaps with, enough to know what must stay a link rather than become an explanation.
+4. Write down the page's job in one line: who arrives, trying to do what, and what they leave able to do. If the page carries a job statement (docs-lab pages use a `>` blockquote under the title), test against it. If the unit you're about to write doesn't serve that job, stop and raise it instead of drafting around it.
+
+## Work in small units
+
+- The default unit is one `##` section. A page is several sittings, not one.
+- For revisions to existing prose, the unit is the requested change, however many headings it touches.
+- Draft the next unit only after the user has reviewed the current one. When the user asks for fixes, fix only that; don't smuggle in the next unit.
+
+## Evidence before prose
+
+Before drafting a unit, know where its claims come from.
+
+- Run the terminal commands the unit will show when they're cheap: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Paste real output; trim it, never retouch it.
+- Check names against source: flags, paths, config keys, and defaults come from `src/` and the CLI's own help, not from older docs. When docs and source disagree, source wins; note the conflict for the user.
+- Never bridge a gap with a plausible-sounding sentence. A claim you couldn't check gets flagged at the checkpoint, not silently shipped. Don't let one expensive check stall the draft.
+
+## Strip the slop
+
+Invoke the `no-ai-slop` skill on the drafted unit and apply its edit pass. Docs prose gets no exemption: the patterns it names read as machine-written to exactly the audience these docs must win over.
+
+## Does it do the job?
+
+Reread the unit cold, as the reader the job line names, arriving with their actual problem. Answer three questions:
+
+1. Can they act? Every step is runnable as written, and nothing depends on knowledge the page hasn't given or linked.
+2. Do they know it worked? Where success could be in doubt, the unit shows something visible: output, a file, what the agent does next. Where the outcome is obvious, no success line is owed.
+3. What can they do now that they couldn't before? If the honest answer is "they read some context", the unit is explaining instead of solving; cut it back to what serves the job or raise it with the user.
+
+A unit that fails here gets fixed before the checkpoint, not annotated.
+
+## Checkpoint
+
+End the unit by showing the user:
+
+- the file path and the unit written;
+- the page's job in one line, and what this unit lets the reader do toward it;
+- which claims you checked and how (commands run, files read);
+- any claim still unchecked.
+
+Then stop. The next unit starts when the user says so.