Version Packages (#1766)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.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.

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

@@ -0,0 +1,204 @@
+# OpenSpec docs: the style guide
+
+Structure, voice, tone, and language for OpenSpec's user docs. This file is the primary style authority for the docs tree. The tree's own README owns structure (the page map and which page teaches what); when this file and that README disagree, the README wins. `no-ai-slop` owns the generic slop patterns; this file owns what OpenSpec's docs specifically look and sound like.
+
+## Six principles
+
+Every rule below applies one of these; when rules collide, the principles decide.
+
+- **A page is a retrieval surface, not an essay.** The reader arrives mid-task with a question, scans for the answer, and leaves. Structure decides whether they find it; prose only decides how it reads. Structure wins.
+- **The shortest version that answers is the right length, drafted that way from the start.** Expanding a spare page is cheap; cutting a bloated one is a rewrite. Plain words, and the fewest of them: an idea that fits in one line takes one line.
+- **Dumb sentences, smart structure.** Write the obvious sentence: actor, verb, object, stating the literal event ("Running init creates two things in your project"). Never the version that compresses facts in or takes an angle ("Everything init creates is meant to be committed"). If a sentence needs unpacking, it failed.
+- **One job per slot.** A sentence carries one fact (one carrying three hides two). A list intro only announces its list. A section owns one reader question or lookup target. Related facts get their own slot, never a ride in someone else's.
+- **Ground everything in what the reader can verify.** Name things by path, file, or real output: what the reader could match against `ls`. The concept is the gloss, never the name.
+- **No house template.** Shape follows content: inventories get overview-then-expand, sequences get numbered steps, a single idea gets short paragraphs, and reasoning lives in prose. The universal check is the retrievability test, not bullet count.
+
+## The retrievability test
+
+Name the questions or exact product terms a reader would bring to the section ("does init touch `.gitignore`?", "how do I add a tool later?", `generates`). Each answer or term must be findable by scanning, heading to anchor to fact, without reading paragraphs. If finding a fact means reading sentences, restructure; prose that passes needs no bullets, and no amount of bullets saves a section that fails.
+
+## The shortest draft
+
+Brevity happens at drafting time, not review. A page that needs heavy cutting in review gets rewritten, and a rewrite costs more than writing it spare the first time. Start from the shortest version that answers and expand only where a real reader question goes unanswered.
+
+Every slot is earned before it's written:
+
+- **The unit**: it answers a reader question or documents a lookup target, or it doesn't go in. Tight prose on the wrong scope is still the wrong scope.
+- **The sentence**: would any reader come back for it? If not, it spends attention without buying anything; don't write it.
+- **The depth**: an edge case or rationale most readers skip goes behind a link to its canonical page, not inline. The docs keep the depth; this page doesn't charge every reader for it.
+- **The payload**: the command, the real output, the failure and its fix stay whole. Spare means no wind-up and no commentary, never fewer facts.
+
+The glance test is the backstop, not the method. Scroll the rendered page and read it as shapes: short units, air between anchors, no screen-filling block of anything. A page that looks like work loses its reader before the first sentence; if yours does, something above got in without earning its slot. For table or layout changes, check both desktop and narrow widths; the Markdown source can't show cramped columns, poor wrapping, or horizontal scrolling.
+
+## Shape of a section
+
+- **Answer first**: open with the command, the inventory, or the fact in one line. Context and rationale come after, never first.
+- **Inventory, then expand**: when a section covers several things (what init installs, what an uninstall leaves behind), open with a list naming every item in one line each, then expand each in its own unit after the list (a subsection or bold lead-in).
+- **The overview only names**: a count ("two things:") is not an inventory, and expansion never happens inline in the list; the reader sees the whole footprint, then the detail.
+- **Place first, meaning second**: name each on-disk item by its path or folder ("an `openspec/` folder at the repo root"), never by concept alone ("the planning folder"). The concept gloss can wait for the item's expansion. When a location varies (per tool, per OS), anchor it with a real folder or two ("`.agents/`, `.claude/`") and link the full list.
+- **Core before nuance**: inside every unit, the answer, then what to expect, then edge cases last. A reader who stops early still leaves with the core.
+- **One unit per target**: task pages separate different reader questions. Reference pages separate different product elements when readers look them up independently. Two facts with different targets get separate units, even when one elegant sentence could join them.
+
+## Scan anchors
+
+Every load-bearing fact sits on an anchor: something the eye lands on without reading. A fact a reader might come back for never lives only in the middle of a paragraph. The anchors these docs use:
+
+- Code fences, for commands and real output.
+- Numbered steps with bold lead-ins (`**1. Remove the package.**`) for multi-step tasks.
+- `**Term**: fact` bullets for options, properties, and locations.
+- Tables, when several items share the same attributes (mostly reference pages).
+- File trees with inline annotations for layouts.
+
+A full screen of content with no anchor is a wall, even when every sentence in it is true.
+
+## Choosing the shape
+
+No house template: facts go on anchors (enumerable content defaults to a list or table); explanation, reasoning, and judgment go in prose. The content picks the form:
+
+- **Sequences**: numbered steps, one bounded action each. Numbers mean order of execution; an inventory of things takes bullets, never numbers. Restate any value a step needs rather than pointing back three steps.
+- **Options, properties, locations**: `**Term**: fact` bullets.
+- **Items sharing the same attributes**: a table.
+- **A single idea** (why a store is worth it, what sync treats as drift): a couple of short paragraphs; that is the right shape.
+- **Connected reasoning**: a paragraph. Shredding a thought into fragments makes it harder to read, not easier; a bullet list of full explanatory sentences is a paragraph in costume, so write the paragraph.
+
+Across every form:
+
+- Cap lists at about five items. Longer than that, split by priority: common path first, edge cases into their own list or a linked page.
+- Keep items parallel: same internal order (name, fact, catch, link), same grammatical shape. Repetition across items is what makes scanning work; never vary structure between items for the sake of the prose.
+- Uniformity is right when the content is uniform (a reference table, an install matrix). When every section on a varied page resolves to the same pattern, some of those lists are disguised paragraphs.
+
+## Prose budget
+
+Paragraphs are glue between anchors, not containers for facts.
+
+- One to three lines. Three is the ceiling; a glue line between two anchors is often enough.
+- The list intro has exactly one job: say what the list is ("Running init creates two things in your project:"). Never spend that slot on a different fact, however related; it gets its own line after the list.
+- Parentheses and semicolon riders are for true asides only (a version caveat, a pointer). If a reader might return for the fact, it gets its own anchor.
+- A section that is mostly paragraphs is misshaped, unless the page is genuinely conceptual (Concepts, explanations of the model). Even there, front-load each paragraph and leave air between them.
+
+## Sentences
+
+- Short sentences, active voice. Default subject is "you" or the tool by name.
+- No preamble. The first sentence of any unit states the thing itself, never wind-up ("Before we get into...", "It's worth understanding that...").
+- No em dashes anywhere in these docs. Use a colon, a comma, parentheses, or two sentences.
+- Write the sentence you would say out loud. A draft that splices clauses with semicolons or colon-stacked fragments ("different documents: fewer of them, different names, different structure") gets rewritten as the spoken version ("when you want these to be different documents, whether that means fewer of them, different names, or a different structure"). Colons still introduce lists, fences, and labels. They don't splice prose.
+- Contractions are fine ("you're set", "doesn't come along"). These docs talk, they don't proclaim.
+- Inside narrative paragraphs, vary sentence length so the prose doesn't read staccato. Paragraphs only; list items stay parallel even when the cadence repeats.
+
+## Voice
+
+The narrator is a colleague who has run every command on the page, hit the failure modes personally, and is telling you what they know. Not a marketer, not a tutorial host, not a manual.
+
+- Calm and specific. The reader wants the fact, the command, and the catch, in that order.
+- Confidence comes from precision, not emphasis. Never "very", "extremely", "critical", bold-for-importance, or exclamation marks.
+- Plain judgment is welcome. The docs may tell the reader what to do and what to skip: "The `openspec/` folder: pause first."
+- Address the reader as "you". OpenSpec, the CLI, and init do things. "We" appears only for project decisions ("we say skills"), never as a tour guide.
+- Dry beats chirpy. No cheerleading, no apologizing, no drama around failures. A failure is a fact with a fix.
+
+## Structure and tone by page type
+
+Same voice everywhere; structure and temperature shift:
+
+- **Start pages**: numbered steps and short units, nothing assumed, every step ends in something visible. Warmest the docs get, which is still plain.
+- **Guides**: peer to peer, skip re-orientation. The judgment calls are the reason guides exist; put them on anchors so they scan.
+- **Reference**: mirror the product, use its exact names as anchors, and cover the contract without compressing it. Tables and fragments are common, but scan speed decides the shape. No motivation or persuasion; the reader is here to look something up and leave.
+- **Troubleshooting**: symptom, cause, fix, in that order, one unit per symptom. Name the error the reader sees. Never "you may notice" or "sometimes it can happen that".
+
+Guides and Customize pages share one skeleton: a one-line what, a link to the Quickstart (never a recap), the 80% path, then Advanced. The exception is the concepts page, which is an explanation, not a task guide; its shape follows its concerns.
+
+## Reference pages
+
+Reference describes the product for a reader who is already working with it. The outline follows the machinery: file, block, field; command group, command, option; object, property, value. Use the product's exact names as headings when readers will search for those names. Reader-question headings belong to task pages unless the question itself is the established lookup term.
+
+Cover the full contract without packing several facts into one sentence, cell, or paragraph.
+
+### Draft the contract first
+
+Before writing prose:
+
+1. Inventory the product elements from source.
+2. Arrange them in the same hierarchy as the product.
+3. Write the smallest complete contract for each element.
+4. Expand only the elements whose behavior needs more room.
+5. Add examples that illustrate one rule at a time.
+6. Audit defaults, constraints, failures, ignored input, and validation gaps.
+
+For each field, option, command, or file, record the identity facts that apply:
+
+- Exact name and syntax
+- Type or accepted values
+- Required state and default
+- Scope, location, or base path
+
+Then record the behavior facts that apply:
+
+- Behavior and side effects
+- Constraints
+- Failure and ignored-input behavior
+- What validation catches and misses
+
+Don't create empty sections or table columns for facts that don't apply.
+
+### Inventory, then expand
+
+Open with a complete table or list. Expand an item below the inventory only when its behavior can't fit cleanly in the overview. Put the expansion under the item's exact name so the table of contents works as an index.
+
+For field and option references, `Field | Contract` is the safe table shape when definitions need sentences. Add more columns only when every cell is short and comparable. If columns split one coherent definition into fragments or wrap badly at a narrow width, use fewer columns or move the detail below the inventory.
+
+### Examples and edge cases
+
+An example illustrates one mapping, rule, or result. It doesn't become a sequence the reader follows or a narrative about completing a task. A complete example may follow the contract when seeing the elements together helps lookup.
+
+Put the concrete default path or value in the primary slot. Put environment variables and uncommon overrides afterward.
+
+State the observable consequence of a limit. If OpenSpec ignores a misspelled field, say that validation passes and the field has no effect. If a value falls back, name the value OpenSpec uses.
+
+## Two surfaces
+
+OpenSpec spans the terminal and the AI chat, and readers mix them up. Label every snippet:
+
+```
+In your terminal:
+  openspec init
+
+In your AI chat:
+  /opsx:propose add-rate-limit
+```
+
+Where the reader could doubt it worked (a fresh install, a first run, a command with no output of its own), end with the concrete success signal: the line the command prints, the file that now exists, what the agent says next. Where the outcome is obvious, stop; an unneeded success line is noise.
+
+## Authoring mechanics
+
+Pages are plain markdown; GitHub and the site both render them. JSX components (`<Callout>`, `<Tabs>`, `<details>`) don't render; never use them.
+
+- **Install commands**: write the global npm command once, in a fence whose language is `npm`; the site renders it as npm/pnpm/yarn/bun tabs with a copy button per tab (`remarkNpm` in `website/source.config.ts`, which also persists the reader's choice across blocks). On GitHub the fence degrades to the plain npm command.
+- **Callouts**: GitHub-style blockquote alerts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`); GitHub styles them natively and the site renders them as callouts (`remarkGfmAlert` in `website/lib/remark-gfm-alert.ts`). Never place one directly under the page title: the sync lifts the leading blockquote into the page description.
+
+## What earns a developer's trust
+
+- Show the real command and its real output, trimmed honestly. A retouched output is a lie the reader catches on their first run.
+- No hype and no comfort adjectives: easy, simple, just, powerful, seamless, robust. Three lines that show the thing beat any adjective about it.
+- State limits plainly. A named limitation builds more trust than praise: "Your assistant does need to be able to run shell commands; a few IDE integrations can't."
+- Don't generalize. Where you're tempted to write what OpenSpec "helps" with, write what actually happens: which file appears, what the diff shows, what the agent does next.
+- Don't define what you can show. An unfamiliar term whose instances explain themselves (the workflow list: propose, explore, apply...) is introduced by showing the instances with one-phrase glosses; the abstraction can wait.
+- Exact names: flags, paths, config keys, and versions as they exist in source, linked to their canonical page on first use.
+
+## Naming and terms
+
+- One term per concept, the glossary's term if the tree has one; today that means "skills", never "slash commands".
+- No invented taxonomy. Product terms (spec, change, delta, profile, store) name real things; use them freely. Any other organizing word in a heading or goal ("layers", "levers", "pillars") must pass one test: would a reader use it to ask their own question? If not, write the reader's question or the plain enumeration ("What you can customize", never "The three layers").
+- Examples invoke workflows by skill: the ask that triggers it ("ask your agent to propose a change") or the skill's name (`openspec-propose`), which is the same in every tool. A command spelling (`/opsx:propose`) appears only as a labeled per-tool example, never as the generic instruction; commands are headed for deprecation and their spellings vary per tool.
+- Prefer the shared `.agents/` folder in file-path examples; a tool-specific folder (`.claude/`) appears only when the example is about that tool.
+- Headings lead with a verb when the section is something the reader does ("Initialize your project"). Found content takes a plain noun phrase ("Install methods"). Never a vague verb ("Understand it") and never a pun.
+- If the page carries a one-line job statement under the title (docs-lab uses a `>` blockquote the site lifts into the page description), keep it plain, concrete, and true of the finished page.
+
+## One canonical home
+
+A fact lives on exactly one page; everywhere else links to it. A second copy is a future contradiction. The tree's README says which page owns what; when in doubt, link.
+
+## Exemplars
+
+When unsure how something should scan or sound, match these:
+
+- `docs-lab/start/setup.md`: section shape, inventory-then-expand, enumerable facts on bullets.
+- `docs-lab/start/installation.md`, the Uninstalling section: multi-step tasks with bold numbered lead-ins.

.github/dependabot.yml

@@ -1,5 +1,14 @@
 version: 2
 
+# Dependabot does not manage two dependency surfaces in this repo:
+#   1. pnpm `overrides` (pnpm-workspace.yaml + package.json, root and website) —
+#      transitive version pins that remediate advisories Dependabot can't otherwise
+#      reach. It never bumps or removes these; each carries an inline advisory
+#      comment noting the removal condition (see pnpm-workspace.yaml).
+#   2. The Nix flake (flake.nix / flake.lock). Update nixpkgs manually with
+#      `nix flake update`; there is no Dependabot ecosystem for Nix. Note that the
+#      pnpmDeps FOD hash in flake.nix must be regenerated on any root lockfile change.
+
 updates:
   # Published CLI package
   - package-ecosystem: npm
@@ -16,6 +25,17 @@ updates:
       semver-minor-days: 7
       semver-patch-days: 3
     open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "@types/node"
+        update-types:
+          - version-update:semver-major
+      # Chalk 6 requires Node 22, while the published CLI supports Node 20.19.
+      - dependency-name: "chalk"
+        update-types:
+          - version-update:semver-major
+      - dependency-name: "typescript"
+        update-types:
+          - version-update:semver-major
     commit-message:
       prefix: chore
       include: scope
@@ -46,6 +66,13 @@ updates:
       semver-minor-days: 7
       semver-patch-days: 3
     open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "@types/node"
+        update-types:
+          - version-update:semver-major
+      - dependency-name: "typescript"
+        update-types:
+          - version-update:semver-major
     commit-message:
       prefix: chore
       include: scope

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
           persist-credentials: false
 
       - name: Check for Nix-related changes
-        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4
         id: filter
         with:
           filters: |
@@ -39,6 +39,7 @@ jobs:
               - 'flake.lock'
               - 'package.json'
               - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
               - 'scripts/update-flake.sh'
               - '.github/workflows/ci.yml'
 
@@ -76,7 +77,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -131,7 +132,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -253,13 +254,13 @@ jobs:
 
       - name: Setup pnpm
         if: steps.changed-changesets.outputs.has_changesets == 'true'
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
         if: steps.changed-changesets.outputs.has_changesets == 'true'
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20.19.0'
+          node-version: '24'
           cache: 'pnpm'
 
       - name: Install dependencies

.github/workflows/release-prepare.yml

@@ -5,9 +5,11 @@ on:
     branches: [main]
   workflow_dispatch: # manually cut a beta prerelease from main
 
+# Floor for both jobs. The prepare job widens this to pull-requests: write for
+# the Version Packages PR; the beta job only tags/releases + publishes via OIDC
+# and needs no PR access, so it inherits this narrower default.
 permissions:
   contents: write
-  pull-requests: write
   id-token: write # Required for npm OIDC trusted publishing
 
 concurrency:
@@ -18,6 +20,10 @@ jobs:
   prepare:
     if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'push'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write # changesets opens/updates the Version Packages PR
+      id-token: write # Required for npm OIDC trusted publishing
     steps:
       # Generate GitHub App token first - used for checkout and changesets
       # This allows git operations to trigger CI workflows on the version PR
@@ -34,7 +40,7 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app-token.outputs.token }}
 
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -47,13 +53,17 @@ jobs:
       # Opens/updates the Version Packages PR; publishes when the Version PR merges
       - name: Create/Update Version PR
         id: changesets
-        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1
+        uses: changesets/action@8488615a623b1b9c987934bb89eae8af6a946ac1 # v2.1.1
         with:
-          title: 'chore(release): version packages'
-          createGithubReleases: true
+          github-token: ${{ steps.app-token.outputs.token }}
+          pr-title: 'chore(release): version packages'
+          create-github-releases: true
+          # Preserve the v1 release path: pushes use the GitHub App token from
+          # checkout so version PR updates trigger their normal CI workflows.
+          push-with-git-cli: true
           # Use CI-specific release script: relies on version PR having been merged
           # so package.json already contains the bumped version.
-          publish: pnpm run release:ci
+          publish-script: pnpm run release:ci
         env:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           # npm authentication handled via OIDC trusted publishing (no token needed)
@@ -74,7 +84,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:

.github/workflows/security.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - '**/package.json'
       - '**/pnpm-lock.yaml'
+      - '**/pnpm-workspace.yaml'
       - '.github/workflows/security.yml'
   pull_request:
     branches: [main]
@@ -50,7 +51,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       # No dependency cache: `pnpm audit` reads the lockfile, nothing is installed,
       # so a cache-save step would fail on the missing store path.
@@ -88,3 +89,32 @@ jobs:
         if: ${{ !cancelled() }}
         continue-on-error: ${{ github.event_name == 'pull_request' }}
         run: pnpm audit --audit-level high --dir website
+
+  # The website keeps its own lockfile and is never installed or built elsewhere
+  # in CI, so a website/package.json change — e.g. a security override — that is
+  # not reflected in website/pnpm-lock.yaml goes unnoticed: the override you think
+  # patches an advisory may not be in the committed graph at all, and `pnpm audit`
+  # would happily audit the stale (possibly still-vulnerable) tree. A frozen-lockfile
+  # install fails fast on that drift. Root drift is already caught by the
+  # `--frozen-lockfile` installs in ci.yml; this closes the same gap for the website.
+  # `--ignore-scripts` skips sharp's native build (irrelevant to lockfile validation
+  # and the usual source of install flake).
+  website-lockfile:
+    name: Website Lockfile Drift
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.19.0'
+
+      - name: Verify website lockfile matches package.json
+        run: pnpm install --frozen-lockfile --ignore-scripts --dir website

CHANGELOG.md

@@ -1,5 +1,185 @@
 # @fission-ai/openspec
 
+## 1.12.0
+
+### Minor Changes
+
+- [#1171](https://github.com/Fission-AI/OpenSpec/pull/1171) [`44a39eb`](https://github.com/Fission-AI/OpenSpec/commit/44a39eb24b7ca0f2cf08df697888c3b1e9818a5a) Thanks [@aleksandr4842](https://github.com/aleksandr4842)! - Add SourceCraft Code Assistant as a supported tool for project skills and commands in its VS Code extension.
+
+- [#1713](https://github.com/Fission-AI/OpenSpec/pull/1713) [`db03c6c`](https://github.com/Fission-AI/OpenSpec/commit/db03c6c4b0ef8a05308497482bdc5fc4dd151569) Thanks [@Marzx13](https://github.com/Marzx13)! - ### New Features
+  
+  - Add `openspec validate --report findings` for explicit bulk scopes. It returns only items with errors, warnings, or information while keeping full-run totals and exit codes. JSON output identifies the report and its scope; human output includes each finding's path and message. The default full report is unchanged.
+
+### Patch Changes
+
+- [#1710](https://github.com/Fission-AI/OpenSpec/pull/1710) [`a4fcdbe`](https://github.com/Fission-AI/OpenSpec/commit/a4fcdbece6f4f7ce86fbd57230be2753945020ba) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Report delta merge conflicts during validation as informational findings, including in successful text reports, without changing validation exit codes. Preserve filesystem read errors so unreadable main specs are not mistaken for missing specs.
+  
+  Keep the validation report intact when the advisory merge preflight cannot resolve its inputs.
+
+- [#1017](https://github.com/Fission-AI/OpenSpec/pull/1017) [`b976106`](https://github.com/Fission-AI/OpenSpec/commit/b976106d954a0eebbf94ec26b056208968313a4d) Thanks [@DanRioDev](https://github.com/DanRioDev)! - Improve explore mode guidance so it asks more useful dependency-aware questions, recommends defaults, and checks the codebase before asking for facts the repo can answer.
+
+- [#1737](https://github.com/Fission-AI/OpenSpec/pull/1737) [`98bf53e`](https://github.com/Fission-AI/OpenSpec/commit/98bf53e59ec91eb71de4ed0e8036459de7352585) Thanks [@clay-good](https://github.com/clay-good)! - Guide propose and fast-forward workflows to inspect relevant project code, tests, and documentation before drafting artifacts, so plans reflect the existing implementation instead of deferring basic discovery to implementation tasks.
+
+- [#786](https://github.com/Fission-AI/OpenSpec/pull/786) [`0296401`](https://github.com/Fission-AI/OpenSpec/commit/0296401b823726ae6a8d8505104e95c7899b3056) Thanks [@Br1an67](https://github.com/Br1an67)! - Preserve empty OpenSpec directories in Git after initialization. Re-running init restores missing directory markers without overwriting existing files or following marker symlinks.
+
+- [#1725](https://github.com/Fission-AI/OpenSpec/pull/1725) [`cd72444`](https://github.com/Fission-AI/OpenSpec/commit/cd724449aced1655eb513f3207600bec074c7588) Thanks [@aron-intframe](https://github.com/aron-intframe)! - `openspec init` and `openspec update` now share the IDE restart hint: "Restart your IDE to refresh commands." or "Restart your IDE to refresh skills." The message also covers removing workflows, without claiming that new files were generated.
+
+## 1.11.0
+
+### Minor Changes
+
+- [#1301](https://github.com/Fission-AI/OpenSpec/pull/1301) [`a7353ae`](https://github.com/Fission-AI/OpenSpec/commit/a7353aea9a0b23762602badf5055a157a76f62b1) Thanks [@m-tanner](https://github.com/m-tanner)! - Add `openspec status --all`, which reports every active change in one process instead of one CLI spawn per change. `--all --json` emits a single `{ "changes": [ <status>, ... ], "root" }` envelope sorted by change name; a change that fails to load contributes `{ "changeName", "status": [diagnostic] }` in place rather than aborting the sweep. A partial failure exits 1 in both text and JSON modes while preserving the complete JSON envelope. Mutually exclusive with `--change`.
+
+- [#980](https://github.com/Fission-AI/OpenSpec/pull/980) [`dd7cea3`](https://github.com/Fission-AI/OpenSpec/commit/dd7cea3ffed4a22421dce02f54c37c4f076b44f0) Thanks [@bsmedberg-xometry](https://github.com/bsmedberg-xometry)! - show: add `--diff`, which renders each delta requirement against the requirement it replaces in the main spec instead of reprinting the whole block. A MODIFIED requirement has to carry every scenario it keeps, so reviewers could not see what a change actually altered without diffing files by hand. `openspec show <change> --diff` now prints a colorized unified diff per requirement (additions green, removals red), the full text of ADDED requirements, the authored Reason/Migration text of REMOVED ones, and FROM/TO for RENAMED ones; a requirement that is renamed and modified in the same delta is diffed against its old name. `--json --diff` keeps the existing payload shape and adds each applicable `diff` and `warning` field to MODIFIED deltas only. Main specs resolve against the same root as the change, so `--store <id>` diffs against that store. Without `--diff`, `openspec show <change>` prints exactly what it printed before.
+
+### Patch Changes
+
+- [#830](https://github.com/Fission-AI/OpenSpec/pull/830) [`109f81f`](https://github.com/Fission-AI/OpenSpec/commit/109f81f17d3bb99eb6fb2c9a33ec9e8ab0680bb2) Thanks [@alfred-openspec](https://github.com/alfred-openspec)! - Write Antigravity skills and workflows to `.agents/`, arbitrate its shared skill tree with other tools, and safely migrate an existing `.agent/` install.
+
+- [#1712](https://github.com/Fission-AI/OpenSpec/pull/1712) [`04b37ac`](https://github.com/Fission-AI/OpenSpec/commit/04b37ac1d5c852385d2effbff196ddb4fdd1700c) Thanks [@Marzx13](https://github.com/Marzx13)! - archive: preserve a requirement's original position when renaming it instead of moving the renamed block to the end of the spec.
+
+- [#1716](https://github.com/Fission-AI/OpenSpec/pull/1716) [`7010e26`](https://github.com/Fission-AI/OpenSpec/commit/7010e268907598c385eb6686699928fbd5a3a733) Thanks [@aymanxdev](https://github.com/aymanxdev)! - explore: require explicit, scope-bound confirmation before the skill uses any command or tool that can create, edit, move, or delete a file. The explore skill's guardrails let "if the user asks" cover answers to its own clarifying questions, so an agent could treat a design discussion as a go-ahead and start creating schemas or editing `openspec/config.yaml` uninvited. The skill and the `/opsx:explore` command now instruct the agent to name the proposed artifacts or files, ask a direct yes/no question, and wait for confirmation in a separate message before writing. Read-only commands and tools remain available without confirmation, and expanding the confirmed scope requires another confirmation.
+
+- [#1199](https://github.com/Fission-AI/OpenSpec/pull/1199) [`ab81a4b`](https://github.com/Fission-AI/OpenSpec/commit/ab81a4b43a7bd769b1d2a33457b7b708b8c52516) Thanks [@leo-ar](https://github.com/leo-ar)! - Improve Fish completions so command, subcommand, flag, and indexed positional completions no longer fall back to filesystem suggestions unless the target is a real path.
+
+- [#1010](https://github.com/Fission-AI/OpenSpec/pull/1010) [`e5e350d`](https://github.com/Fission-AI/OpenSpec/commit/e5e350d04b5d635b56846f46a212b097cd00eeb6) Thanks [@Dansyuqri](https://github.com/Dansyuqri)! - Draw explore-mode diagrams with plain ASCII. The worked examples in the explore skill and `/opsx:explore` command used Unicode box-drawing, arrow, and marker glyphs, whose display width varies across terminals, fonts, and locales. Agents copied the style, causing padded boxes and aligned tables to drift.
+
+- [`2fa679f`](https://github.com/Fission-AI/OpenSpec/commit/2fa679f180424d46ce7d8789eb85138397844a89) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Make `schema init --default` validate and stage config changes before installing a schema, and roll back both files if either install fails. The staging and backup directories it creates are excluded from schema discovery, so they are never offered as real schemas.
+
+- [#1671](https://github.com/Fission-AI/OpenSpec/pull/1671) [`126c5d6`](https://github.com/Fission-AI/OpenSpec/commit/126c5d6c59d63b7e70314bcc776104c7cc548819) Thanks [@kitimark](https://github.com/kitimark)! - `openspec validate` now reports a `## Purpose` that is still the placeholder archive writes for a new capability, instead of passing it. The placeholder is longer than the 50-character brevity floor, so until now the one check meant to catch a Purpose nobody wrote was satisfied by the exact text saying nobody wrote one — a spec whose Purpose read `Does stuff.` failed `--strict` while a spec whose Purpose said nothing at all passed. A capability could carry the placeholder indefinitely while every command reported success.
+
+  It is a warning, so a project that already has placeholders on disk keeps validating by default and only `--strict` fails. The message says to edit the main spec directly, since a `## Purpose` in a delta is read only when the capability is created and cannot replace an existing one.
+
+  Detection is narrow. The placeholder archive generates is recognised through the same definition that writes it, wherever it appears in the Purpose. Otherwise only a `TBD` or `TODO` opening the Purpose counts, so `The retry budget is TBD pending benchmarks` is still a valid Purpose and a word like `TBDs` is not a marker. Fenced code inside the Purpose is quoted material rather than the Purpose speaking, so a spec that documents the placeholder keeps passing. An empty Purpose is unchanged, and a Purpose reported as a placeholder is no longer also reported as too brief, so a bare `TBD` yields one finding rather than two.
+
+  `openspec archive` is unaffected: it validates rebuilt specs without `--strict`, so a spec archive writes still passes the validation it would have passed before, and the text archive writes is unchanged.
+
+## 1.10.0
+
+### Minor Changes
+
+- [#1685](https://github.com/Fission-AI/OpenSpec/pull/1685) [`c747ed1`](https://github.com/Fission-AI/OpenSpec/commit/c747ed1f34459ca6bc15d43ad9f68dfdf7750875) Thanks [@clay-good](https://github.com/clay-good)! - Add `openspec init --language <language>` to configure the language used for artifacts in new projects.
+
+### Patch Changes
+
+- [#1704](https://github.com/Fission-AI/OpenSpec/pull/1704) [`7276c6c`](https://github.com/Fission-AI/OpenSpec/commit/7276c6c26832f699a63544302d38b1af8ddb9844) Thanks [@clay-good](https://github.com/clay-good)! - Drop the npm `postinstall` script. Its only job was printing a one-line tip about opt-in shell completions, but shipping any install script made `npm install -g @fission-ai/openspec` emit an `allow-scripts` warning that reads as a packaging fault (and `npm approve-scripts` then fails with `ENOMATCH` on a global install, since it looks in the local project). The tip now prints from the CLI on its first run — to stderr, in an interactive terminal, once, and not at all if you already have completions installed — and the published package declares no `preinstall`/`install`/`postinstall` script, so a registry install runs no OpenSpec code. Suppress the tip with `OPENSPEC_NO_COMPLETIONS=1`.
+
+- [#1656](https://github.com/Fission-AI/OpenSpec/pull/1656) [`a72a74d`](https://github.com/Fission-AI/OpenSpec/commit/a72a74de6571c26fd79a193bb33fa3b8e1a767fb) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - `openspec update` now suggests restarting an IDE only when it updates an IDE-resident tool. CLI tools such as Claude Code, Codex, and Gemini CLI no longer show an unnecessary restart hint.
+
+- [#1703](https://github.com/Fission-AI/OpenSpec/pull/1703) [`9643888`](https://github.com/Fission-AI/OpenSpec/commit/9643888a7525467c7a076bfec9bb075910e78bb8) Thanks [@clay-good](https://github.com/clay-good)! - Point the spec-driven `specs` instruction's main-spec read and edit at the store-aware root. It named `openspec/specs/<capability-path>/spec.md`, a path relative to the current directory, for both step 1 of the MODIFIED workflow ("locate the existing requirement") and the edit that fixes a leftover `TBD` Purpose. When the change lives in a store — whether selected with `--store`, a project `store:` pointer, or a global default store — the main spec is under the store root, so that read missed it, or silently returned a different capability when a local one happened to share the name, and the MODIFIED block was then copied from the wrong requirement. Both operations now use `<planningHome.root>/openspec/specs/...`, the root already returned by `openspec instructions ... --json` and the same convention the sync and archive workflows use. Fixes [#1702](https://github.com/Fission-AI/OpenSpec/issues/1702).
+
+- [#1699](https://github.com/Fission-AI/OpenSpec/pull/1699) [`18688c8`](https://github.com/Fission-AI/OpenSpec/commit/18688c8b27820da3435a47a7f11e90073724b728) Thanks [@clay-good](https://github.com/clay-good)! - archive: tell the author how to retire a capability when the emptied spec also holds content the merge cannot account for. That combination printed only "Spec must have at least one requirement" and no guidance at all; the abort now names the blocking lines and reports a `retire_capabilities` marker that is present but cannot be honored. Authored content quoted in those messages - the blocking lines, and the marker's own reason, which `openspec validate` prints too - is stripped of control characters and bounded in length before it reaches the terminal.
+
+- [#1660](https://github.com/Fission-AI/OpenSpec/pull/1660) [`7da3f34`](https://github.com/Fission-AI/OpenSpec/commit/7da3f34fb66d602bd987caa7dddcf3d6621e7d44) Thanks [@clay-good](https://github.com/clay-good)! - Require generated tasks to state how their completion can be verified.
+
+## 1.9.0
+
+### Minor Changes
+
+- [#1622](https://github.com/Fission-AI/OpenSpec/pull/1622) [`59c16a4`](https://github.com/Fission-AI/OpenSpec/commit/59c16a4461254ed984d1d5e29d00af1a5610035a) Thanks [@clay-good](https://github.com/clay-good)! - ### New Features
+
+  - **Command Code command adapter** — Command Code is now a first-class, adapter-backed tool. `openspec init` generates OpenSpec commands under `.commandcode/commands/opsx-<id>.md` (invoked as `/opsx-<id>`) alongside the skills under `.commandcode/skills/`, matching Command Code's documented custom-slash-command surface.
+
+- [#1613](https://github.com/Fission-AI/OpenSpec/pull/1613) [`42d7f67`](https://github.com/Fission-AI/OpenSpec/commit/42d7f673bc5f13378451267c8a9d0c23f63a2d1a) Thanks [@Angelthebestone](https://github.com/Angelthebestone)! - ### New Features
+
+  - **Command Code support** — `openspec init` now supports Command Code as an adapterless skills-only tool. It installs the OpenSpec skills under `.commandcode/skills/` and invokes them as `/openspec-*` commands, matching Command Code's native skill surface.
+
+- [#1604](https://github.com/Fission-AI/OpenSpec/pull/1604) [`83be9d1`](https://github.com/Fission-AI/OpenSpec/commit/83be9d113e8310789c281f7c8a00ed4fad191dd5) Thanks [@clay-good](https://github.com/clay-good)! - Add `openspec validate --archived`: an opt-in check that every change under `changes/archive/` has all of its `tasks.md` checkboxes ticked, exiting non-zero if any are unchecked. This surfaces changes that were archived with unfinished work — which the normal validate flow never catches, because it only looks at active changes — and is meant for a pre-commit or CI hook ([#205](https://github.com/Fission-AI/OpenSpec/issues/205)). It is a standalone scope: it does not alter any existing `validate` invocation and does not re-validate already-applied spec deltas.
+
+### Patch Changes
+
+- [#1530](https://github.com/Fission-AI/OpenSpec/pull/1530) [`bf5099e`](https://github.com/Fission-AI/OpenSpec/commit/bf5099e39fdb5d7bde2adc84f49ea93afd7463e9) Thanks [@clay-good](https://github.com/clay-good)! - Apply workflow now tells agents to surface unexpected scope instead of hiding it. When a task needs work beyond what the spec describes, the `/opsx:apply` skill and command guidance direct the agent to pause and report the added scope rather than silently narrowing, deferring, or simplifying away specified behavior, and to mark a task complete only when its specified behavior is fully implemented. Fixes [#1529](https://github.com/Fission-AI/OpenSpec/issues/1529).
+
+- [#1603](https://github.com/Fission-AI/OpenSpec/pull/1603) [`9ae75c8`](https://github.com/Fission-AI/OpenSpec/commit/9ae75c86efe5d326ffa7ca5a3fd64b1f1e7728c2) Thanks [@clay-good](https://github.com/clay-good)! - `openspec archive` no longer writes terminal escape codes to a redirected or captured stdout. Its confirmation prompts and the no-argument change picker drew their live UI with ANSI cursor-move sequences even when stdout was not a terminal — noise in a redirected log, and in some non-interactive hosts an unbounded render loop that could grow the captured output until the disk filled. When stdout (or stdin) is not a terminal, archive now reads the confirmations as plain text, and a no-argument run asks you to pass a change name up front instead of drawing a menu. Piped answers (`printf 'y\n' | openspec archive …`) and `--yes` behave as before, and interactive terminals are unchanged. Fixes [#1526](https://github.com/Fission-AI/OpenSpec/issues/1526).
+
+- [#1528](https://github.com/Fission-AI/OpenSpec/pull/1528) [`9425897`](https://github.com/Fission-AI/OpenSpec/commit/942589741de35f1b8896b410d7ea70295bb137c0) Thanks [@Marzx13](https://github.com/Marzx13)! - Canonicalize rebuilt specs to end with exactly one final LF. Previously a spec whose `## Requirements` section was last was rebuilt with a trailing blank line (`\n\n`), which failed Markdown whitespace checks after sync or archive. Internal spacing and content after the Requirements section are unchanged.
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - Preserve the blank lines around a spec's `## Requirements` heading when syncing a delta. `openspec archive` rebuilt `openspec/specs/<capability>/spec.md` by joining its slices with a bare newline, so the blank lines that surround the heading were dropped and the resulting file failed Markdown whitespace checks. The rebuild now keeps that spacing intact. Fixes [#1625](https://github.com/Fission-AI/OpenSpec/issues/1625). Thanks [@jwang513](https://github.com/jwang513)! ([#1637](https://github.com/Fission-AI/OpenSpec/pull/1637))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate --all` and `openspec list --json` no longer silently pass when run outside an OpenSpec project. From a directory with no root they used to resolve the current directory as an implicit root, exit 0, and report empty results — a false pass for CI and agents. Bulk validation (`--all`, `--changes`, `--specs`) and `list` now require an existing root (the `openspec/project.md` fallback for legacy projects is kept), while direct validation and other intentional implicit-root workflows are unchanged. Thanks [@clay-good](https://github.com/clay-good)! ([#1612](https://github.com/Fission-AI/OpenSpec/pull/1612))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - Label the `update` workflow in the `openspec config` workflow picker. The checklist had friendly labels for 11 of the 12 workflows but was missing `update`, so that row — one of the six core workflows every user sees — fell back to its raw id with a placeholder description. The update-change template's stale "expanded-profile" wording is also reworded to "optional". Fixes [#1627](https://github.com/Fission-AI/OpenSpec/issues/1627). Thanks [@clay-good](https://github.com/clay-good)! ([#1632](https://github.com/Fission-AI/OpenSpec/pull/1632))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec schema fork` now preserves the source schema's YAML formatting. Renaming a forked `schema.yaml` round-tripped through a parse/re-serialize step that dropped comments, could rewrite block-scalar style (a literal `|` folded to `>`), and reordered keys, so the fork no longer matched its source. The rename now edits the document in place via the YAML Document API, leaving comments, scalar style, and key order untouched. Thanks [@clay-good](https://github.com/clay-good)! ([#1607](https://github.com/Fission-AI/OpenSpec/pull/1607))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec schemas` now resolves through the canonical OpenSpec root-selection precedence instead of always reading from the current directory. It accepts `--store <id>`, rejects `--store-path` like the other store-aware commands, and returns the shared machine-readable diagnostics on JSON failures, while preserving the existing human output and bare JSON array on success. Thanks [@Patodo](https://github.com/Patodo)! ([#1616](https://github.com/Fission-AI/OpenSpec/pull/1616))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate` now warns on ambiguous task numbering in `spec-driven` changes: a task ID duplicated at full depth (including across resolved task files), or a task whose leading number disagrees with its enclosing `## N.` group. Numeric-looking text outside numbered groups is ignored, and custom schemas are unchanged until they opt in. The checks run across direct, bulk, and deprecated change validation. Closes [#1520](https://github.com/Fission-AI/OpenSpec/issues/1520). Thanks [@alectimison-maker](https://github.com/alectimison-maker)! ([#1523](https://github.com/Fission-AI/OpenSpec/pull/1523))
+
+- [#1522](https://github.com/Fission-AI/OpenSpec/pull/1522) [`07dea6e`](https://github.com/Fission-AI/OpenSpec/commit/07dea6ed2faf71c8b9f4944d64246f2ff39eeffc) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Don't let a legacy Codex upgrade hijack the vendor-neutral `agents` target** — `openspec update` no longer overwrites an existing `.agents` skills tree (and its ownership marker) when Codex is detected only from leftover global `~/.codex/prompts`. Because Codex and the vendor-neutral `agents` target share `.agents/skills`, a project that used the `agents` target could have its generic skills silently rewritten with Codex-specific syntax and its target flipped to Codex on the next `update --force`. The legacy-upgrade path now respects the established owner of a shared skills directory, matching the one-writer rule `openspec init` already applies. When an upgrade is skipped this way, that tool's repo-local legacy files (e.g. `.codex/prompts/openspec-*.md`) are also preserved rather than cleaned up, since no replacement was written to take their place. A genuine first-time Codex upgrade (no `.agents` tree yet) is unaffected.
+
+- [#1521](https://github.com/Fission-AI/OpenSpec/pull/1521) [`c751b3d`](https://github.com/Fission-AI/OpenSpec/commit/c751b3da52a7f06d6662a8673feff4685566cdd4) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Stop silently dropping unlabeled scenarios on archive** — `openspec validate` and `openspec archive` now recognize every level-4 (`####` followed by whitespace) child of a requirement as a scenario, matching how the spec is counted elsewhere. Before, the scenario-loss guard only recognized headers written exactly as `#### Scenario:`, so a `MODIFIED` requirement that dropped a differently-labeled child (for example `#### Edge case`) passed validation and was then permanently deleted by archive with no warning. Both paths now agree, so the loss is caught at authoring time. Scenario names are normalized when comparing (an optional `Scenario:` prefix and a CommonMark closing `#` run are ignored), so simply relabeling a scenario is not mistaken for dropping one.
+
+- [#1610](https://github.com/Fission-AI/OpenSpec/pull/1610) [`17581c1`](https://github.com/Fission-AI/OpenSpec/commit/17581c11edf6b27ef18be7be1e4dcc06c81a3fff) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - `openspec init` now suggests an IDE restart only when an IDE-resident tool such as Cursor, GitHub Copilot, Continue, or Cline was configured. CLI tools like Claude Code, Codex, and Gemini CLI no longer show the hint, since their commands work as soon as the files exist.
+
+- [#1609](https://github.com/Fission-AI/OpenSpec/pull/1609) [`804427b`](https://github.com/Fission-AI/OpenSpec/commit/804427b6ff3f3b35b542365ba8b32e183fce3287) Thanks [@clay-good](https://github.com/clay-good)! - Suppress the first-run telemetry disclosure notice when `--json` is used. On a
+  first-ever run the notice was written to stdout and could break `--json`
+  consumers; it is now deferred to the first later non-JSON run, keeping `--json`
+  output valid while still guaranteeing the disclosure.
+
+## 1.8.0
+
+### Minor Changes
+
+- [#1303](https://github.com/Fission-AI/OpenSpec/pull/1303) [`1aa0f2a`](https://github.com/Fission-AI/OpenSpec/commit/1aa0f2abfc19f2487f5b8566e6eb3bf15f41c20a) Thanks [@solanab](https://github.com/solanab)! - Add the vendor-neutral `agents` target: `openspec init --tools agents` installs the workflow skills to `.agents/skills/openspec-*/SKILL.md`, the shared location AGENTS.md-compatible assistants read. It is skills-only, so no slash commands are generated. Because `agents` is now a real target, `--tools all` includes it and creates `.agents/skills/` where it previously did not.
+
+- [#1274](https://github.com/Fission-AI/OpenSpec/pull/1274) [`7a4a745`](https://github.com/Fission-AI/OpenSpec/commit/7a4a745d803b698c34947eda6d73b5a24aebb58c) Thanks [@NicoAvanzDev](https://github.com/NicoAvanzDev)! - Generate GitHub Copilot coding agent setup and custom agent files during `openspec init` and keep them synchronized during `openspec update`.
+
+- [#1214](https://github.com/Fission-AI/OpenSpec/pull/1214) [`161f945`](https://github.com/Fission-AI/OpenSpec/commit/161f9454a372aab67c495d780928bba89c829f3e) Thanks [@showms](https://github.com/showms)! - Add MiniMax Code as a global skills-only tool target.
+
+- [#1518](https://github.com/Fission-AI/OpenSpec/pull/1518) [`568e56c`](https://github.com/Fission-AI/OpenSpec/commit/568e56c67231dbe2447aca4f0e7995c05ada95a3) Thanks [@clay-good](https://github.com/clay-good)! - ### New Features
+
+  - **Atlassian Rovo Dev CLI** — `openspec init --tools rovodev` installs the OpenSpec workflow skills for Atlassian's Rovo Dev CLI. It is skills-only (no slash commands), written to `.rovodev`.
+
+  ### Bug Fixes
+
+  - **Codex skills now live in the shared `.agents` directory** — `openspec init` and `openspec update` install Codex skills under `.agents/skills/` (the canonical location assistants read) and migrate an existing `.codex` skills directory in place. Files you customized are preserved, not overwritten.
+  - **`openspec status` separates planning from implementation** — status now reports `isPlanningComplete` (every non-skipped planning artifact exists; skipped artifacts count as satisfied without being written) distinctly from overall progress, and its messages no longer imply a change is finished before it has been implemented. `isComplete` is kept as a compatibility alias, so existing scripts keep working.
+
+- [#1517](https://github.com/Fission-AI/OpenSpec/pull/1517) [`73207a6`](https://github.com/Fission-AI/OpenSpec/commit/73207a6f2cd235729ac3fe3cb1e44152b8f63f12) Thanks [@clay-good](https://github.com/clay-good)! - Make GitHub Copilot cloud coding-agent files opt-in. Selecting the `github-copilot` tool no longer silently writes a GitHub Actions workflow into `.github/`; `openspec init` now asks first (default No) and remembers the choice in `openspec/config.yaml` (`githubCopilot.cloudAgent`). Use `--copilot-cloud` / `--no-copilot-cloud` to decide non-interactively.
+
+  - `openspec update` never prompts — it only refreshes cloud files for projects that opted in (or that already have generated cloud files, so existing setups keep working).
+  - Opting out (`--no-copilot-cloud` or `cloudAgent: false`) removes OpenSpec-managed cloud files; a user-customized file is always preserved, never overwritten or deleted.
+  - `init` and `update` now report whether cloud files were written, skipped, or left untouched — and if you already have your own `copilot-setup-steps.yml`, they say it was preserved and that you need to add the OpenSpec install step by hand.
+
+- [#1484](https://github.com/Fission-AI/OpenSpec/pull/1484) [`521ee33`](https://github.com/Fission-AI/OpenSpec/commit/521ee33e6ece269241b45e08017ee60f13fdef08) Thanks [@clay-good](https://github.com/clay-good)! - Retire a capability when a change removes its last requirement. A change that declares `retire_capabilities: true` in its `.openspec.yaml` (alongside the `schema:` that file requires) may now be archived even when its REMOVED entries take a capability's last requirement: `openspec archive` deletes that capability's main spec instead of aborting with "Spec must have at least one requirement". Without the marker nothing changes — the archive aborts exactly as before, except the message now names the marker as the way out. Retirement happens only when the emptied spec could not have been written at all, every one is named in the archive output, a pasteable `git checkout` is included when the spec lived in the caller's checkout, and `--no-validate` never retires. Archive now also rejects a main spec with duplicate canonical requirement names instead of letting delta reconciliation collapse one of the duplicate blocks. One thing to know before retiring: a capability's spec is the base another change's MODIFIED block is checked against, so an in-flight change that modifies the capability you just retired will keep validating clean and then refuse to archive ("target spec does not exist; only ADDED requirements are allowed for new specs") — close or rework that change alongside the retirement.
+
+### Patch Changes
+
+- [#1502](https://github.com/Fission-AI/OpenSpec/pull/1502) [`ece8660`](https://github.com/Fission-AI/OpenSpec/commit/ece8660d44bd19b86440376327752cda3d7b0717) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate` now treats the English `SHALL`/`MUST` convention as guidance in normal mode, so requirements written in other languages can validate. Strict mode continues to enforce the convention.
+
+- [#1483](https://github.com/Fission-AI/OpenSpec/pull/1483) [`2b3d368`](https://github.com/Fission-AI/OpenSpec/commit/2b3d368539132be6311e55db58899abbf5306b81) Thanks [@clay-good](https://github.com/clay-good)! - Tell the caller which flag to pass when `openspec archive` cannot ask its confirmation questions. An AI agent (or any script) runs the CLI with stdin closed, so every prompt rejects with `@inquirer`'s `User force closed the prompt with 0 null` — the archive aborted with an error that named neither the question nor the flag, and agents burned a turn guessing ([#1479](https://github.com/Fission-AI/OpenSpec/issues/1479)). Each confirmation now reports what it needed and a pasteable rerun that carries the flags you already passed: `openspec archive <name> --skip-specs --yes` stays a `--skip-specs` run, so following the suggestion cannot merge specs you opted out of merging, and a change name that needs quoting gets double quotes, the one form bash, zsh, PowerShell and cmd.exe all read the same way (a name no shell reads literally even quoted — one containing `$`, a backtick, or the `%`/`!` that cmd.exe still expands inside quotes — is left as a `<change-name>` placeholder rather than a command that would target something else). `openspec archive` with no change name used to swallow the same failure, print `No change selected. Aborting.` and exit 0 — success for a run that archived nothing; it now exits 1 asking for a change name, matching how `openspec show` and `openspec validate` already behave without a terminal. The check is reactive — it inspects a prompt that already failed — so answers piped into the command, `--yes`, `--json`, and Ctrl-C all behave exactly as before, and a run that OpenSpec already considers non-interactive (`CI`, `OPEN_SPEC_INTERACTIVE=0`, `--no-interactive`) gets the guidance even when the runner allocated a pty. The onboarding walkthrough, the only generated guidance that tells an agent to run `openspec archive`, now shows `--yes`.
+
+- [#1486](https://github.com/Fission-AI/OpenSpec/pull/1486) [`427abf4`](https://github.com/Fission-AI/OpenSpec/commit/427abf40ac45a9a44f78eb74c81f53f9f4197ccf) Thanks [@clay-good](https://github.com/clay-good)! - Task progress now counts indented sub-tasks. A `tasks.md` whose sub-tasks were unfinished reported `✓ Complete` in `openspec list` and `openspec view`, was missing those tasks from the `openspec instructions apply` list, and archived with no incomplete-task warning, because both checkbox parsers only matched checkboxes at column 0.
+
+  Progress counting and the apply task list now share one parser, so `list`, `view`, `archive` and `apply` agree about which lines of a tasks file are tasks. A checkbox with no text after it is left out of the apply list, which has nothing to act on, but still counts toward every progress number; a file of nothing but such checkboxes now asks to be rewritten rather than reporting itself done. The shared pattern matches every line the two it replaced matched, and more, so task counts can rise but never fall: no change starts reporting less work than before, and archive's incomplete-task warning can only become stricter. Checkboxes are still counted wherever they appear, including inside a code fence, an HTML comment or an indented block, so a `tasks.md` that shows a checklist as a format example can now count that example as work — remove it from the file, or pass `--yes` to archive.
+
+- [#1500](https://github.com/Fission-AI/OpenSpec/pull/1500) [`26bd1d4`](https://github.com/Fission-AI/OpenSpec/commit/26bd1d4e5c6c6ba75bd7d6136424019b2bf89ced) Thanks [@clay-good](https://github.com/clay-good)! - Keep generated workflows on the selected store, handle optional workflow fallbacks safely, and validate synced specs before reporting success.
+
+- [#1490](https://github.com/Fission-AI/OpenSpec/pull/1490) [`45cca5d`](https://github.com/Fission-AI/OpenSpec/commit/45cca5db6137ed209117cc70510eb3e057fb981b) Thanks [@clay-good](https://github.com/clay-good)! - Say before confirmation when archiving a change will delete a note written next to a requirement. A requirement absorbs anything below it that OpenSpec doesn't recognize as a new heading — a note indented by the one to three spaces Markdown allows, for example — so removing or modifying that requirement took the note with it, silently. `openspec archive` now names content the rebuilt spec would actually drop and where to move it to keep it. The merge itself is unchanged: nothing is relocated, because a `#` line inside a scenario looks identical to a note and moving one of those would rewrite the spec wrongly.
+
+- [#1492](https://github.com/Fission-AI/OpenSpec/pull/1492) [`690a27e`](https://github.com/Fission-AI/OpenSpec/commit/690a27e649c4a3325daeb0f6667ebe0f82792179) Thanks [@mc856](https://github.com/mc856)! - `openspec init` and `openspec update` no longer delete the CoStrict and Junie command files they just generated. Legacy cleanup removes artifacts older OpenSpec versions left behind, and two of its patterns named paths the current adapters still write to. CoStrict's was a whole-directory removal of `.cospec/openspec/commands/`, the folder the adapter writes `opsx-<id>.md` into, so every run wiped the directory — including any file the user kept there — while the banner above it read `No user content to preserve`. Junie's `.junie/commands/opsx-*.md` listed its own current output. Cleanup runs before the config migration, so on a config that has no `profile` key yet the missing command files make delivery detection read the project as skills-only and persist that to the global config: the files are not regenerated, and the preference changes for every other project too.
+
+  CoStrict is now a file pattern, `.cospec/openspec/commands/openspec-*.md`, matching the three commands the pre-`opsx` CoStrict integration wrote there (`openspec-proposal.md`, `openspec-apply.md`, `openspec-archive.md`) and the same shape every other file-based tool already uses. Junie's entry is removed outright: Junie support arrived after the slash configurators that wrote `openspec-*` files were deleted, so no OpenSpec version ever created those files there. Genuinely legacy files are still detected and removed, and no other tool's patterns change — they never overlapped their adapter's current output.
+
+- [#1501](https://github.com/Fission-AI/OpenSpec/pull/1501) [`0b20ae3`](https://github.com/Fission-AI/OpenSpec/commit/0b20ae3964283bdcb4e34ea7380770857f6a339c) Thanks [@clay-good](https://github.com/clay-good)! - Keep the propose workflow focused on planning, clarify material ambiguities before creating a change, and hand implementation off to the apply workflow.
+
+- [#1503](https://github.com/Fission-AI/OpenSpec/pull/1503) [`8a3850d`](https://github.com/Fission-AI/OpenSpec/commit/8a3850da735e241c14ad94935463f879b33f21a9) Thanks [@clay-good](https://github.com/clay-good)! - When exploration turns into a new change, generated explore guidance now instructs agents to run `openspec new change` before writing requested artifacts. This preserves the required `.openspec.yaml` metadata instead of letting an agent create an incomplete change directory by hand. After the user accepts a capture, explore also creates the requested artifacts without requiring another workflow command.
+
+- [#1513](https://github.com/Fission-AI/OpenSpec/pull/1513) [`622c509`](https://github.com/Fission-AI/OpenSpec/commit/622c509a1349c3ad9c52cd1a4ee007bd47549204) Thanks [@FasterPHP](https://github.com/FasterPHP)! - Honor `telemetry.enabled` in global config. `false` disables anonymous telemetry and `openspec update` version checks; unset keeps telemetry enabled, and env/CI opt-outs still take precedence.
+
+- [#1499](https://github.com/Fission-AI/OpenSpec/pull/1499) [`9cd845f`](https://github.com/Fission-AI/OpenSpec/commit/9cd845fc459b71486d9f2424c2e1f38e2ca8766e) Thanks [@clay-good](https://github.com/clay-good)! - Keep generated files, specs, archive moves, and local state inside their intended security boundaries without breaking linked monorepo workflows.
+
+- [#1482](https://github.com/Fission-AI/OpenSpec/pull/1482) [`84ebc57`](https://github.com/Fission-AI/OpenSpec/commit/84ebc57cb3f0e91b93484484092fdc2f9fcf39e6) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate <change>` now reports a MODIFIED requirement that omits a scenario the main spec still has — the same loss archive already refuses to apply — so the change fails at authoring time instead of at archive time. A change carrying a stale MODIFIED block will start failing validation; it was already unarchivable, and the message names the scenarios to copy back in.
+
 ## 1.7.0
 
 ### Minor Changes

README.md

@@ -172,6 +172,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
 → **[Customization](docs/customization.md)**: make it yours<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
 → **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 
@@ -248,7 +249,9 @@ OpenSpec collects anonymous usage stats.
 
 We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
 
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+**Opt-out (any one is enough):**
+- `openspec config set telemetry.enabled false` (global config; unset means on)
+- `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1` (env overrides config)
 
 </details>
 

SECURITY.md

@@ -27,7 +27,7 @@ If you think something sits on the boundary, report it and we'll work it out tog
 
 ## Published package contents
 
-The `openspec` npm package publishes `dist/`, `bin/`, `schemas/`, and `scripts/postinstall.js`. Build and test tooling (vite, rollup, vitest, eslint, and their transitive dependencies) is not published. Scanners that read `pnpm-lock.yaml` without separating dependency scope will report advisories for packages that never reach an installed copy of OpenSpec.
+The `openspec` npm package publishes `dist/`, `bin/`, and `schemas/`. Build and test tooling (vite, rollup, vitest, eslint, and their transitive dependencies) is not published. Scanners that read `pnpm-lock.yaml` without separating dependency scope will report advisories for packages that never reach an installed copy of OpenSpec.
 
 You do not have to take that on trust — install the package and look:
 
@@ -42,7 +42,7 @@ ls node_modules | grep -E '^(vite|rollup|vitest|eslint|js-yaml|minimatch)$'   #
 
 | Surface | Behavior |
 | --- | --- |
-| Install script | `scripts/postinstall.js` prints one line suggesting shell completions. It makes no network request, writes no files, and runs no shell. Completions are opt-in via `openspec completion install`. |
+| Install scripts | The package ships no `preinstall`, `install`, or `postinstall` script, so installing it from the npm registry runs no code from OpenSpec. (`prepare` is still declared; npm runs it only for git and local-directory installs, where it builds from source.) Shell completions are opt-in via `openspec completion install`; the CLI prints a one-line tip about them on its first run. |
 | Running other programs | Every call that goes through a shell uses a fixed literal (`which gh`, `gh auth status`). Anything carrying your input — issue text, editor paths, workset commands, the path passed to `openspec update` — uses an argument array, never string interpolation into a shell. On Windows, `.cmd` shims are launched through `cross-spawn`, which escapes arguments rather than concatenating them. |
 | Installing software | `openspec update` can run `npm install -g @fission-ai/openspec@latest` and then re-run `openspec update` with the upgraded CLI. It does this only after you answer yes to a prompt, only for the OpenSpec package itself, only when npm owns the install, and never in CI or a non-interactive shell. A global install lives outside your project, so it runs with your permissions there and executes whatever lifecycle scripts the published package ships. It then reads the installed binary's version back rather than assuming the upgrade took. Decline and it prints the command for you to run yourself. |
 | Telemetry | Command name, OpenSpec version, and a locally generated random UUID. No file paths, no file contents, no environment, no hostname, and IP capture is explicitly disabled. Opt out with `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1`; it is off in CI automatically. |

docs-lab/Notes.md

@@ -0,0 +1,94 @@
+Ok these are my notes when reviewing the different sections/file in docs-lab.
+I've written down my thoughts when looking at these sections so we can think about how to update these
+docs with the feedback in mind.
+
+
+## Start > Overview
+
+Ok the following subtitle here is horrible:
+
+> OpenSpec gives you and your coding agent a shared, reviewable plan before code is written.
+
+This is not a strong value prop in the day and age of plan mode, but other than that i don't think it sells openspec hard enough
+
+OpenSpec is not really about a shared plan for a single session it's about a keeping things on track and aligned for larger features.
+
+what we focus on:
+- making it work for teams
+- git native / things checked into vcs
+- intented behaviour matches the implemented behaviour
+- we help you capture intendede behaviour and match it to the implemented behaviour.
+- it's about correctness, coherence,
+
+Control theory inspiration:
+
+Instructors break down how a system measures its current state, compares it to a desired goal, and adjusts its actions to reduce the difference. 
+
+
+
+## Guides > Explore and idea
+
+I think in this section we should mention:
+
+This is about exploring the problem space, figuring out what problems you care about and diving deeper into them.
+
+It was designed with a very different philiosphy in mind of giving you the freedom to explore the problem space and jump around to different ideas and sections.
+
+It serves a similar purpose to other newer entrees in the fields like superpowers or matt pocock's skills.
+
+We often do see people combining explore with 
+
+Often this is a matter of UX and personal preference. There is no single best skill or method to getting to
+aligment with your agent.
+
+Some people prefer a conversing with a thoughtful design partner, others might prefer being asked questions till they have a good understanding of a problem.
+
+Feel free to customize the explore skills to your needs.
+
+Unrelated to docs:
+
+How do we solve the problem for PM's?
+How do we give them a good home? - what is their job to be done?
+How we efficiently help them achieve that?
+
+- they're basically turning it into tickets?
+
+
+What do we want to get across the line this week?
+
+- The spec drift agent?
+- The dashboard?
+
+- figure out how we use agent session and traces better
+
+
+## From docs-lab drafting (2026-08-19, project-config page)
+
+Product issue, not docs: the installed skills in this repo are stale against the current
+templates. `.claude/skills/openspec-archive-change/SKILL.md` has no `openspec instructions`
+call at all, while `src/core/templates/workflows/archive-change.ts:40` instructs one; the
+installed apply skill also doesn't mention the `context`/`operationGuidance` fields in the
+JSON it reads. So config injection reaches the CLI output, but a stale skill never tells
+the agent to consume it. Running `openspec update` should refresh them.
+
+
+## From docs-lab drafting (2026-08-19, schemas page)
+
+Product issues found while verifying the schema system (all file refs current as of today):
+
+- `schema init` next-steps output prints a command that doesn't exist in that form:
+  "Use with: openspec new --schema <name>" (schema.ts:999); real syntax is
+  `openspec new change <name> --schema <name>`.
+- `openspec new change` spinner prints the hardcoded default schema, not the resolved one
+  (new-change.ts:118): "Creating change 'x' with schema 'spec-driven'..." then "Schema: lite".
+- `schema fork` re-serializes schema.yaml (literal `instruction: |` becomes folded `>`,
+  comments dropped), so diffing a fork against upstream is noisy (schema.ts:706-712).
+- All `openspec schema` subcommands plus `openspec schemas`/`templates` use process.cwd()
+  and take no --store; they silently see nothing when run from a subdirectory, unlike
+  root-resolved commands (schema.ts:383/485/634/768).
+- `suggestSchemas` fuzzy "did you mean" helper exists but is wired to nothing
+  (project-config.ts:420).
+
+Docs follow-up: the community schema catalog lives only in legacy docs/customization.md
+(#community-schemas); customize/schemas.md links to it on GitHub. When the old docs tree
+retires, the catalog needs a docs-lab home.

docs-lab/README.md

@@ -0,0 +1,294 @@
+# docs-lab: parallel rebuild of the OpenSpec docs
+
+**Status: prose is landing page by page; the rest are skeletons** (real headings plus a
+one-line `>` job statement the site lifts into the page description). The live site
+builds from this tree: `website/docs.sync.config.mjs` maps these files to published
+pages, and the old `docs/` tree is no longer used by the site.
+
+This README owns the structure: which pages exist and which page teaches what. The
+reverse view, from a job or message to the page that owns it, is
+[message-map.md](message-map.md). How to
+write them (style, voice, formatting) is the `write-openspec-docs` skill's
+[writing.md](../.agents/skills/write-openspec-docs/writing.md).
+
+## The bar for every page
+
+Every page in docs-lab is written by hand, from scratch. The old `docs/` tree is source
+material for facts, never text to carry over.
+
+What we're after is that the reader gets the idea: every page reads well and makes sense
+to anyone, whatever their level of skill, and above all it is simple. The worst thing we
+can ship is documentation that is cognitively expensive to understand, and that cost
+comes from complicated words, metaphors that don't make sense, random terminology that
+isn't explained, and formatting that gets in the way of reading. Every sentence has a
+purpose and is easy to read and comprehend. If a sentence doesn't pass that test, rewrite
+it or cut it.
+
+## Structure rules
+
+**Folders are the areas.** Every page lives in its area's folder (`start/`,
+`guides/`, `customize/`, `multi-repo/`, `reference/`, `help/`); the root holds only this
+README, `message-map.md`, and `sources.md`. Most folders publish as one
+sidebar group; `guides/` publishes as the Guides group, holding three collapsible
+subgroups (Understanding OpenSpec, Using OpenSpec, Adopting OpenSpec), all expanded
+by default (held back from the site until the pages are drafted: the whole section is
+commented out in `website/docs.sync.config.mjs`, and links to a guide fall back to its
+source on GitHub until it's re-listed). Reference holds three nested
+folders (`reference/architecture/`, `reference/schemas/`, and
+`reference/configuration/`), each publishing as a collapsible group with `index.md` as
+its landing page; the spec-driven schema publishes as a single page
+(`reference/schemas/spec-driven/index.md`) inside the Schemas group. Labels and URLs come from
+`website/docs.sync.config.mjs`, so moving a file never moves a URL.
+
+**Teach once.** The loop (propose, review, apply, archive) has one teacher; every other
+page links, never re-teaches:
+
+- `start/quickstart.md` teaches it as UX: how a human moves a change through the
+  lifecycle, including what archive does on disk.
+- `start/overview.md` shows it as pitch: copy only, no explanation.
+- `guides/concepts.md` stays out of it: the page explains the artifacts (specs, changes,
+  the delta) and links to the quickstart for the loop. Disk paths appear inline with the
+  concept that owns them, never as a layout section.
+- `start/installation.md` owns install; `start/setup.md` owns init and what it writes.
+  The quickstart opens with one prerequisite line linking both and starts at explore.
+
+**Guides vs reference.** `reference/skills.md` holds each skill's contract: arguments,
+what it creates, and what it responds with. Guide pages
+(the Using and Adopting subgroups) own the human judgment for a task, including when
+to reach for each skill, may span several skills, and never restate skill mechanics.
+`reference/architecture/` is the one exception to Reference's look-it-up bar: it's
+explanation content, housed here as a pragmatic home while it's three pages. If it
+grows (say, by absorbing contributor internals), consider giving it its own folder
+and tab.
+
+**Reference is lookup, and named for it.** `reference/schemas/` and
+`reference/configuration/` are contracts: keys, values, types, defaults, and
+locations, on tables and fences. Anything explanatory (what a schema is, what
+to put in config.yaml) lives in Customize or Guides and is linked, never
+restated. Naming follows three rules. A reference folder's landing
+page is titled "Overview"; the folder label already names the group, and
+repeating it double-nests the sidebar. A page documenting one file carries
+concept and filename in the title, concept first, where the concept names the
+file's use, never just its scope ("Project configuration (config.yaml)", "CLI
+settings (config.json)"): the left edge is what the eye disambiguates in the
+sidebar, and the filename keeps the title matching what readers search for and
+see on disk. A file whose name is the term readers use keeps the filename
+alone as the title (`schema.yaml`), and a page owning one product term takes
+that term as the title (`spec-driven`), and
+a page covering several files takes the concept alone (Stores), naming its
+files in the job line.
+
+**FAQ is one-liners.** Every FAQ entry is a short answer, a few lines at most, or a
+router link to the page that owns the topic. How-to content never lives in the FAQ:
+when an answer outgrows a one-liner, it moves to a guide or reference page and the FAQ
+entry becomes a pointer.
+
+## Page index: every page's job
+
+Each goal below is the page's `>` blockquote verbatim, so the promise here is the promise
+readers see. A page delivers exactly its goal: content that outgrows it means splitting
+the page or rewriting the goal in both places, never letting them drift.
+
+### Start: from "what is this?" to your first archived change
+
+| Page | Goal |
+|---|---|
+| [Overview](start/overview.md) | _TODO: emptied 2026-08-21 for a from-scratch rewrite and pulled from the site (`/docs` redirects to Installation meanwhile); the old goal line was dropped as too weak a pitch. Brief in Notes.md._ |
+| [Installation](start/installation.md) | Install the `openspec` CLI on your machine, update it, and uninstall it. |
+| [Set up your project](start/setup.md) | Add OpenSpec to a project: run init, see what it wrote, and adjust it. |
+| [Quickstart](start/quickstart.md) | Your first change on your existing repo, from idea to archived. |
+
+### Guides: understand the system, use it well, bring it to your codebase and team
+
+| Page | Goal |
+|---|---|
+| [Understanding › Concepts](guides/concepts.md) | What the two artifacts are, and how a change describes a diff against current specs. |
+| [Using › Explore an idea](guides/explore.md) | Think it through with the agent before you commit to a proposal. |
+| [Using › Review the plan](guides/review-the-plan.md) | The two-minute pass that catches wrong turns before they're code. |
+| [Using › Apply a change](guides/apply.md) | Run the plan: pacing, context windows, and picking up where you left off. |
+| [Using › Change course](guides/change-course.md) | Revise a change in flight, or decide it's cleaner to start fresh. |
+| [Adopting › Existing codebases](guides/existing-codebases.md) | Bring OpenSpec to a codebase with a lot of code and no specs: where to start, what to backfill, and how specs grow from there. |
+| [Adopting › Teams](guides/teams.md) | Run OpenSpec as a team: what to commit, how a change rides its PR, and when to archive. |
+
+### Customize: make the workflows fit your project
+
+| Page | Goal |
+|---|---|
+| [Overview](customize/overview.md) | Your options for customizing OpenSpec. |
+| [Profiles](customize/profiles.md) | Choose which workflows are installed, and whether they install as skills, commands, or both. |
+| [Project configuration](customize/project-config.md) | Make the workflows plan changes the way you want with a few lines in config.yaml. |
+| [Schemas](customize/schemas.md) | Change what OpenSpec produces: the artifacts, their order, and their templates. |
+
+### Multi-repo (beta): plan across repository boundaries
+
+| Page | Goal |
+|---|---|
+| [Stores (beta)](multi-repo/stores.md) | Plan changes that span repositories: one store, many repos. |
+| [Worksets (beta)](multi-repo/worksets.md) | Open the store and the repos that use it in one editor window, so your agent sees both. |
+
+### Reference: look it up, exact and complete
+
+| Page | Goal |
+|---|---|
+| [Skills](reference/skills.md) | Every OpenSpec skill: arguments, what it creates, and what it responds with. |
+| [CLI](reference/cli.md) | The `openspec` terminal commands. |
+| [Schemas](reference/schemas/index.md) | Every available workflow schema and the artifacts it defines. |
+| [Schemas › schema.yaml](reference/schemas/schema-yaml.md) | Every field of a schema definition, for reading or writing one. |
+| [Schemas › spec-driven](reference/schemas/spec-driven/index.md) | The default workflow's artifacts: their order, their formats, and the change folder they produce. |
+| [Configuration](reference/configuration/index.md) | Every file and setting that changes how OpenSpec behaves, and where each lives. |
+| [Configuration › Project configuration (config.yaml)](reference/configuration/config-yaml.md) | Every field of openspec/config.yaml: the schema, context, and rules this project plans with. |
+| [Configuration › Change metadata (.openspec.yaml)](reference/configuration/change-metadata.md) | The supported fields and validation rules for the metadata stored with each change. |
+| [Configuration › CLI settings (config.json)](reference/configuration/config-json.md) | Every field of config.json: how the openspec CLI behaves on your machine. |
+| [Configuration › Environment variables](reference/configuration/environment-variables.md) | Every environment variable OpenSpec reads. |
+| [Configuration › Stores](reference/configuration/stores.md) | The files behind multi-repo stores: registry.yaml and store.yaml, and which root a command uses. |
+| [Supported tools](reference/supported-tools.md) | Which AI coding tools OpenSpec supports, and each one's command syntax. |
+| [Glossary](reference/glossary.md) | Every OpenSpec term, one line each. |
+| [Architecture](reference/architecture/index.md) (held back from the site until drafted) | How OPSX is built: internals for the curious. |
+| [Architecture › Workflow runs](reference/architecture/workflow-runs.md) | How a workflow run executes, from invocation to written artifacts. |
+| [Architecture › Design decisions](reference/architecture/design-decisions.md) | Why OPSX works the way it does. |
+
+### Help: get unstuck (held back from the site until drafted, see Open TODOs)
+
+| Page | Goal |
+|---|---|
+| [FAQ](help/faq.md) | Short answers to the questions that don't need a page. |
+| [Troubleshooting](help/troubleshooting.md) | When OpenSpec doesn't do what you expected: symptoms and their fixes. |
+
+### Legacy: land the old workflow safely (held back from the site until drafted, see Open TODOs)
+
+| Page | Goal |
+|---|---|
+| [Migrating from the legacy workflow](help/legacy/migration.md) | Moving from the legacy `/openspec:*` commands to OPSX. |
+
+## Old docs
+
+The `docs/` tree is legacy, and the plan is to remove it once docs-lab covers what it
+owns. It has become a bit of an AI slop mess, so nothing from it is carried over as text
+(see The bar for every page). Until it's removed it stays untouched: fixes land in
+docs-lab, never in `docs/`.
+
+[`sources.md`](sources.md) maps every current `docs/` page to its destination here: the
+source material while drafting, the redirect list at cutover. Cutover steps are in that
+file's [Cutover](sources.md#cutover) section.
+
+## Open TODOs
+
+- Not started: the Architecture pages (`reference/architecture/index.md`,
+  `workflow-runs.md`, `design-decisions.md`). All three are headings only, so we hid the
+  group from the site on 2026-08-21 (folder entry commented out in
+  `website/docs.sync.config.mjs`). The files stay on disk with a WIP comment. Published
+  pages that link to them (`reference/glossary.md` to the Overview,
+  `customize/project-config.md` to Workflow runs) fall back to the GitHub source until
+  the group is re-listed.
+- Not started: the Help and Legacy pages (`help/faq.md`, `help/troubleshooting.md`,
+  `help/legacy/migration.md`). FAQ has one answer and the other two are headings only, so
+  we hid both sections from the site on 2026-08-21 (commented out in
+  `website/docs.sync.config.mjs`, same mechanism as Guides). The files stay on disk with
+  a WIP comment. Published pages that link to them (`start/setup.md` to FAQ,
+  `reference/glossary.md` to Migration) fall back to the GitHub source until the
+  sections are re-listed.
+- Not started: `start/overview.md` is empty on purpose. We cleared the skeleton
+  (headings, narrative beats, diagram gallery) on 2026-08-21 to rewrite the landing page
+  from scratch. The old pitch ("a shared, reviewable plan before code is written")
+  undersells OpenSpec now that plan mode is everywhere; the rewrite should sell keeping
+  larger features on track and aligned (teams, git-native, intended vs implemented
+  behavior, control-loop framing). Brief in `Notes.md` ("Start > Overview"); the diagram
+  candidates went with the gallery and live in git history. Until the rewrite lands the
+  page is off the site: its entry is commented out in `website/docs.sync.config.mjs` and
+  `/docs` redirects to Installation (`website/public/_redirects` plus a fallback in the
+  docs page route). Restoring it is one uncomment plus removing the two redirects. The
+  Teach-once rule still applies: the loop appears here as pitch only.
+- Product feedback, not a docs task: spec-driven's design `instruction` lists six
+  sections (including Migration Plan and Open Questions) but
+  `schemas/spec-driven/templates/design.md` carries only four headers. The docs show
+  both verbatim; the mismatch belongs upstream. Noted 2026-08-14 while consolidating
+  the spec-driven page.
+- Product feedback, not a docs task: `openspec store setup --remote` writes the URL
+  into `store.yaml` but never configures a git `origin`, so "setup --remote, then
+  `git push -u origin main`" fails as written; the Stores page shows `git remote add`
+  instead. The pasteable missing-store fix in `openspec doctor` is powered by
+  `references:` remotes, not `store.yaml`. Noted 2026-08-21 while porting the Stores
+  page.
+- Style guide follow-up (`.agents/skills/write-openspec-docs/writing.md`), from the
+  Stores page's review rounds, 2026-08-21: never use a term the page hasn't shown
+  (say "the `store:` line", not "the pointer"; define by showing the artifact first);
+  when behavior depends on the reader's starting state, enumerate the states and walk
+  each to its outcome; sentence subjects are you, OpenSpec, or your agent, never an
+  implementation unit ("the resolver picks") or a class of things ("store-only
+  projects make..."); when a defined term is reused a section later, re-gloss it in
+  one parenthetical at the point of use.
+- Fence convention follow-up, 2026-08-21: the Stores page puts commands in `bash`
+  fences with a one-line `#` comment and OpenSpec output in a separate `yaml` fence.
+  `customize/schemas.md` still uses `console` fences with `$` prompts (lines 78, 114,
+  137, 145; prompts at 24 and 115); the style guide should name the convention and
+  that page should adopt it.
+- Monorepo: message-map row 37 is still a Gap. "Packages treated as separate repos"
+  may land on the Stores page later; not part of the current page.
+
+- `reference/cli.md` is fully drafted: the command table plus one section per real
+  command, facts captured from working-tree runs (2026-08-11). The `delivery` key that
+  start/setup.md's "Skills, commands, or both" section sets appears there only as
+  command output; its field-level home, `reference/configuration/config-json.md`, is
+  drafted (2026-08-14).
+- Telemetry is undocumented. `OPENSPEC_TELEMETRY=0` appears nowhere in the tree; the
+  Deno install command grants `--allow-net=edge.openspec.dev` with no explanation (the
+  telemetry gloss was deliberately pulled pending a real home). The home now exists:
+  write `reference/configuration/environment-variables.md` (the env var, what's
+  collected, the opt-out, the CI auto-disable), then have the Deno section link to it
+  to explain the flag. Noted 2026-08-07; home settled 2026-08-10.
+- Product feedback, not a docs task: init doesn't say when the global profile changed what
+  it wrote. A machine with `profile: custom` silently installs a different workflow set
+  than a stock machine, and nothing in the init output names the profile that shaped it.
+  Noted 2026-08-05 while verifying installation.md; track upstream, don't paper over in prose.
+- Product feedback, not a docs task: drop the sync-specs skill from the default set; its
+  job reads as reference content, not a workflow, and it pads the skill list every reader
+  scans. Noted 2026-08-08 while writing start/setup.md's workflow tree.
+- Product feedback, not a docs task: make the shared `.agents/` folder the default install
+  target for every tool, with tool-specific folders (`.claude/`, ...) the exception. The
+  docs already prefer `.agents/` in examples; the product should match. Noted 2026-08-08.
+- `help/troubleshooting.md`'s skeleton has no section for install-time failures
+  (`command not found`, wrong Node version, PATH). Old `docs/troubleshooting.md` covered
+  them; `start/installation.md` carries caveats inline but there is no symptom-to-fix
+  home. Add a section or an installation.md anchor. Noted 2026-08-10 during the old-docs
+  message audit.
+- Missing guide: the iterative flow. new/continue/fast-forward have no owner for the
+  judgment: what the flow is, when to pick it over propose, and ff vs continue. Old
+  `docs/workflows.md` covered it (Two Modes, When to Use What); `sources.md` routes that
+  page's mechanics to `guides/apply.md` and contracts to `reference/skills.md`, so the
+  choice itself landed nowhere. Likely a Guides › Using page slotted between Explore and
+  Review the plan, with a pointer to `customize/profiles.md` (the skills are optional
+  workflows outside the core set). Salvage only the ff-vs-continue rule of thumb; the rest of
+  workflows.md is unverified. Noted 2026-08-11. Related: message-map row 29 words
+  apply.md's pacing question as drafting-time pacing, the same creation-stage choice;
+  fix that row's wording or owner when this guide lands. Noted 2026-08-14.
+- Missing guide: working with git. OpenSpec never touches git, so every git decision
+  lands on the reader with no page to answer it: do you branch before or after propose,
+  does a task get its own commit, what goes in the PR, where does the archive commit
+  land. `guides/teams.md` owns the archive-vs-PR ordering; the rest is unowned. Likely a
+  `guides/` file in the Adoption group. Noted 2026-08-08.
+- `customize/skills.md` is parked: the skeleton stays on disk but is out of the page
+  index, the sidebar, and the sync config. Editing installed skill prompts has no good
+  answer yet (`openspec update` overwrites edits); the message map keeps the question as
+  a Gap. Revive when the product has a real story for surviving updates. Parked 2026-08-14.
+- `guides/examples.md` is parked: the skeleton stays on disk but is out of the page
+  index, the sidebar, and the sync config. Contrived examples teach the wrong lesson for
+  this product; revive the page when real archived changes from actual usage can fill it.
+  The content plan (weak-vs-reviewed pairs, archived-changes gallery) is in the file's
+  comment. Parked 2026-08-11.
+- Product feedback, not a docs task: "expanded" survives in product strings and the
+  update workflow is unlabeled in the picker. The only stored profile values are core
+  and custom, but `src/core/templates/workflows/update-change.ts` says "expanded-profile
+  workflow", and `WORKFLOW_PROMPT_META` (`src/commands/config.ts`) has no `update` entry,
+  so the `openspec config` workflow picker renders a core workflow as raw `update` /
+  "Workflow: update". Docs standardized on core/custom with "expand the set" as a verb
+  (2026-08-12). Noted 2026-08-12 during the glossary product sweep.
+- Product feedback, not a docs task: converge on skills only, soon. A workflow's skill and
+  command are the same instructions, Claude Code has already merged commands into skills
+  upstream, and setup spends a whole subsection explaining why two forms exist. Every page
+  gets simpler when commands go. Noted 2026-08-08 while writing start/setup.md.
+- Website QOL backlog, site build not prose: i18n; AI search layered on the stock keyword
+  search (an ask-the-docs answer box, not just matching); proper light/dark themes that
+  carry the Survey palette (DESIGN.md tokens) into both modes instead of a stock dark
+  theme. Candidates to bundle in the same pass: `llms.txt` plus a per-page "copy as
+  Markdown" button so agents can ingest pages, copy buttons on code blocks, and
+  "edit this page on GitHub" links. Noted 2026-08-11.

docs-lab/customize/overview.md

@@ -0,0 +1,32 @@
+# Overview
+
+> Your options for customizing OpenSpec.
+
+OpenSpec supports multiple customization options. This page shows what each one changes and when to use it.
+
+## What you can customize
+
+| Option | What it changes | Use it when |
+|---|---|---|
+| [Profiles](profiles.md) | Which workflows are installed, and whether as skills, commands, or both | You want additional workflows and working patterns, or to remove workflows you don't need |
+| [Project configuration](project-config.md) | The instructions injected into every workflow run: context, rules, and operation guidance (`config.yaml`) | You want changes planned your way, like tasks always including Playwright tests |
+| [Schemas](schemas.md) | What OpenSpec produces: the artifacts, their order, and their templates | Changes should produce different planning files, sections, or formats |
+
+## Not sure which to use?
+
+Config and schemas are two levels of customization. Pick by how hands-on you want to get:
+
+- **Start with [project configuration](project-config.md)**: it's lighter, and for most projects it's enough. You keep the standard artifacts and add your own context and rules on top.
+- **Fork a [schema](schemas.md) when adding isn't enough**: config only adds on top of the core workflow. It can add a rule like "tasks always include tests," but it can't drop the design doc or rename a file. That's schema territory. Forking gives you your own copy to edit.
+
+*"Fork" here means the `openspec schema fork` command, not forking a git repo. [Schemas](schemas.md) has the details.*
+
+```mermaid
+flowchart LR
+    a["The workflows should know my stack and conventions"] --> config
+    b["One artifact needs an extra rule, like tasks always including tests"] --> config
+    c["Different artifacts, file names, or document structure"] --> schema
+    d["The built-in instructions say things my team does differently"] --> schema
+    config["Project configuration<br/>(config.yaml)"]
+    schema["Fork a schema<br/>(openspec schema fork)"]
+```

docs-lab/customize/profiles.md

@@ -0,0 +1,88 @@
+# Profiles
+
+> Choose which workflows are installed, and whether they install as skills, commands, or both.
+
+A profile is your preference for which OpenSpec workflows (the [skills and commands](../start/setup.md#the-workflow-files-skills-and-commands) in your AI tool) are installed across your machine. The default profile is `core`. Include or exclude workflows and your selection is saved as the `custom` profile.
+
+## The core set
+
+The `core` profile installs six workflows, covering the whole loop from idea to archive:
+
+| Workflow | What it's for |
+|---|---|
+| [`explore`](../reference/skills.md#openspec-explore) | Think through an idea before it becomes a change proposal |
+| [`propose`](../reference/skills.md#openspec-propose) | Create a change proposal and generate all its planning artifacts in one step |
+| [`apply`](../reference/skills.md#openspec-apply-change) | Implement a change proposal's tasks |
+| [`update`](../reference/skills.md#openspec-update-change) | Revise a change proposal's existing planning artifacts |
+| [`sync`](../reference/skills.md#openspec-sync-specs) | Merge a change proposal's spec updates into `specs/` without archiving it |
+| [`archive`](../reference/skills.md#openspec-archive-change) | Move a finished change proposal to the archive |
+
+Each links to its full contract: arguments, what it creates, and what it responds with.
+
+## Expanding the set: optional workflows
+
+Six more workflows are available beyond the core set. Three of them (`new`, `continue`, `ff`) create a change proposal artifact by artifact, instead of all at once like `propose`.
+
+| Workflow | What it's for |
+|---|---|
+| [`new`](../reference/skills.md#openspec-new-change) | Start a change proposal as an empty scaffold |
+| [`continue`](../reference/skills.md#openspec-continue-change) | Create the next planning artifact in a change proposal, one at a time |
+| [`ff`](../reference/skills.md#openspec-ff-change) | Create a change proposal and every planning artifact implementation needs, in one pass |
+| [`verify`](../reference/skills.md#openspec-verify-change) | Check that the implementation matches the change proposal's artifacts |
+| [`bulk-archive`](../reference/skills.md#openspec-bulk-archive-change) | Archive several change proposals at once |
+| [`onboard`](../reference/skills.md#openspec-onboard) | Learn the workflow by doing one real change proposal end to end |
+
+To change the set, run the interactive picker:
+
+```bash
+openspec config profile
+```
+
+The picker asks what to configure ([delivery](#delivery-skills-commands-or-both), workflows, or both), then lists all twelve workflows as checkboxes, with the installed ones checked. Any selection that isn't exactly the core six is saved as the `custom` profile, so you can also uncheck core workflows you don't use.
+
+## Delivery: skills, commands, or both
+
+Delivery is a profile setting that lets you choose to have only skills or only commands installed. The default is `both`. [Set up your project](../start/setup.md#the-workflow-files-skills-and-commands) explains the two forms and why both exist. The field's exact contract is in [CLI settings (config.json)](../reference/configuration/config-json.md#delivery).
+
+Two ways to change it:
+
+**Interactively**: run `openspec config profile` and choose "Delivery only". Here's switching to skills only:
+
+```
+Current profile settings
+  Delivery: both
+
+? What do you want to configure? Delivery only
+? Delivery mode (how workflows are installed): Skills only
+
+Config changes:
+  delivery: both -> skills
+? Apply changes to this project now? (Y/n) y
+```
+
+**Directly**: one command, no prompts:
+
+```bash
+openspec config set delivery skills   # or: both, commands
+```
+
+Delivery never changes the profile name. `core` and `custom` describe the workflow set only, and switching back to `core` keeps your delivery setting.
+
+## Switching profiles
+
+Switching is two steps: change the profile on your machine, then update each project to apply it.
+
+1. Change the profile:
+
+   ```bash
+   openspec config profile        # interactive
+   openspec config profile core   # reset to the core six (keeps delivery)
+   ```
+
+2. Run the update in each project you work in:
+
+   ```bash
+   openspec update
+   ```
+
+When your current directory is an existing OpenSpec project, the interactive flow offers to run step 2 there for you.

docs-lab/customize/project-config.md

@@ -0,0 +1,124 @@
+# Project configuration
+
+> Make the workflows plan changes the way you want with a few lines in config.yaml.
+
+`openspec/config.yaml` tells the workflows how you want changes planned.
+
+For example, the following configuration updates the creation rules for the [tasks.md](../reference/schemas/spec-driven/index.md) artifact:
+
+```yaml
+rules:
+  tasks:
+    - End every task with a commit
+```
+
+When the agent runs, it pulls from these rules and ensures every task ends with a commit step.
+
+Keep rules short. Everything here lands in the agent's context, and verbose rules can make the output worse.
+
+## How it works
+
+config.yaml holds instructions the agent receives when it creates artifacts or works through the workflow.
+
+Here's what happens on every run:
+
+1. You run a workflow (e.g. `/openspec-propose`).
+2. The agent calls the [`openspec instructions`](../reference/cli.md) command.
+3. The command reads your context and rules from config.yaml.
+4. OpenSpec's built-in instructions and your customizations are combined into a single prompt for the agent.
+5. The agent follows that prompt to write the artifact.
+
+For example, with a `context` field and the rule from the top of this page, here's what [`openspec instructions`](../reference/cli.md) returns for tasks.md (trimmed and annotated):
+
+```xml
+<artifact id="tasks" change="add-dark-mode" schema="spec-driven">
+
+  <!-- From your config.yaml: context -->
+  <project_context>
+    Tech stack: TypeScript, Node.js
+    Domain: e-commerce platform
+  </project_context>
+
+  <!-- From your config.yaml: rules for tasks -->
+  <rules>
+    - End every task with a commit
+  </rules>
+
+  <!-- From OpenSpec: the built-in guidance -->
+  <instruction>
+    ...how to write a good tasks.md...
+  </instruction>
+
+  <template>
+    ...the tasks.md structure to fill in...
+  </template>
+
+</artifact>
+```
+
+Your config arrives first, then OpenSpec's built-in instruction and template. Rules add to the built-ins and never replace them. Edits to config.yaml reach the agent on the next run.
+
+[Workflow runs](../reference/architecture/workflow-runs.md) covers the full run, from invocation to written artifacts.
+
+## The fields
+
+Three fields shape what the agent receives. Each field's exact contract (types, limits, validation) is in [Project configuration (config.yaml)](../reference/configuration/config-yaml.md).
+
+| Field | What it does | Injected into |
+|---|---|---|
+| `context` | Instructions the agent always receives | Everything: every artifact, `apply`, `archive` |
+| `rules` | Extra instructions for one artifact | Only that artifact's creation |
+| `operations` | Guidance for how a workflow step is carried out | Only `apply` and `archive` |
+
+config.yaml's other fields (`schema`, `store`, `references`) select which schema and which OpenSpec root a project uses. The contract page covers them.
+
+The last column is exact, so a field reaches only the steps listed there. In particular, `verify` never receives `rules`. It checks the implementation against the artifacts as written.
+
+### context
+
+`context` is what the agent should know up front when planning a change, whether it's creating an artifact, applying tasks, or archiving:
+
+```yaml
+context: |
+  We ship cross-platform; designs and tasks must cover Windows, macOS, and Linux
+  Tech stack: TypeScript, Node.js, Commander.js
+  We use conventional commits
+```
+
+This is planning context, not project documentation. Add a fact when it should shape every plan, like the cross-platform line above. Leave out anything the agent can learn by reading the code.
+
+**Another language**: because context reaches every artifact, it's also how you change the output language. One line, like `Write all artifacts in Spanish.`, switches every proposal, spec, and tasks file the workflows write.
+
+### rules
+
+`rules` attach to one artifact, keyed by artifact id. Each line is added to that artifact's built-in guidance:
+
+```yaml
+rules:
+  proposal:
+    - Keep proposals under 500 words
+  tasks:
+    - Every UI task includes a Playwright test
+```
+
+Proposals now stay short and tasks.md always plans browser tests. Every other artifact is untouched.
+
+### operations
+
+`operations` guides how the agent carries out `apply` and `archive`, rather than what artifacts say:
+
+```yaml
+operations:
+  apply:
+    guidance:
+      - Run the linter before marking a task complete
+  archive:
+    guidance:
+      - Summarize what shipped before archiving
+```
+
+During apply, the agent lints as it completes tasks. During archive, it closes with a summary.
+
+## When config.yaml isn't enough
+
+Config adds instructions on top of the standard workflow, but it can't change which artifacts exist or how they're structured. When you want that level of control, or rules aren't steering behavior consistently, [fork a schema](schemas.md).

docs-lab/customize/schemas.md

@@ -0,0 +1,164 @@
+# Schemas
+
+> Change what OpenSpec produces: the artifacts, their order, and their templates.
+
+A schema defines what a change proposal produces: which artifacts, in what order, from which templates. For example, [spec-driven](../reference/schemas/spec-driven/index.md), the default bundled schema, produces these four in roughly this order, each building on what came before:
+
+```
+proposal → specs → design → tasks
+```
+
+Fork a schema when you want these to be different documents, whether that means fewer of them, different names, or a different structure.
+
+## Where schemas live
+
+OpenSpec looks for a schema in three places, in order, and uses the first one it finds:
+
+1. **Your project**: `openspec/schemas/`, committed with the repo so your whole team gets it.
+2. **Your machine**: `~/.local/share/openspec/schemas` on macOS and Linux (or under `$XDG_DATA_HOME` if you set it), or `%LOCALAPPDATA%\openspec\schemas` on Windows. Schemas here are available in every project you work in.
+3. **The package**: the built-ins, like `spec-driven`, ship inside openspec itself.
+
+The same name can exist in more than one place, and the more specific location wins. `openspec schema which` shows which copy is in use:
+
+```
+$ openspec schema which spec-driven
+Schema: spec-driven
+Source: project
+Path: /your-project/openspec/schemas/spec-driven
+
+Shadows:
+  package: .../openspec/schemas/spec-driven
+```
+
+## What's in a schema
+
+A schema is defined by a folder of plain files: one schema.yaml that declares the artifacts, and a template for each of them. Here's the built-in `spec-driven`:
+
+```
+spec-driven/
+├── schema.yaml
+└── templates/
+    ├── proposal.md
+    ├── spec.md
+    ├── design.md
+    └── tasks.md
+```
+
+- **schema.yaml**: declares each artifact, the file it generates, the template it starts from, what it requires first, and the instruction the agent receives when creating it. Every field's contract is in [schema.yaml](../reference/schemas/schema-yaml.md).
+- **templates/**: one markdown skeleton per artifact, which the agent fills in.
+
+Here's the tasks artifact's entry in schema.yaml, trimmed:
+
+```yaml
+artifacts:
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      ...what the agent is told when creating tasks.md...
+    requires:
+      - specs
+      - design
+```
+
+The built-in schemas ship inside the openspec package, so you never edit them in place. You get your own copy by forking.
+
+## Creating your own custom schema
+
+There are two ways to get your own schema:
+
+1. **Fork an existing schema** and edit your copy. Start here when an existing schema is close to what you want, because everything in it already works.
+2. **Start from scratch** when none of them fit, scaffolding an empty schema with `openspec schema init`.
+
+### Fork an existing schema
+
+1. Fork the schema you want to start from, running from your project root:
+
+   ```console
+   $ openspec schema fork spec-driven
+
+   Note: Schema commands are experimental and may change.
+   ✔ Forked 'spec-driven' to 'spec-driven-custom'
+
+   Source: .../openspec/schemas/spec-driven (package)
+   Destination: /your-project/openspec/schemas/spec-driven-custom
+   ```
+
+   Pass a second argument to pick the name (`openspec schema fork spec-driven team-flow`). Names are kebab-case.
+
+2. Edit the copy: schema.yaml and the templates. [Editing your fork](#editing-your-fork) covers what to change.
+
+3. Validate it:
+
+   ```bash
+   openspec schema validate spec-driven-custom
+   ```
+
+   This is the one command that catches a broken schema (missing templates, bad YAML, dependency cycles) before you're in the middle of a change.
+
+4. Point your project at it in openspec/config.yaml. This step is yours to do because fork leaves config.yaml untouched:
+
+   ```yaml
+   schema: spec-driven-custom
+   ```
+
+5. New change proposals now follow your schema. Changes created earlier keep the schema they started with.
+
+To replace the default everywhere without touching config.yaml, fork to the same name: `openspec schema fork spec-driven spec-driven`. Your project's copy then shadows the built-in, as [Where schemas live](#where-schemas-live) explains.
+
+### Start from scratch
+
+`openspec schema init` scaffolds a new schema instead of copying one:
+
+```console
+$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks
+
+✔ Created schema 'lite'
+Schema created at: /your-project/openspec/schemas/lite
+Artifacts: proposal, tasks
+```
+
+The scaffold is bare. Artifacts come from the built-in four ids only, and the generated templates carry no instructions, so the agent gets less guidance until you write your own. From there the fork steps apply unchanged: validate it, then point config.yaml at it.
+
+## Editing your fork
+
+A fork has two kinds of files to edit:
+
+- **templates/** change the skeleton of each document. Add a section to the tasks template and every new tasks.md starts with it.
+- **schema.yaml** changes the workflow itself: which artifacts exist, what each one requires first, and the instruction the agent gets when creating it.
+
+For example, to drop the design document for a leaner flow:
+
+1. Delete the `design` entry from schema.yaml.
+2. Remove `design` from the `requires` list of `tasks`.
+3. Validate:
+
+   ```console
+   $ openspec schema validate spec-driven-custom
+
+   ✓ Schema 'spec-driven-custom' is valid
+   ```
+
+Skip step 2 and validate catches it:
+
+```console
+✗ Schema 'spec-driven-custom' has errors:
+  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist
+```
+
+Validate after every hand-edit. A broken schema otherwise surfaces in the middle of a change, when a workflow asks for a file that isn't there. Like config.yaml, schema edits reach the agent on the next run.
+
+## A fork is a snapshot
+
+`openspec update` refreshes the installed skills and commands, and it never touches `openspec/schemas/`. Your fork keeps working exactly as you left it, which also means it stops receiving improvements when the built-in schema evolves. To pick those up later, fork the built-in again under a new name and port the differences across.
+
+## Sharing schemas
+
+Sharing a schema means copying its folder.
+
+- **With your team**: commit `openspec/schemas/` and everyone on the repo uses it.
+- **Across your projects**: put the folder in the user-level directory from [Where schemas live](#where-schemas-live).
+- **From the community**: the [community catalog](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md#community-schemas) lists shared schemas. Copy one into `openspec/schemas/<name>` and it works like your own.
+
+We're working on a schema registry, public and private, so schemas can be installed by name instead of copied by hand.

docs-lab/customize/skills.md

@@ -0,0 +1,14 @@
+# Customizing skills
+
+> Edit the installed skill prompts directly: what you can change, and what update overwrites.
+
+<!-- PARKED 2026-08-14 (README TODO): out of the page index, sidebar, and sync config.
+No good answer yet for edits surviving `openspec update`; the message map keeps
+"How should a user edit the installed skill prompts?" as a Gap. Skeleton below is
+the shape to revive. The honest page for the update-clobber caveat. -->
+
+## What you can change
+
+## What openspec update overwrites
+
+## Supported alternatives

docs-lab/guides/apply.md

@@ -0,0 +1,11 @@
+# Apply a change
+
+> Run the plan: pacing, context windows, and picking up where you left off.
+
+<!-- Skeleton: headings only. Promoted out of examples.md in review round 2. -->
+
+## Task by task or all at once
+
+## Managing the context window
+
+## Continue and fast-forward

docs-lab/guides/change-course.md

@@ -0,0 +1,11 @@
+# Change course
+
+> Revise a change in flight, or decide it's cleaner to start fresh.
+
+<!-- Skeleton: headings only. -->
+
+## Update or start fresh?
+
+## Revising artifacts with openspec-update-change
+
+## Advanced: revising mid-implementation

docs-lab/guides/concepts.md

@@ -0,0 +1,9 @@
+# Concepts
+
+> What the two artifacts are, and how a change describes a diff against current specs.
+
+<!-- Skeleton: headings only. Narrowed in review round 3 (dedup pass). The quickstart's archive file-steps absorbed the loop mechanics this page once planned to own, so the loop section is gone: the quickstart is the loop's only teacher, and core-vs-optional moved to customize/profiles.md. The fixed-vs-shapeable section was cut entirely (customize/overview.md dropped that framing in review, 2026-08-14: it opens straight on the options and never says what can't be changed). What remains is the one explanation this page owns: the artifacts. Specs absorbs "What a spec is"; Changes owns the delta concept: one worked delta block (ADDED/MODIFIED/REMOVED, from docs/concepts.md's core) showing a change as a diff against current specs; the file-format rules live in reference/schemas/spec-driven/index.md (Delta specs section). Disk paths appear inline with the concept that owns them (specs/ under Specs, changes/ under Changes), never as a layout section. Close with link lines: quickstart for the loop, customize/overview for the customization options. When to archive relative to a branch or PR stays in guides/teams.md. -->
+
+## Specs: the system as built
+
+## Changes: a folder of deltas

docs-lab/guides/examples.md

@@ -0,0 +1,16 @@
+# Examples
+
+> See what a good change looks like: real drafts, what review caught, and the fixes.
+
+<!-- Skeleton: headings only. PARKED 2026-08-11: out of the README index and sync config. Contrived examples teach the wrong lesson for this product; the page waits for real archived changes from actual usage. Plan when revived: weak-vs-reviewed pairs (4) plus an archived-changes gallery. Earlier decisions still hold: slimmed in review round 2, purely example pairs; apply technique lives in guides/apply.md. -->
+
+
+## Adding a feature to an undocumented codebase
+
+## Changing an API without breaking clients
+
+## A behavior-preserving refactor
+
+## A database migration with rollback
+
+## Real archived changes

docs-lab/guides/existing-codebases.md

@@ -0,0 +1,13 @@
+# Existing codebases
+
+> Bring OpenSpec to a codebase with a lot of code and no specs: where to start, what to backfill, and how specs grow from there.
+
+<!-- Skeleton: headings only. Rescoped 2026-08-11: the page is the adoption guide for legacy codebases (a lot of code, no specs), not just the backfill task; "Specs for existing code" is now one section. The opening section owns "you don't need specs first": the quickstart runs on an existing repo as-is, and specs accumulate through changes. Source: docs/existing-projects.md. When prose lands, reshape to the Guides skeleton (one-line what, quickstart link, 80% path, Advanced). -->
+
+## Start with a change
+
+## Specs for existing code
+
+## Working from a PRD
+
+## Organizing specs as they grow

docs-lab/guides/explore.md

@@ -0,0 +1,17 @@
+# Explore an idea
+
+> Think it through with the agent before you commit to a proposal.
+
+<!-- Skeleton: headings only. -->
+
+## When to explore first
+
+## A real explore session
+
+## From exploration to proposal
+
+## Advanced
+
+### Exploring mid-change
+
+### Challenging a draft plan

docs-lab/guides/review-the-plan.md

@@ -0,0 +1,15 @@
+# Review the plan
+
+> The two-minute pass that catches wrong turns before they're code.
+
+<!-- Skeleton: headings only. -->
+
+## The two-minute pass
+
+## What good requirements look like
+
+## What good scenarios look like
+
+## Pushing back
+
+## Advanced: verify after apply

docs-lab/guides/teams.md

@@ -0,0 +1,17 @@
+# Teams
+
+> Run OpenSpec as a team: what to commit, how a change rides its PR, and when to archive.
+
+<!-- Skeleton: headings only. Retitled from "Teams & parallel changes" 2026-08-11: the page's job is running OpenSpec in a team; parallel changes stays as the touching-one-spec section, and the general parallel-changes answer (solo included) remains an unowned gap in message-map.md. Expanded in review: this page owns the git/PR conventions (the quickstart's archive step shows the mechanism; this page owns timing). Source for all three new sections: docs/team-workflow.md. "A change is a branch and a PR": one branch carries the change folder and the code, so the PR shows the plan and the diff together. "Review in pull requests": reviewer order proposal → spec delta → code; approach disagreements land on the proposal, not across 300 lines of diff. "When to archive": after the PR merges (recommended, specs/ only advances with shipped work) vs inside the PR (simpler, noisier diff); pick one and be consistent. Proposal-first PRs (plan reviewed before implementation starts) go under Advanced. -->
+
+## Checking openspec/ into git
+
+## A change is a branch and a PR
+
+## Review in pull requests
+
+## When to archive
+
+## Parallel changes touching one spec
+
+## Advanced: conventions for larger teams

docs-lab/help/faq.md

@@ -0,0 +1,23 @@
+# FAQ
+
+> Short answers to the questions that don't need a page.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its section is commented out in website/docs.sync.config.mjs, 2026-08-21). The
+file stays so the structure and inbound links survive; re-list it in the sync config
+once the prose lands. -->
+
+<!-- Every entry is a one-liner: a short answer or a router link to the page that owns the topic; how-to content never lives here (README's "FAQ is one-liners" rule). Update/uninstall moved to installation.md; the skills-missing fix and Getting help live in troubleshooting.md; the git question is a one-line yes routing to guides/teams.md, which owns the team conventions. Unfilled headings are skeletons. -->
+
+## Should openspec/ be checked into git?
+
+## What runs in the terminal, and what in chat?
+
+## Does OpenSpec work with my tool?
+
+If it has a row in the [support matrix](../reference/supported-tools.md), yes.
+Pick its id at init. If it isn't listed but reads the shared `.agents/skills/`
+folder, pick **Shared `.agents` skills** (`--tools agents`). If neither, request
+it in the [OpenSpec repo](https://github.com/Fission-AI/OpenSpec/issues).
+
+## Where did the old /openspec:* commands go?

docs-lab/help/legacy/migration.md

@@ -0,0 +1,18 @@
+# Migrating from the legacy workflow
+
+> Moving from the legacy `/openspec:*` commands to OPSX.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its section is commented out in website/docs.sync.config.mjs, 2026-08-21). The
+file stays so the structure and inbound links survive; re-list it in the sync config
+once the prose lands. -->
+
+<!-- Skeleton: headings only. -->
+
+## What changed and why
+
+## Command mapping
+
+## Migrating a project
+
+## Behavior differences

docs-lab/help/troubleshooting.md

@@ -0,0 +1,20 @@
+# Troubleshooting
+
+> When OpenSpec doesn't do what you expected: symptoms and their fixes.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its section is commented out in website/docs.sync.config.mjs, 2026-08-21). The
+file stays so the structure and inbound links survive; re-list it in the sync config
+once the prose lands. -->
+
+<!-- Skeleton: headings only. Canonical home for symptom-to-fix, including the skills-missing checklist. -->
+
+## Skills don't appear in chat
+
+## The agent ignores the workflow
+
+## Validation failures
+
+## Sync and archive issues
+
+## Getting help

docs-lab/message-map.md

@@ -0,0 +1,65 @@
+# Message map: the questions the docs must answer, and where
+
+The [README](README.md) index runs page to job. This file runs the other way: one flat
+list of the questions we need the docs to answer, each pointing at the group and page
+that owns the answer. Status says whether that answer exists yet: **Answered** (the
+owning page's prose has landed), **Skeleton** (owner assigned, page is headings only),
+**Gap** (no owner), **Off-site** (answered outside these docs by decision). Flip a row
+to Answered when its page's prose lands. Rows follow the sidebar order of the owning
+page; gaps sit where their proposed home would fall, and off-site rows go last. Keep
+rows coarse (question to page, never sentence to section) so this stays cheap to
+maintain.
+
+| Question | Answered by | Status |
+|---|---|---|
+| How do we pitch the core idea (keeping larger features on track and aligned, not just a plan before code)? | [Start › Overview](start/overview.md) (emptied 2026-08-21 for a from-scratch rewrite and pulled from the site until then; brief in Notes.md) | Skeleton |
+| How does someone decide OpenSpec is worth their time? | [Start › Overview](start/overview.md) (emptied 2026-08-21, see row above) | Skeleton |
+| How should a user install the CLI, update it, uninstall it? | [Start › Installation](start/installation.md) | Answered |
+| How can a user hand install and setup to their AI assistant? | [Start › Installation](start/installation.md), the install.md prompt | Answered |
+| How should a user add OpenSpec to their repo? | [Start › Set up your project](start/setup.md) | Answered |
+| How do the workflows get into a user's tool, and why skills and commands both? | [Start › Set up your project](start/setup.md) | Answered |
+| How do we teach the loop: propose, review, apply, archive? | [Start › Quickstart](start/quickstart.md) | Answered |
+| How should a user run their first change end to end? | [Start › Quickstart](start/quickstart.md) | Answered |
+| How does a user know which prompts go in the AI chat and which commands in the terminal? | [Start › Quickstart](start/quickstart.md) inline with each step, then [Help › FAQ](help/faq.md) | Answered |
+| How do we explain what specs and changes are? | [Guides › Understanding › Concepts](guides/concepts.md) | Skeleton |
+| How should a user think through an idea before proposing? | [Guides › Using › Explore an idea](guides/explore.md) | Skeleton |
+| How should a user review a plan? | [Guides › Using › Review the plan](guides/review-the-plan.md) | Skeleton |
+| How does a user check the implementation matches the plan before archiving? | [Guides › Using › Review the plan](guides/review-the-plan.md), the verify pass | Skeleton |
+| How should a user run a plan across sessions and context limits? | [Guides › Using › Apply a change](guides/apply.md) | Skeleton |
+| How should a user pace the plan: draft everything at once, or artifact by artifact? | [Guides › Using › Apply a change](guides/apply.md), continue and fast-forward | Skeleton |
+| How do we explain the standard flow (propose drafts every artifact in one step) vs the iterative flow (new creates the change, continue drafts the next artifact, fast-forward catches up)? | [Start › Quickstart](start/quickstart.md) teaches only the standard flow; [Guides › Using › Apply a change](guides/apply.md) owns pacing once a change exists; [Reference › Skills](reference/skills.md) holds the new/continue/ff contracts; [Customize › Profiles](customize/profiles.md) covers installing them; a [README](README.md) TODO proposes a Using guide | Gap |
+| How should a user change direction mid-change, or bail out? | [Guides › Using › Change course](guides/change-course.md) | Skeleton |
+| How should a team run OpenSpec together? | [Guides › Adopting › Teams](guides/teams.md) | Skeleton |
+| How should a user work on several changes at once? | [Guides › Adopting › Teams](guides/teams.md) owns the touching-one-spec collision case; the general answer (solo included, not just teams) has no owner yet | Gap |
+| How should a user handle git across the loop: branching, commits, PRs? | Only archive-vs-PR ordering is owned, by [Guides › Adopting › Teams](guides/teams.md); README TODO proposes a guide | Gap |
+| What does a good change look like? | `guides/examples.md` is parked until real archived changes can fill it (README TODO); no published owner | Gap |
+| How should a user adopt OpenSpec on code that already exists? | [Guides › Adopting › Existing codebases](guides/existing-codebases.md) | Skeleton |
+| How should a user run OpenSpec in a monorepo? | Legacy `docs/existing-projects.md` owned it (one `openspec/` at the repo root, domains map to packages); likely home is [Guides › Adopting › Existing codebases](guides/existing-codebases.md), with [Multi-repo › Stores](multi-repo/stores.md) taking packages treated as separate repos | Gap |
+| How do we explain what's customizable in OpenSpec? | [Customize › Overview](customize/overview.md) | Answered |
+| How does a user pick the right customization level, and when should they escalate from config to schemas? | [Customize › Overview](customize/overview.md), the "Not sure which to use?" section | Answered |
+| How should a user choose which workflows are installed? | [Customize › Profiles](customize/profiles.md) | Answered |
+| How does a user switch to skills only or commands only? | [Customize › Profiles](customize/profiles.md), Delivery section; [Start › Set up your project](start/setup.md) owns why both forms exist | Answered |
+| How does a user make the workflows plan changes their way: context, rules, and guidance? | [Customize › Project configuration](customize/project-config.md) | Answered |
+| How does a user get artifacts written in a language other than English? | [Customize › Project configuration](customize/project-config.md), the context section's "Another language" note | Answered |
+| How should a user change what OpenSpec produces? | [Customize › Schemas](customize/schemas.md), with the fork walkthrough in "Creating your own custom schema" | Answered |
+| How should a user edit the installed skill prompts? | No owner: `customize/skills.md` is parked (README TODO) until there's a good answer to `openspec update` overwriting edits | Gap |
+| How should a user run OpenSpec across multiple repos? | [Multi-repo › Stores](multi-repo/stores.md); [Start › Set up your project](start/setup.md) routes there from "Pick where OpenSpec lives" | Answered |
+| How should a user plan a change that spans repos? | [Multi-repo › Stores](multi-repo/stores.md) | Answered |
+| What does each skill do, and when should a user reach for it? | [Reference › Skills](reference/skills.md) | Answered |
+| Where does a user look up a terminal command? | [Reference › CLI](reference/cli.md) | Answered |
+| How does a user learn what telemetry is collected, and opt out? | [Reference › Configuration › Environment variables](reference/configuration/environment-variables.md) owns the facts (was a README-TODO gap); [Help › FAQ](help/faq.md) routes searchers there | Skeleton |
+| Where does a user look up an artifact's format, or a schema definition's fields? | [Reference › Schemas](reference/schemas/index.md) | Answered |
+| Where does a user look up a setting or a file that changes OpenSpec's behavior? | [Reference › Configuration](reference/configuration/index.md) | Answered |
+| Which openspec/ tree does a command operate on? | [Reference › Configuration › Stores](reference/configuration/stores.md) owns the whole resolution ladder, including the everyday case (nearest openspec/ wins); readers reach it from the Stores row of the [Configuration overview](reference/configuration/index.md) map | Skeleton |
+| How should a user run a change with no spec impact, or retire a capability outright? | [Reference › Configuration › Change metadata](reference/configuration/change-metadata.md) owns the `skip_specs` and `retire_capabilities` contracts; [Reference › Schemas › spec-driven](reference/schemas/spec-driven/index.md), Delta specs section, owns their effect on deltas and archive; neither half has a guide owner | Gap |
+| What is an initiative, and how does a change join one? | No owner: the `initiative` field's contract sits on [Reference › Configuration › Change metadata](reference/configuration/change-metadata.md), but no page teaches initiatives (multi-repo has only Stores) | Gap |
+| What is a workset, and how does a user open one in their editor? | [Multi-repo › Worksets](multi-repo/worksets.md); the `openers` field's contract stays on [Reference › Configuration › CLI settings](reference/configuration/config-json.md) | Answered |
+| Which AI tools work, and what's each one's syntax? | [Reference › Supported tools](reference/supported-tools.md) | Answered |
+| My tool isn't listed, can I still use OpenSpec? | [Help › FAQ](help/faq.md) routes: the shared `.agents` target or an issue; [Reference › Supported tools](reference/supported-tools.md), Per-tool notes, holds the shared target's contract | Answered |
+| Where does a user look up a term? | [Reference › Glossary](reference/glossary.md) | Answered |
+| How is OPSX built? | [Reference › Architecture](reference/architecture/index.md) | Skeleton |
+| How do we explain that the workflow is fluid, actions not phases? | [Start › Overview](start/overview.md) will carry the pitch once rewritten (the "shared map, not a plan up front" framing was in the cleared skeleton); [sources.md](sources.md) routes opsx.md's explanation to [Guides › Understanding › Concepts](guides/concepts.md), but that page narrowed to artifacts only in review round 3; likely home is Guides › Understanding, widening [Concepts](guides/concepts.md) or adding a sibling page, with [Reference › Architecture › Design decisions](reference/architecture/design-decisions.md) keeping the why | Gap |
+| What should a user do when OpenSpec doesn't do what they expected? | [Help › Troubleshooting](help/troubleshooting.md), then [Help › FAQ](help/faq.md) | Skeleton |
+| Where does a user go for help or to report a bug? | [Help › Troubleshooting](help/troubleshooting.md), Getting help | Skeleton |
+| How should a user move off the legacy `/openspec:*` commands? | [Help › Migration](help/legacy/migration.md) | Skeleton |
+| How does a script or CI drive the CLI programmatically? | Off-site by decision: repo-side contributor docs, per [sources.md](sources.md) | Off-site |

docs-lab/multi-repo/stores.md

@@ -0,0 +1,341 @@
+# Stores (beta)
+
+> Plan changes that span repositories: one store, many repos.
+
+OpenSpec normally lives inside one repo: an `openspec/` folder next to the code it plans. A store moves that folder into a repository of its own, and several code repos can share it.
+
+After a one-time setup on each machine, commands like `status`, `new change`, and `archive` can work in the store from any directory.
+
+```
+         team-plans  (a store: OpenSpec in its own repo)
+         ├── .openspec-store/store.yaml   the store's name
+         └── openspec/
+             ├── specs/
+             └── changes/
+                   ▲
+                   │ set up once on each machine,
+                   │ shared by pushing and cloning like any repo
+     ┌─────────────┼─────────────┐
+     │             │             │
+ web-app       api-server     mobile-app
+(code repo)   (code repo)    (code repo)
+```
+
+You share a store with git, the same way you share code: commit, push, pull, and review it yourself. Specs and changes get branches and pull requests the same way code does.
+
+## When you need one
+
+Two common reasons to use a store:
+
+- **Frontend and backend in separate repos**: one feature touches both, and the plan needs a single home instead of two halves.
+
+  ```
+        shop-plans  (store)
+        └── openspec/changes/add-discounts/    one plan for the feature
+                  ▲
+        ┌─────────┴─────────┐
+        │                   │
+    storefront             api
+  (frontend repo)     (backend repo)
+  ```
+
+- **One product, several client repos**: Android, iOS, and web ship from their own repos but share one expected behavior. A spec describes behavior, not implementation, so one spec serves all three.
+
+  ```
+          product-specs  (store)
+          └── openspec/specs/checkout/spec.md    the expected behavior
+                    ▲
+      ┌─────────────┼─────────────┐
+      │             │             │
+  android-app    ios-app       web-app
+  (code repo)   (code repo)   (code repo)
+  ```
+
+You can have more than one store, though we recommend keeping the count low.
+
+## Set up a store
+
+One person creates the store, then everyone else joins it.
+
+1. **Create the store** (one person, once per team). Run `openspec store setup` and answer the prompts:
+
+   ```bash
+   # run from anywhere; it asks what to create and where
+   openspec store setup
+   ```
+   
+   It asks three questions:
+   
+   - **Store name**: `team-plans`
+   - **Where should this store live?**: pre-filled with `~/openspec/<name>`, press Enter to accept it or type another path
+   - **Create this store?**: shows what it's about to make, answer `Yes`
+   
+   Then it reports what it created:
+   
+   ```yaml
+   Store ready: team-plans
+   Location: ~/openspec/team-plans
+   OpenSpec root: ready
+   Registry: registered
+   
+   Next: run normal OpenSpec commands against this store, for example:
+     openspec new change <change-id> --store team-plans
+   Share this store by committing and pushing it like any Git repo.
+   ```
+
+2. **Push it to your git host.** Create an empty `team-plans` repo on your host first. Setup doesn't add a git remote, so connect the store to that repo, then push:
+
+   ```bash
+   # connect the store to the empty repo on your git host
+   cd ~/openspec/team-plans
+   git remote add origin git@github.com:acme/team-plans.git
+
+   # publish it
+   git push -u origin main
+   ```
+   
+3. **Join the store** (every teammate, once per machine):
+   
+   ```bash
+   # get the store onto your machine
+   git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
+   
+   # tell OpenSpec where it lives
+   openspec store register ~/openspec/team-plans
+   ```
+
+   ```yaml
+   Store registered: team-plans
+   Location: /Users/you/openspec/team-plans
+   OpenSpec root: ready
+   Registry: registered
+   ```
+   
+   Registering tells your machine where this store lives. The store's name is already committed inside it, in `.openspec-store/store.yaml`. Setup registered the creator's copy, so only cloned copies need this step.
+   
+4. **Confirm it worked**, from any directory:
+   
+   ```bash
+   # any OpenSpec command reaches the store by name
+   openspec status --store team-plans
+   ```
+
+   ```yaml
+   Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
+   No active changes. Create one with: openspec new change <name> --store team-plans
+   ```
+   
+## Types of setups
+
+OpenSpec has three setups. The rest of this page uses these names:
+
+- **repo-local**: OpenSpec inside your repo, no store. The default.
+- **store-only**: your repo keeps no specs or changes of its own. Everything lives in the store.
+- **store-optional**: your project has its own `openspec/` folder and also reaches a store when you ask.
+
+### The default: OpenSpec inside your repo (`repo-local`)
+
+`openspec init` puts an `openspec/` folder next to your code, and that repo's specs and changes live there. No store is involved. This is the setup [Set up your project](../start/setup.md) teaches, and most projects never need another.
+
+```
+web-app  (code repo)
+└── openspec/
+    ├── specs/
+    └── changes/
+```
+
+### OpenSpec outside your repo, in a store (`store-only`)
+
+The repo keeps no specs or changes of its own. Everything it plans lives in the store, and one line in the repo's config connects the two.
+
+Common when one team builds all the repos and plans in one place. The [examples above](#when-you-need-one) all have this shape.
+
+```
+team-plans  (store)
+└── openspec/
+    ├── specs/       the repo's specs live here
+    └── changes/     its changes too
+          ▲
+          │ store: team-plans   (the connecting line)
+web-app  (code repo)
+└── openspec/
+    └── config.yaml    nothing else
+```
+
+### OpenSpec in your repo and in a store (`store-optional`)
+
+The repo stays repo-local for its own work, while the store holds the shared specs and changes. Inside the repo, OpenSpec uses your project's `openspec/` folder, and reaches the store only when you pass `--store`.
+
+Common when a repo used OpenSpec before the store existed, or when a mostly independent repo only occasionally touches shared work.
+
+```
+team-plans  (store)
+└── openspec/          the shared specs and changes
+          ▲
+          │ only when you pass --store team-plans
+web-app  (code repo)
+└── openspec/          this repo's own
+    ├── config.yaml
+    ├── specs/
+    └── changes/
+```
+
+A repo can start repo-local and move its specs and changes into the store later. [Move a repo's specs and changes into the store](#move-a-repos-specs-and-changes-into-the-store) shows how.
+
+## Where artifacts get created when using stores
+
+When you use a store, OpenSpec also has to decide where the artifacts get created. It depends on your setup:
+
+- **store-only** (your project only writes to the store): every artifact is created in the store. The `store:` line below records that.
+- **store-optional** (your project has its own `openspec/` folder and also uses a store): artifacts are created in your project, unless you name the store in your request or pass `--store` for that change. Your agent then carries the flag through the rest of the workflow.
+
+OpenSpec writes artifacts to one of two places: your project's `openspec/` folder, or the store's. It picks in this order, and the first option that applies wins:
+
+1. **`--store <id>` on a command.** Always wins, from any directory.
+2. **Your project's `openspec/` folder.** If your project has its own `specs/` or `changes/` folders, OpenSpec uses them.
+3. **The `store:` line in your project.** How a store-only project records its store.
+4. **`defaultStore` on your machine.** The fallback when none of the above applies.
+
+When OpenSpec selects a store, it prints `Using OpenSpec root: ...` before the command output.
+
+### The `store:` line (store-only projects)
+
+Add one line to your project's `openspec/config.yaml`:
+
+```yaml
+# web-app/openspec/config.yaml
+store: team-plans
+```
+
+Everything you or your agent run inside your project now uses the store, with no flag to type:
+
+```bash
+# inside web-app, connected
+openspec status
+```
+
+```yaml
+Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
+No active changes. Create one with: openspec new change <name> --store team-plans
+```
+
+- **Without the line**: run a plain command in a store-only project and OpenSpec stops with an error listing your registered stores.
+- **Commit it**: teammates who clone your project get the line too. They still need the store registered on their machine ([step 3 of Set up a store](#set-up-a-store)), or OpenSpec errors and tells them to register it.
+- **Next to real folders**: if your project also has `specs/` or `changes/` folders, OpenSpec uses those and ignores the line, with a warning.
+
+### `defaultStore` on your machine
+
+Set it once if every project you work in uses the same store. OpenSpec falls back to it when it finds no flag, no local `openspec/` folder, and no `store:` line:
+
+```bash
+# use team-plans whenever nothing else names a store
+openspec config set defaultStore team-plans
+
+# undo it
+openspec config unset defaultStore
+```
+
+**Commands that stay local.** `init`, `update`, `templates`, `schemas`, and the `openspec schema` subcommands act on the current directory only and take no `--store`.
+
+## Move a repo's specs and changes into the store
+
+To take a repo from repo-local to store-only:
+
+1. Move everything in the repo's `openspec/specs/` and `openspec/changes/` into the same folders in the store.
+2. Delete the now-empty folders, so the repo's `openspec/` folder holds only `config.yaml`.
+3. Add the `store:` line to that `config.yaml`.
+
+`openspec status` inside the repo now starts with `Using OpenSpec root: team-plans`.
+
+## Work in the store
+
+The workflows don't change, for you or for your agent. Propose, apply, and archive run the way they always do. The only difference is where the artifacts get created, and [the section above](#where-artifacts-get-created-when-using-stores) covers that.
+
+Create a change from inside a store-only repo and it lands in the store:
+
+```bash
+# inside web-app; the store: line routes this to team-plans
+openspec new change add-login
+```
+
+```yaml
+Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
+Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
+Schema: spec-driven
+Next: openspec status --change add-login --store team-plans
+```
+
+- **Where it went**: into the store repo, not next to your code.
+- **Sharing it**: the change exists only in your checkout until you commit and push the store repo. Teammates see it when they pull. The same goes for every artifact the workflows write.
+- **Paths in the docs**: wherever the docs show an `openspec/` path, in a store setup that folder is the store's.
+
+When artifacts get created somewhere you didn't expect, `openspec doctor` checks your setup without changing anything and prints a fix for each finding:
+
+```bash
+# check the current root and its stores
+openspec doctor
+```
+
+```yaml
+Doctor
+
+Root
+  Location: /Users/you/openspec/team-plans
+  OpenSpec root: ok
+  Store: team-plans (metadata ok)
+
+References
+  (none declared)
+```
+
+`openspec context` lists the root and stores your current directory works with, when you want the same picture without the checks.
+
+To open the store and a repo in one editor window, so your agent can read both, see [Worksets (beta)](worksets.md).
+
+## Read specs from another store
+
+Your repo can keep its own `openspec/` folder and still let your agent read another store's specs. Declare that store under `references:` in the repo's `openspec/config.yaml`:
+
+```yaml
+# api-server/openspec/config.yaml
+references:
+  - team-plans
+```
+
+References are read-only. Your work stays in your repo, and the reference only changes what your agent is told.
+
+When a workflow creates an artifact, its instructions gain an index of the referenced store's specs, each with a one-line summary and the exact command to fetch it:
+
+```xml
+<referenced_stores>
+<!-- Read-only upstream context. Fetch what you need; cite what you use. -->
+Store team-plans (/Users/you/openspec/team-plans):
+  - payments: Rules for charging and refunding customers.
+  Fetch: openspec show <spec-id> --type spec --store team-plans
+</referenced_stores>
+```
+
+A reference can also carry the store's clone URL, for machines that don't have that store yet:
+
+```yaml
+references:
+  - team-plans
+  - { id: design-system, remote: "git@github.com:acme/design-system.git" }
+```
+
+With the URL declared, `openspec doctor` turns a missing store into a pasteable fix:
+
+```yaml
+# output wrapped to fit
+References
+  - team-plans: ok (/Users/you/openspec/team-plans)
+  - design-system: Referenced store 'design-system' is not registered on this machine.
+    Fix: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' &&
+         openspec store register '/Users/you/openspec/design-system' --id design-system
+```
+
+## Beta limits
+
+- **The shape may change**: command names, flags, and file formats can change between releases. Re-read this page after upgrading.
+- **No sync, by design**: OpenSpec never clones, pulls, or pushes. A stale checkout shows stale specs until you pull, and references are read from whatever is on disk.
+- **One checkout per store name**: registering a second folder under a name that's already registered fails, with a hint to run `openspec store unregister` first.

docs-lab/multi-repo/worksets.md

@@ -0,0 +1,62 @@
+# Worksets (beta)
+
+> Open the store and the repos that use it in one editor window, so your agent sees both.
+
+With a store, the context your agent needs is split across folders. The specs and changes live in the store, and the code lives in each repo. An agent started in one repo can read and grep that repo and nothing else, so it works from half the picture.
+
+Worksets are the utility OpenSpec provides for this. A workset is a saved, named list of folders you open together. This page assumes the store is already set up and registered on your machine. [Stores (beta)](stores.md) covers that.
+
+## How it works
+
+- **What it is**: a named list of folders, saved on your machine only. Nothing is written into the member folders, and nothing is committed.
+- **What opening does**: OpenSpec generates a `.code-workspace` file from the list and launches your editor on it. Every member folder sits in one window.
+- **What you get**: your editor's search, and any agent you run inside that window, can read every member folder. The agent can grep the store's specs and the repo's code in one session.
+- **What it doesn't change**: which `openspec/` folder a command uses. That still follows [Where artifacts get created](stores.md#where-artifacts-get-created-when-using-stores).
+
+## Set it up
+
+1. **Save the workset** (once per machine). List the repo and the store as members, and the tool to open them with:
+
+   ```bash
+   # save a named list of folders you open together
+   openspec workset create platform \
+     --member ~/src/web-app \
+     --member ~/openspec/team-plans \
+     --tool code
+   ```
+
+   ```yaml
+   Saved workset 'platform' (2 members) to your machine.
+   Open it any time with: openspec workset open platform
+   ```
+
+2. **Open it** whenever you start work:
+
+   ```bash
+   # open every member in one VS Code window
+   openspec workset open platform
+   ```
+
+`openspec workset list` shows what you saved, and `openspec workset remove <name>` deletes a workset without touching the member folders:
+
+```yaml
+platform  (opens in VS Code)
+  web-app     /Users/you/src/web-app
+  team-plans  /Users/you/openspec/team-plans
+```
+
+## Use it: one change, two folders
+
+Say the `add-login` change lives in the `team-plans` store, and the code for it lives in `web-app`. Open the `platform` workset and ask your agent to implement the change. In that one session it can:
+
+- read `team-plans/openspec/changes/add-login/` and the specs next to it
+- edit the code in `web-app/`
+- run `openspec` commands from inside `web-app`
+
+Without the workset, the agent only sees whichever folder it was started in.
+
+## Tools out of the box
+
+- **VS Code** (`--tool code`) and **Cursor** (`--tool cursor`): built in. Each opens one window with every member folder.
+- **Claude Code and Codex in the terminal**: temporarily disabled as workset openers while that flow is reworked. `--tool claude` or `--tool codex` stops with an error that says so and points you to VS Code or Cursor.
+- **Other editors**: add them under the `openers` key in [CLI settings (config.json)](../reference/configuration/config-json.md).

docs-lab/reference/architecture/design-decisions.md

@@ -0,0 +1,11 @@
+# Design decisions
+
+> Why OPSX works the way it does.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its entry is commented out in website/docs.sync.config.mjs, 2026-08-21). The file
+stays so the structure and inbound links survive; re-list it in the sync config once the
+prose lands. -->
+
+<!-- Skeleton: heading only. Split from reference/architecture.md on 2026-08-10.
+message-map.md routes "the workflow is fluid, actions not phases" here. -->

docs-lab/reference/architecture/index.md

@@ -0,0 +1,19 @@
+# Overview
+
+> How OPSX is built: internals for the curious.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its entry is commented out in website/docs.sync.config.mjs, 2026-08-21). The file
+stays so the structure and inbound links survive; re-list it in the sync config once the
+prose lands. -->
+
+<!-- Skeleton: headings only. Moved out of Legacy in review round 2 (it documents
+the current system); split from a single architecture.md page into this folder
+on 2026-08-10. -->
+
+The pages in this section:
+
+- [Workflow runs](workflow-runs.md): how a workflow run executes, from invocation to written artifacts.
+- [Design decisions](design-decisions.md): why OPSX works the way it does.
+
+## How the pieces fit

docs-lab/reference/architecture/workflow-runs.md

@@ -0,0 +1,10 @@
+# Workflow runs
+
+> How a workflow run executes, from invocation to written artifacts.
+
+<!-- WIP, on the todo list: this page is not written yet and is held back from the
+site (its entry is commented out in website/docs.sync.config.mjs, 2026-08-21). The file
+stays so the structure and inbound links survive; re-list it in the sync config once the
+prose lands. -->
+
+<!-- Skeleton: heading only. Split from reference/architecture.md on 2026-08-10. -->

docs-lab/reference/configuration/change-metadata.md

@@ -0,0 +1,62 @@
+# Change metadata (.openspec.yaml)
+
+> The supported fields and validation rules for the metadata stored with each change.
+
+## Location
+
+Each change keeps its metadata at `openspec/changes/<change-name>/.openspec.yaml`, next to its artifacts. Creating a change writes the file with `schema` and `created` filled in.
+
+## Fields
+
+| Key | Type | Required | Effect |
+| --- | --- | --- | --- |
+| `schema` | string | Yes | The workflow schema this change follows |
+| `created` | string, YYYY-MM-DD | No | Records the date the change was created |
+| `goal` | string | No | Records what the change sets out to do |
+| `affected_areas` | list of strings | No | Records the areas the change expects to touch |
+| `initiative` | map: `store` and `id` | No | Records the initiative this change belongs to |
+| `skip_specs` | boolean | No | Declares the change makes no spec deltas, so zero deltas validate |
+| `retire_capabilities` | boolean | No | Authorizes archive to delete a capability this change empties |
+
+### schema
+
+The workflow schema this change follows. It is set when the change is created and wins over the project config, so a change keeps its schema even if `openspec/config.yaml` changes afterwards. Valid names are listed in [Schemas](../schemas/index.md).
+
+### initiative
+
+The initiative this change belongs to, as a store id and an initiative id, both kebab-case:
+
+```yaml
+initiative:
+  store: platform-specs
+  id: unify-billing
+```
+
+Keys other than `store` and `id` are rejected. No command reads the link today.
+
+### skip_specs
+
+Declares the change intentionally makes no spec deltas: a pure refactor, tooling, or docs change. With it set, validation accepts zero deltas, and artifacts that would generate spec files count as complete. Setting it while spec files exist under specs/ is a validation error. Its effect on deltas and archive is on [spec-driven](../schemas/spec-driven/index.md).
+
+### retire_capabilities
+
+Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call. The archive behavior is on [spec-driven](../schemas/spec-driven/index.md).
+
+## Example
+
+A filled-in .openspec.yaml:
+
+```yaml
+schema: spec-driven
+created: 2026-08-14
+goal: Add magic-link login to the API
+affected_areas:
+  - auth
+  - api
+```
+
+## Validation
+
+The file is validated whenever a command writes or reads it. A write that fails validation throws and writes nothing. Reading an existing file fails on invalid YAML, a field that breaks its contract, or a schema name that is not available. A missing file is not an error, and the change is treated as having no metadata.
+
+Unlike [config.yaml](config-yaml.md), bad values are never dropped with a warning. A metadata error stops the command. The one exception is unknown top-level keys, which are ignored rather than rejected.

docs-lab/reference/configuration/config-json.md

@@ -0,0 +1,63 @@
+# CLI settings (config.json)
+
+> Every field of config.json: how the openspec CLI behaves on your machine.
+
+## Location
+
+The CLI keeps its machine-level settings at `~/.config/openspec/config.json` on macOS and Linux, and `%APPDATA%\openspec\config.json` on Windows. `$XDG_CONFIG_HOME` wins on every platform when set. The `openspec config` command reads and edits it.
+
+## Fields
+
+| Key | Type | Required | Effect |
+| --- | --- | --- | --- |
+| `profile` | string: `core` or `custom` | No | Picks the workflow set `openspec init` installs |
+| `delivery` | string: `both`, `skills`, or `commands` | No | Whether init installs skills, slash commands, or both |
+| `workflows` | list of strings | No | The workflow list a `custom` profile installs |
+| `featureFlags` | map: flag → boolean | No | Boolean feature toggles |
+| `defaultStore` | string | No | Machine-level fallback store for root resolution |
+| `openers` | list | No | The tools worksets open in, and how each is launched |
+| `telemetry` | map | No | State the CLI keeps: anonymous id and notice-seen |
+
+### profile
+
+Which workflow set `openspec init` installs. Defaults to `core`: propose, explore, apply, update, sync, and archive. Setting `custom` installs exactly the `workflows` list instead.
+
+### delivery
+
+Whether init installs workflows as skills, as slash commands, or both. Defaults to `both`.
+
+### workflows
+
+The workflows a `custom` profile installs; ignored when the profile is `core`. Valid ids: `propose`, `explore`, `new`, `continue`, `apply`, `update`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`.
+
+### featureFlags
+
+Boolean toggles keyed by flag name, set with `openspec config set featureFlags.<flag> true`. No flag is read by the CLI today.
+
+### defaultStore
+
+The machine-level fallback store id for root resolution, consulted only when no `--store` flag, local `openspec/`, or project `store:` pointer resolves. The full ladder is [Root resolution](../../multi-repo/stores.md#where-artifacts-get-created-when-using-stores).
+
+### openers
+
+The tools a workset can open in, and how each is launched. Entries are hand-edited and validated on use. Each may set `style` (`workspace-file` or `attach-dirs`), `label`, `command`, `args`, and `attach_flag`, and is merged over the built-in defaults.
+
+### telemetry
+
+State the CLI writes for telemetry: your anonymous id and whether the first-run notice was shown. It is not the opt-out. Disabling telemetry is an environment variable, on [Environment variables](environment-variables.md).
+
+## Example
+
+A filled-in config.json:
+
+```json
+{
+  "profile": "core",
+  "delivery": "both",
+  "featureFlags": {},
+  "telemetry": {
+    "anonymousId": "5f8a2c1e-4b6d-4f9a-9c3d-7e1b2a8d4c6f",
+    "noticeSeen": true
+  }
+}
+```

docs-lab/reference/configuration/config-yaml.md

@@ -0,0 +1,102 @@
+# Project configuration (config.yaml)
+
+> Every field of openspec/config.yaml: the schema, context, and rules this project plans with.
+
+## Location
+
+Each OpenSpec project keeps its config file at `openspec/config.yaml`, in the project root.
+
+## Fields
+
+| Key | Type | Required | Effect |
+| --- | --- | --- | --- |
+| `schema` | string | Yes | The workflow schema this project's changes follow |
+| `context` | string | No | Injected into every artifact's instructions |
+| `rules` | map: artifact ID → list of strings | No | Extra rules added to one artifact's built-in guidance |
+| `operations` | map: operation → guidance list | No | Advisory guidance for apply and archive work |
+| `store` | string | No | Fallback OpenSpec root when this openspec/ is config-only |
+| `references` | list | No | Stores whose specs are indexed into instructions |
+
+Invalid fields never fail a command. Each field is validated on its own, and a bad value is dropped with a warning.
+
+What to write in these fields is covered in [Project configuration](../../customize/project-config.md).
+
+### schema
+
+The workflow schema every change in this project follows. Valid values are `spec-driven` or a schema name the project defines. The names are listed in [Schemas](../schemas/index.md).
+
+### context
+
+Free text injected into every artifact's instructions. The limit is 50KB, and a larger value is ignored with a warning.
+
+### rules
+
+Extra rules for one artifact, added to the schema's built-in guidance:
+
+```yaml
+rules:
+  proposal:
+    - Keep proposals under 500 words
+```
+
+Artifact IDs are not restricted to the built-in names, so artifacts from custom schemas work as keys.
+
+### operations
+
+Advisory guidance for how apply and archive work is conducted, separate from artifact rules:
+
+```yaml
+operations:
+  apply:
+    guidance:
+      - Keep test summaries concise
+```
+
+Only `apply` and `archive` are read.
+
+### store
+
+A store id used as the OpenSpec root, consulted only when this openspec/ directory is config-only (no specs/ or changes/). It is a fallback, never an override. The full ladder is [Root resolution](../../multi-repo/stores.md#where-artifacts-get-created-when-using-stores).
+
+### references
+
+Store ids whose specs this project's work draws on. An index of each store's specs (id, summary, fetch command) is added to instructions output. Spec content is never inlined, and root resolution is never affected. An entry is a store id or a map with `id` and an optional `remote` clone source:
+
+```yaml
+references:
+  - platform-specs
+  - id: billing-specs
+    remote: git@github.com:acme/billing-specs.git
+```
+
+## Example
+
+A filled-in config.yaml:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  We use conventional commits
+  Domain: e-commerce platform
+
+rules:
+  proposal:
+    - Keep proposals under 500 words
+    - Always include a "Non-goals" section
+  tasks:
+    - Break tasks into chunks of max 2 hours
+
+operations:
+  apply:
+    guidance:
+      - Keep test summaries concise
+  archive:
+    guidance:
+      - Summarize the archive outcome before finishing
+```
+
+## Legacy names
+
+`openspec/config.yml` is read as an alias when `config.yaml` does not exist. When both files exist, `config.yaml` wins and `config.yml` is ignored. `openspec init` creates `config.yaml`.

docs-lab/reference/configuration/environment-variables.md

@@ -0,0 +1,14 @@
+# Environment variables
+
+> Every environment variable OpenSpec reads.
+
+<!-- Skeleton: headings only. This page is the telemetry opt-out's home
+(README TODO): OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, auto-disabled in CI, plus
+what's collected. start/installation.md's Deno section links here to explain
+its network-permission flag. XDG vars move the config/data directories. -->
+
+## OPENSPEC_TELEMETRY
+
+## DO_NOT_TRACK
+
+## XDG_CONFIG_HOME and XDG_DATA_HOME

docs-lab/reference/configuration/index.md

@@ -0,0 +1,11 @@
+# Overview
+
+> Every file and setting that changes how OpenSpec behaves, and where each lives.
+
+| File | Lives at | Controls |
+| --- | --- | --- |
+| [Project configuration (config.yaml)](config-yaml.md) | `openspec/config.yaml` | The schema, context, and rules this project plans with |
+| [Change metadata (.openspec.yaml)](change-metadata.md) | `openspec/changes/<name>/.openspec.yaml` | The workflow schema, goal, scope, and spec exceptions for one change |
+| [CLI settings (config.json)](config-json.md) | `~/.config/openspec/config.json` (Windows varies) | How the openspec CLI behaves on your machine |
+| [Environment variables](environment-variables.md) | Your shell or CI environment | Telemetry opt-out, and where the config and data directories live |
+| Stores | `~/.local/share/openspec/stores/` (Windows varies) | The registry and metadata behind multi-repo stores |

docs-lab/reference/configuration/stores.md

@@ -0,0 +1,22 @@
+# Stores
+
+> The files behind multi-repo stores: registry.yaml and store.yaml, and which root a command uses.
+
+<!-- Skeleton: headings only. Beta, like the multi-repo group. Machine-maintained
+rather than hand-edited; documented so readers can inspect and repair them. The
+concept and workflow live in multi-repo/stores.md. Root resolution is the
+contract from src/core/root-selection.ts: --store flag, else nearest ancestor
+openspec/, else a config-only openspec/'s store: pointer, else the global
+defaultStore, else error. This page owns the whole ladder including the
+everyday case (nearest openspec/ wins); the section's Overview only links
+here. Locations (store/foundation.ts): registry.yaml at <dataDir>/stores/
+(~/.local/share/openspec/stores/); store.yaml at .openspec-store/store.yaml
+inside each checkout. The glossary's "OpenSpec root" row links here. -->
+
+## registry.yaml
+
+## store.yaml
+
+## Locations
+
+## Root resolution

docs-lab/reference/glossary.md

@@ -0,0 +1,40 @@
+# Glossary
+
+> Every OpenSpec term, one line each.
+
+OpenSpec reuses words that mean something else in git, CI, and agent tooling. Each row gives the OpenSpec meaning, and the last column links to the page that teaches the term.
+
+| Term | Definition | More |
+|---|---|---|
+| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](../guides/apply.md) |
+| **Archive** | Complete a change proposal: merge its deltas into the main specs and move its folder to `openspec/changes/archive/`. | [Quickstart](../start/quickstart.md) |
+| **Artifact** | A planning document inside a change proposal: `proposal.md`, delta specs, `design.md`, `tasks.md`. Not a build output. | [Concepts](../guides/concepts.md) |
+| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
+| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Concepts](../guides/concepts.md) |
+| **Command** | A typed entry point for a workflow. Spelling varies per tool (`/opsx:propose`, `/opsx-propose`). The docs name workflows by skill instead. | [Supported tools](supported-tools.md) |
+| **Continue** | Create the next planning artifact for an existing change proposal. Skill: `openspec-continue-change`. | [Skills](skills.md) |
+| **Delivery** | How workflows are installed: as skills, commands, or both. | [Set up your project](../start/setup.md) |
+| **Delta spec** | A spec inside a change proposal listing only what changes, under `ADDED`, `MODIFIED`, `REMOVED`, and `RENAMED` headers. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
+| **Explore** | Think an idea through with the agent before proposing. Writes no code. Skill: `openspec-explore`. | [Explore an idea](../guides/explore.md) |
+| **Fast-forward** | Create a change proposal with every planning artifact in one pass, ready to implement. Skill: `openspec-ff-change`. Not a git fast-forward. | [Skills](skills.md) |
+| **Legacy workflow** | The pre-OPSX `/openspec:*` commands. | [Migration](../help/legacy/migration.md) |
+| **Loop** | The cycle a change proposal moves through: explore, propose, review, apply, archive. | [Quickstart](../start/quickstart.md) |
+| **Main specs** | The `openspec/specs/` tree: the current, agreed behavior of your system. Archiving merges deltas into it. | [Concepts](../guides/concepts.md) |
+| **OpenSpec root** | The `openspec/` tree a command resolves to and operates on: your repo's, or a store's. | [Stores](../multi-repo/stores.md#where-artifacts-get-created-when-using-stores) |
+| **OPSX** | The current OpenSpec workflow system, and the command prefix it installs (`/opsx:`). | [Architecture](architecture/index.md) |
+| **Profile** | Which workflows init installs: `core` or `custom`. | [Profiles](../customize/profiles.md) |
+| **Propose** | Create a change proposal and generate all its planning artifacts in one step. Skill: `openspec-propose`. | [Quickstart](../start/quickstart.md) |
+| **Registry** | The machine-level list of registered stores, in `registry.yaml`. Not a package registry. | [CLI](cli.md#openspec-store) |
+| **Requirement** | One behavior the system must have, written with SHALL: `### Requirement:` in a spec. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
+| **Scenario** | A testable example under a requirement, in WHEN/THEN form. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
+| **Schema** | The definition of which artifacts a change proposal produces, and in what order. Not JSON Schema. | [Schemas](schemas/index.md) |
+| **Skill** | A workflow's instructions, installed where your AI tool reads them (`.agents/skills/`, ...). | [Skills](skills.md) |
+| **Spec** | A file describing how one capability behaves today, at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
+| **spec-driven** | The default schema: proposal, then delta specs, then design, then tasks. | [spec-driven](schemas/spec-driven/index.md) |
+| **Store** | A standalone OpenSpec repo registered on your machine, for planning that spans repositories. Not a data store. | [Stores (beta)](../multi-repo/stores.md) |
+| **Sync** | Merge implemented deltas into the main specs without archiving. Skill: `openspec-sync-specs`. | [Skills](skills.md) |
+| **Template** | The starting content a schema gives each artifact. | [Schemas](../customize/schemas.md) |
+| **Update** | As a skill (`openspec-update-change`): revise a change proposal's planning artifacts. As a CLI command (`openspec update`): refresh OpenSpec's installed files. | [Change course](../guides/change-course.md), [CLI](cli.md) |
+| **Verify** | Check the implementation matches a change proposal's artifacts before archiving. Skill: `openspec-verify-change`. | [Skills](skills.md) |
+| **Workflow** | A named OpenSpec action (propose, apply, archive, ...), installed into your AI tool as a skill or command. | [Set up your project](../start/setup.md) |
+| **Workset** | A personal, local group of folders opened together in one tool. Not a store, and nothing is shared. | [Worksets (beta)](../multi-repo/worksets.md) |

docs-lab/reference/schemas/index.md

@@ -0,0 +1,20 @@
+# Overview
+
+> Every available workflow schema and the artifacts it defines.
+
+<!-- This group states the formats. How schemas shape artifacts and how to
+change or write one is customize/schemas.md's job. -->
+
+A schema defines which artifacts a change proposal produces, and in what order. On disk it's a folder with a schema.yaml in it. Every field of that file is on the [schema.yaml](schema-yaml.md) page.
+
+## Available schemas
+
+One schema ships with the CLI:
+
+| Schema | Artifacts |
+|---|---|
+| [spec-driven](spec-driven/index.md) (default) | `proposal`, `specs`, `design`, `tasks` |
+
+A project can add its own schemas, and a machine can override globally. Where those folders live and which copy wins is in schema.yaml's [Location](schema-yaml.md#location) section.
+
+In your terminal, [`openspec schemas`](../cli.md#openspec-schemas) prints every schema your project can see.

docs-lab/reference/schemas/schema-yaml.md

@@ -0,0 +1,209 @@
+# schema.yaml
+
+> Every field of a schema definition, for reading or writing one.
+
+`schema.yaml` lists the planning files a workflow creates. It also defines their order and the handoff to implementation.
+
+## Location
+
+A project schema lives under `openspec/schemas/<name>/`:
+
+```text
+openspec/schemas/review-first/
+├── schema.yaml
+└── templates/
+    ├── proposal.md
+    └── tasks.md
+```
+
+OpenSpec checks three places for that directory. The first match wins.
+
+| Copy | Directory |
+|---|---|
+| **1. Project** | `<project>/openspec/schemas/<name>/` |
+| **2. User, macOS and Linux** | `~/.local/share/openspec/schemas/<name>/` |
+| **2. User, Windows** | `%LOCALAPPDATA%\openspec\schemas\<name>\` |
+| **3. Package** | The schemas installed with the CLI |
+
+If `XDG_DATA_HOME` is set, the user directory moves to `$XDG_DATA_HOME/openspec/schemas/<name>/` on every platform.
+
+The directory name is the lookup key used by `--schema`, `config.yaml`, and [`.openspec.yaml`](../configuration/change-metadata.md#schema). If the `name` field differs from the directory name, OpenSpec still uses the directory name for lookup.
+
+[`openspec schema which <name>`](../cli.md#openspec-schema-which) prints the active directory and any lower-priority copies it hides.
+
+## Top-level fields
+
+| Field | Contract |
+|---|---|
+| `name` | **Required.** A non-empty string stored as the schema name. Lookup still uses the directory name. |
+| `version` | **Required.** A positive integer stored as the schema revision. The value doesn't change OpenSpec's behavior. |
+| `description` | An optional string printed by `openspec schemas`. With no value, the schema has no description. |
+| `artifacts` | **Required.** A non-empty list of [artifact entries](#artifact-fields). |
+| `apply` | Optional [apply settings](#apply-fields). With no block, OpenSpec uses the [apply defaults](#apply-defaults). |
+
+## Artifact fields
+
+Each entry under `artifacts` defines one planning file or set of files.
+
+| Field | Contract |
+|---|---|
+| `id` | **Required.** A unique, non-empty string used in dependencies, project rules, commands, and apply settings. |
+| `generates` | **Required.** A relative path or glob telling the agent where to write the artifact inside the change folder. |
+| `description` | **Required.** A string that labels the artifact in instructions sent to the agent. |
+| `template` | **Required.** A relative path to the artifact's format in the schema's `templates/` folder. |
+| `instruction` | Optional guidance telling the agent what content to produce. |
+| `requires` | A list of artifact IDs that must be complete first. Default: `[]`. |
+
+### `generates`
+
+The path starts from the change folder. For a change named `add-auth`:
+
+```yaml
+generates: proposal.md
+```
+
+The artifact goes here:
+
+```text
+openspec/changes/add-auth/proposal.md
+```
+
+A glob can match several files:
+
+```yaml
+generates: specs/**/*.md
+```
+
+This matches Markdown files below `openspec/changes/add-auth/specs/`. OpenSpec treats a value containing `*`, `?`, or `[` as a glob.
+
+OpenSpec rejects absolute paths and paths containing a `..` segment.
+
+#### Completion
+
+OpenSpec checks whether the output exists. It doesn't read the file to decide whether the artifact is complete.
+
+| `generates` value | Complete when |
+|---|---|
+| `proposal.md` | That file exists. |
+| `specs/**/*.md` | The glob matches at least one file. |
+
+### `template`
+
+The path starts from the schema's `templates/` folder. In the `review-first` schema:
+
+```yaml
+template: proposal.md
+```
+
+OpenSpec reads this file:
+
+```text
+openspec/schemas/review-first/templates/proposal.md
+```
+
+OpenSpec gives the template's contents to the agent as the output format. It doesn't copy the template into the change folder.
+
+OpenSpec rejects absolute paths and paths containing a `..` segment.
+
+### `requires`
+
+- **Dependencies**: every ID in `requires` must name another artifact in the same schema.
+- **Ready state**: an artifact becomes ready after all its dependencies are complete.
+- **Invalid graphs**: missing IDs, duplicate IDs, and dependency cycles fail validation.
+- **Ties**: when several artifacts are ready, their order in `artifacts` decides which one OpenSpec returns first.
+
+## Apply fields
+
+`apply` defines what must exist before implementation starts.
+
+| Field | Contract |
+|---|---|
+| `requires` | **Required.** A non-empty list of artifacts that must exist before apply instructions become ready. |
+| `tracks` | An optional relative path to a Markdown task file in the change folder. Default: `null`. |
+| `instruction` | Optional guidance sent to the agent when apply is ready. OpenSpec uses built-in guidance by default. |
+
+Artifact `requires` controls planning order. `apply.requires` controls when apply instructions become ready.
+
+### `tracks`
+
+The path starts from the change folder. For a change named `add-auth`, `tracks: tasks.md` reads:
+
+```text
+openspec/changes/add-auth/tasks.md
+```
+
+Apply stays blocked if that file is missing or contains no checkbox with task text. OpenSpec counts these checkbox forms:
+
+```markdown
+- [ ] Pending task
+- [x] Completed task
+* [X] Completed task
+```
+
+Leading spaces are allowed. The [tasks.md section of the spec-driven page](spec-driven/index.md#tasksmd) defines the stricter format produced by the default schema.
+
+The tracked file drives the apply state:
+
+- **`blocked`**: the file is missing, or no checkbox has task text.
+- **`ready`**: at least one tracked task is pending.
+- **`all_done`**: every tracked task is checked.
+
+OpenSpec rejects absolute paths and paths containing a `..` segment.
+
+### Apply defaults
+
+| Behavior | Default |
+|---|---|
+| Required artifacts | Every artifact in the schema |
+| Progress tracking | No tracked file |
+| Agent guidance | Built-in apply guidance |
+
+## Complete example
+
+```yaml
+name: review-first
+version: 1
+description: Proposal and implementation checklist
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Why the change is needed and what it affects
+    template: proposal.md
+    instruction: |
+      Explain the problem, the proposed change, and its impact.
+    requires: []
+
+  - id: tasks
+    generates: tasks.md
+    description: Trackable implementation checklist
+    template: tasks.md
+    instruction: |
+      Break the approved proposal into ordered implementation tasks.
+    requires:
+      - proposal
+
+apply:
+  requires:
+    - tasks
+  tracks: tasks.md
+  instruction: |
+    Work through the pending tasks and mark each one complete.
+```
+
+## Validation
+
+[`openspec schema validate <name>`](../cli.md#openspec-schema-validate) checks:
+
+- Field types and required fields
+- Relative paths
+- Artifact IDs, dependencies, and cycles
+- Template files
+
+Validation doesn't catch these mistakes:
+
+| Mistake | What happens |
+|---|---|
+| A field is misspelled, such as `instrution` | OpenSpec ignores it. Validation doesn't report the typo. |
+| `apply.requires` names an unknown artifact ID | Validation doesn't report the unknown ID. |
+| `name` differs from the schema directory | Validation passes. OpenSpec still uses the directory name for lookup. |

docs-lab/reference/schemas/spec-driven/index.md

@@ -0,0 +1,429 @@
+# spec-driven
+
+> The default workflow's artifacts: their order, their formats, and the change folder they produce.
+
+`spec-driven` is OpenSpec's built-in default schema. [schema.yaml](../schema-yaml.md) defines the fields it sets.
+
+## Artifacts
+
+The workflow drafts four artifacts:
+
+| Artifact | File | Purpose |
+|---|---|---|
+| [`proposal`](#proposalmd) | `proposal.md` | Why the change is needed |
+| [`specs`](#delta-specs-specmd) | `specs/<capability-path>/spec.md`, one per capability | What behavior changes |
+| [`design`](#designmd) | `design.md` | How to build it |
+| [`tasks`](#tasksmd) | `tasks.md` | The implementation checklist |
+
+## Drafting order
+
+```text
+             ┌─ specs ──┐
+proposal ────┤          ├── tasks ── apply
+             └─ design ─┘
+```
+
+Proposal comes first. Specs and design follow in either order, and tasks needs both. Implementation ([apply](#apply)) starts once `tasks.md` is in place.
+
+Two artifacts can be skipped:
+
+- **`design`**: when none of [its conditions](#designmd) apply, the agent leaves it out and drafts `tasks` anyway.
+- **`specs`**: set [`skip_specs: true`](../../configuration/change-metadata.md#skip_specs) in the change's `.openspec.yaml`.
+
+## Example change folder
+
+A change named `add-user-auth`, with every artifact drafted:
+
+```text
+openspec/changes/add-user-auth/
+├── .openspec.yaml      change metadata, written when the change is created
+├── proposal.md
+├── specs/
+│   └── user-auth/
+│       └── spec.md     one delta spec per capability
+├── design.md
+└── tasks.md
+```
+
+## proposal.md
+
+Establishes why the change is needed.
+
+### Structure
+
+The template the agent receives as the output format ([templates/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/proposal.md)):
+
+```md
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
+     (e.g., user-auth or identity/user-auth) that follow the project's existing
+     spec organization. Each creates specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
+     changes. A change with no capabilities at all (pure refactor, tooling, docs)
+     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
+     a zero-delta change without that marker. Do not invent a requirement just to
+     satisfy validation. -->
+- `<existing-capability-path>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->
+```
+
+### Instructions
+
+The instruction sent to the agent when it drafts this artifact (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+```md
+Create the proposal document that establishes WHY this change is needed.
+
+Sections:
+- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+- **Capabilities**: Identify which specs will be created or modified:
+  - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+  - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
+- **Impact**: Affected code, APIs, dependencies, or systems.
+
+IMPORTANT: The Capabilities section is critical. It creates the contract between
+proposal and specs phases. Research existing specs before filling this in.
+Each capability listed here will need a corresponding spec file.
+
+Every change must either declare at least one capability (new or
+modified) or explicitly opt out of specs: `openspec validate` rejects a
+change with zero deltas unless the change's `.openspec.yaml` sets
+`skip_specs: true`. Use `skip_specs: true` only when no spec-level
+behavior changes (pure refactor, tooling, docs) - specs describe
+behavior, so if behavior does not change, no spec should change either.
+Do not invent a requirement just to satisfy validation.
+
+Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+implementation details belong in design.md.
+
+This is the foundation - specs, design, and tasks all build on this.
+```
+
+## Delta specs (spec.md)
+
+Defines what behavior changes, with one delta spec per capability the proposal lists.
+
+### Structure
+
+The template the agent receives as the output format ([templates/spec.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/spec.md)):
+
+```md
+## Purpose
+<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
+
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->
+```
+
+### Instructions
+
+The instruction sent to the agent when it drafts this artifact (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+````md
+Create specification files that define WHAT the system should do.
+
+A spec is a behavior contract, not an implementation plan.
+
+Good spec content:
+- Observable behavior users or downstream systems rely on
+- Inputs, outputs, and error conditions
+- External constraints (security, privacy, reliability, compatibility)
+- Scenarios that can be tested or explicitly validated
+
+Avoid in specs:
+- Internal class/function names
+- Library or framework choices
+- Step-by-step implementation details
+- Detailed execution plans (those belong in design.md or tasks.md)
+
+Quick test: if the implementation can change without changing externally
+visible behavior, it likely does not belong in the spec.
+
+Create one spec file per capability listed in the proposal's Capabilities section.
+`<capability-path>` is the spec directory relative to `specs/` (for example,
+`user-auth` or `identity/user-auth`). Preserve the full path:
+- New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
+- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+
+There must be at least one spec file unless the change's `.openspec.yaml`
+sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
+rejects a zero-delta change without that marker. If the proposal lists no
+capabilities and `skip_specs` is not set, revisit the proposal first.
+
+Delta operations (use ## headers):
+- **ADDED Requirements**: New capabilities
+- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+Format requirements:
+- Each requirement: `### Requirement: <name>` followed by description
+- Use SHALL/MUST for normative requirements (avoid should/may)
+- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+- Every requirement MUST have at least one scenario.
+
+New capabilities only: start the delta spec with a `## Purpose` section -
+one or two sentences (50+ characters, or `openspec validate --strict`
+reports it as too brief) describing what the capability is for. Archive
+copies it into the main spec it creates; without it the new main spec is
+left with a `TBD ... Update Purpose after archive` placeholder to fill in
+by hand. Do NOT add `## Purpose` to a delta for an existing capability -
+that spec already has one and the delta's is ignored. To change an
+existing capability's Purpose - including a leftover `TBD` placeholder -
+edit `openspec/specs/<capability-path>/spec.md` directly.
+
+MODIFIED requirements workflow:
+1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
+2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+4. Ensure header text matches exactly (whitespace-insensitive)
+
+Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+If adding new concerns without changing existing behavior, use ADDED instead.
+
+Example (a new capability, so it opens with `## Purpose`):
+```
+## Purpose
+
+Lets users take their data out of the product in a portable format.
+
+## ADDED Requirements
+
+### Requirement: User can export data
+The system SHALL allow users to export their data in CSV format.
+
+#### Scenario: Successful export
+- **WHEN** user clicks "Export" button
+- **THEN** system downloads a CSV file with all user data
+
+## REMOVED Requirements
+
+### Requirement: Legacy export
+**Reason**: Replaced by new export system
+**Migration**: Use new export endpoint at /api/v2/export
+```
+
+Specs should be testable - each scenario is a potential test case.
+````
+
+## design.md
+
+Explains how to implement the change. Drafted only when the change needs one.
+
+### Structure
+
+The template the agent receives as the output format ([templates/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/design.md)):
+
+```md
+## Context
+
+<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions with rationale and alternatives considered -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->
+```
+
+### Instructions
+
+The instruction sent to the agent when it drafts this artifact (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+```md
+Create the design document that explains HOW to implement the change.
+
+When to include design.md (create only if any apply):
+- Cross-cutting change (multiple services/modules) or new architectural pattern
+- New external dependency or significant data model changes
+- Security, performance, or migration complexity
+- Ambiguity that benefits from technical decisions before coding
+
+Sections:
+- **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
+- **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
+- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+- **Open Questions**: Unknowns that can safely be answered later without
+  changing the specs, the approach, or the task breakdown. Omit if none.
+
+Open questions are for genuinely deferrable unknowns, not decisions you
+skipped. If a question would change the specs, the chosen approach, or
+the task breakdown, resolve it now - ask the user instead of guessing.
+
+Focus on architecture and approach, not line-by-line implementation.
+The proposal covers why and what; design covers how. Reference the
+proposal for motivation and, once written, the specs for requirements -
+if a section would only restate them, point to them instead.
+
+Good design docs explain the "why" behind technical decisions.
+```
+
+## tasks.md
+
+Breaks the implementation into checkable tasks. [apply](#apply) tracks progress here.
+
+### Structure
+
+The template the agent receives as the output format ([templates/tasks.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/tasks.md)):
+
+```md
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->
+```
+
+### Instructions
+
+The instruction sent to the agent when it drafts this artifact (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+````md
+Create the task list that breaks down the implementation work.
+
+Before writing tasks, check design.md for Open Questions. If any of them
+would change what gets built, resolve them with the user first - do not
+bake an unstated assumption into the task list.
+
+**IMPORTANT: Follow the template below exactly.** The apply phase parses
+checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+Guidelines:
+- Group related tasks under ## numbered headings
+- Each task MUST be a checkbox: `- [ ] X.Y Task description`
+- Tasks should be small enough to complete in one session
+- Order tasks by dependency (what must be done first?)
+
+Example:
+```
+## 1. Setup
+
+- [ ] 1.1 Create new module structure
+- [ ] 1.2 Add dependencies to package.json
+
+## 2. Core Implementation
+
+- [ ] 2.1 Implement data export function
+- [ ] 2.2 Add CSV formatting utilities
+```
+
+Reference specs for what needs to be built, design for how to build it.
+Each task should be verifiable - you know when it's done.
+````
+
+## Apply
+
+The handoff from planning to implementation. Apply is the phase that works through `tasks.md`, not an artifact.
+
+- **Starts**: once `tasks.md` exists and lists at least one task.
+- **Tracks**: the checkboxes in `tasks.md`. Checking them off is the progress record.
+- **Ends**: every checkbox checked. OpenSpec then suggests archiving the change.
+
+### Settings
+
+The apply settings (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+```yaml
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  # instruction: shown below
+```
+
+### Instructions
+
+The instruction sent to the agent when implementation starts (from [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)):
+
+```md
+Read context files, work through pending tasks, mark complete as you go.
+Pause if you hit blockers or need clarification.
+```
+
+## schema.yaml
+
+The complete [schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml), with instruction bodies elided. Each is shown in full in its section above.
+
+```yaml
+name: spec-driven
+version: 1
+description: Default OpenSpec workflow - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    # instruction: shown in full under proposal.md above
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    # instruction: shown in full under Delta specs above
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    # instruction: shown in full under design.md above
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    # instruction: shown in full under tasks.md above
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  # instruction: shown in full under Apply above
+```

docs-lab/reference/skills.md

@@ -0,0 +1,176 @@
+# Skills
+
+> Every OpenSpec skill: arguments, what it creates, and what it responds with.
+
+<!-- Drafted 2026-08-11 via one subagent per entry, each verifying every claim against
+its workflow template in src/core/templates/workflows/; assembled and uniformity-passed
+by the main session. Terminology: "change proposal", never bare "change" (user call,
+2026-08-11). Shape (user-reviewed): intro bullets define Core/Optional, then ONE index
+table (Skill / Job / Type) and a flat run of H2 entries matching
+cli.md's shape - no group sections. Recipe per entry: one-line job sentence, then a
+two-column key-value table (header row "Contract | Description", uniform across
+entries) holding the pure input/output contract,
+one row per fact: Arguments (what you pass; each cell self-contains its
+optional/ambiguous behavior) / Creates (exact paths written; always states the code
+boundary) / Response (what the agent reports back and where it stops). No judgment
+rows: no when-to-use beyond the job sentence, no Not-for routing, no guide links
+(guides link here, not the reverse). The ff job says "create a change proposal"
+because its template unconditionally scaffolds a new one (redirects if the name
+exists), contradicting the old "remaining artifacts" framing. Paths shown are the
+default single-repo layout, stated without a caveat: reference pages state defaults,
+and the store-moves-the-planning-home fact is multi-repo/stores.md's to teach (the
+per-tool command spelling story likewise stays with setup.md and supported-tools.md;
+user cut the NOTE carrying both, 2026-08-11). H2 entries double as the site's
+right-rail TOC and the anchors guides deep-link. No frontmatter in source: sync-docs.mjs lifts H1 to title and the > line to
+description (README pins the > line verbatim in its page index). Deliberately
+excluded, each with an owner elsewhere: per-tool command spellings and syntax
+(reference/supported-tools.md), example transcripts (quickstart and guides), tips and
+when-to-use judgment (guides own it), troubleshooting (help/troubleshooting.md),
+legacy /openspec:* commands (help/legacy/migration.md). Source: old docs/commands.md
+maps here per sources.md; its unsupported claims (apply "runs tests", bulk-archive
+name arguments, fixed tasks.md filename) were checked against templates and dropped.
+Skill names from WORKFLOW_TO_SKILL_DIR (src/core/profile-sync-drift.ts) and the
+templates in src/core/templates/workflows/; core set src/core/profiles.ts:14. "Optional"
+is the docs' set label (was "Expanded"; renamed 2026-08-12: the product's only stored
+profile values are core and custom, so "expanded" reads as a third profile). -->
+
+The skills come in two sets:
+
+- **Core**: installed by default, the main planning loop.
+- **Optional**: installed only when you add them, via [Profiles](../customize/profiles.md).
+
+| Skill | Job | Type |
+|---|---|---|
+| [openspec-explore](#openspec-explore) | Think through an idea before it becomes a change proposal | Core |
+| [openspec-propose](#openspec-propose) | Create a change proposal with all its planning artifacts in one step | Core |
+| [openspec-apply-change](#openspec-apply-change) | Implement a change proposal's tasks | Core |
+| [openspec-update-change](#openspec-update-change) | Revise a change proposal's plan | Core |
+| [openspec-sync-specs](#openspec-sync-specs) | Merge a change proposal's spec updates into `specs/` | Core |
+| [openspec-archive-change](#openspec-archive-change) | Move a finished change proposal to the archive | Core |
+| [openspec-new-change](#openspec-new-change) | Start a change proposal as an empty scaffold | Optional |
+| [openspec-continue-change](#openspec-continue-change) | Create the next planning artifact, one at a time | Optional |
+| [openspec-ff-change](#openspec-ff-change) | Create a change proposal with every artifact implementation needs, in one pass | Optional |
+| [openspec-verify-change](#openspec-verify-change) | Check the implementation matches the plan | Optional |
+| [openspec-bulk-archive-change](#openspec-bulk-archive-change) | Archive several change proposals at once | Optional |
+| [openspec-onboard](#openspec-onboard) | Learn the workflow by doing one real change proposal end to end | Optional |
+
+## openspec-explore
+
+Think through an idea before it becomes a change proposal.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A topic: an idea, a problem, a comparison, or the name of an existing change proposal to explore in context. With nothing given it enters explore mode. |
+| **Creates** | Nothing by default. It reads and investigates only. On request it captures insights: a new change proposal under `openspec/changes/<name>/`, or updates to an existing one's proposal, design, specs, or tasks. Never code. |
+| **Response** | An open conversation with no required output. When thinking crystallizes it summarizes the problem, approach, open questions, and next steps, and offers to capture them. You decide. Implementation never starts here. |
+
+## openspec-propose
+
+Create a change proposal and generate all its planning artifacts in one step.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A kebab-case name (`add-dark-mode`) or a plain description. Asks if you give neither. |
+| **Creates** | `openspec/changes/<name>/` with every artifact the schema defines, in dependency order (spec-driven: proposal, spec deltas, design, tasks). Never code. |
+| **Response** | The created artifacts, ready for review, and the next step. Stops there; implementation waits for `openspec-apply-change`. |
+
+## openspec-apply-change
+
+Implement a change proposal's tasks, working through the list until done or blocked.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name (`add-auth`), optional. If the target is ambiguous it lists the active change proposals and asks you to pick. |
+| **Creates** | Code: the minimal changes each task calls for, in your project files. In the change proposal it touches only the tasks file, checking off each finished task (`- [ ]` to `- [x]`). |
+| **Response** | Progress per task, then an overall count (N/M tasks complete). All done: suggests `openspec-archive-change`. Blocked by missing artifacts: points to `openspec-continue-change`. Unclear tasks or errors: pauses and asks. |
+
+## openspec-update-change
+
+Revise a change proposal's existing planning artifacts and keep them coherent with each
+other.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name, optional, plus the revision you want. With no revision stated it runs a coherence review: artifacts checked against each other for contradictions, gaps, and duplication. |
+| **Creates** | Nothing new. Edits only artifact files that already exist. Missing artifacts are `openspec-continue-change`'s job. Never code. |
+| **Response** | Shows each proposed revision and writes it only after you confirm, one artifact at a time. Ends with what was revised and the next step; implementation waits for `openspec-apply-change`. |
+
+## openspec-sync-specs
+
+Merge a change proposal's spec updates into `specs/` without archiving it.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name, optional. You can also name a subset of its delta specs, and only those sync. |
+| **Creates** | Edits or creates `openspec/specs/<capability-path>/spec.md` for each delta spec, merging added, modified, removed, and renamed requirements into the main spec. Never code. |
+| **Response** | A per-capability summary of requirements added, modified, removed, or renamed, after the updated specs validate. The change proposal stays active; archiving waits for `openspec-archive-change`. |
+
+## openspec-archive-change
+
+Move a finished change proposal to the archive.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name, optional. |
+| **Creates** | Moves the change proposal folder to `openspec/changes/archive/YYYY-MM-DD-<name>/` (no date added if the name already starts with one). With your approval it first syncs outstanding delta specs via `openspec-sync-specs`. Never code. |
+| **Response** | Warns and asks before archiving with incomplete artifacts or tasks, and asks whether to sync when delta specs exist. Ends with a summary: name, schema, archive location, spec sync status, and any warnings. |
+
+## openspec-new-change
+
+Start a change proposal as an empty scaffold.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A kebab-case name (`add-user-auth`) or a plain description, plus a schema name only for a non-default workflow. Asks what you want to build if you give neither. |
+| **Creates** | `openspec/changes/<name>/` as an empty scaffold: no artifacts yet, never code. |
+| **Response** | The scaffold's name and location, the workflow's artifact sequence, status (0/N complete), and the first artifact's template. Drafting artifacts waits for `openspec-continue-change`. |
+
+## openspec-continue-change
+
+Create the next planning artifact in a change proposal, one at a time.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name, optional. If still ambiguous it asks you to pick from the most recently modified. |
+| **Creates** | The single next ready artifact in the schema's sequence, written into the change proposal folder. One artifact per run, never code. |
+| **Response** | The created artifact, progress (N of M complete), and which artifacts that unlocked. When planning is complete it says so; implementation moves to `openspec-apply-change`. |
+
+## openspec-ff-change
+
+Create a change proposal and every planning artifact implementation needs, in one pass.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A kebab-case name or a plain description. Asks if you give neither. If the named change proposal already exists it suggests continuing it instead. |
+| **Creates** | `openspec/changes/<name>/` and every planning artifact implementation requires, in dependency order (spec-driven: proposal, specs, design, tasks), leaving out only artifacts marked skipped or conditional. Never code. |
+| **Response** | The change proposal's name and location, each artifact created, and any conditional artifact skipped and why. Stops there; implementation waits for `openspec-apply-change`. |
+
+## openspec-verify-change
+
+Check that the implementation matches the change proposal's artifacts.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | A change proposal name, optional. When ambiguous it asks, listing change proposals that have a tasks artifact. |
+| **Creates** | Nothing. It reads the change proposal's artifacts and the codebase. Verification is report-only. |
+| **Response** | A report: a scorecard for Completeness, Correctness, and Coherence, then CRITICAL, WARNING, and SUGGESTION issues with recommendations, and a final archive-readiness assessment. It changes nothing and does not archive. |
+
+## openspec-bulk-archive-change
+
+Archive several change proposals at once.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | None. It lists the active change proposals and asks you to select any number, with an option for all. If none are active it says so and stops. |
+| **Creates** | `openspec/changes/archive/YYYY-MM-DD-<name>/` per archived change proposal (already-dated names keep their prefix). Each one's spec deltas sync first via `openspec-sync-specs`. Never code. |
+| **Response** | A status table per change proposal and one confirmation for the whole batch, then a summary of archived, skipped, and failed, plus spec sync results. When two change proposals touch the same spec it checks the codebase and syncs implemented deltas oldest first. |
+
+## openspec-onboard
+
+Learn the workflow by doing one real change proposal end to end.
+
+| Contract | Description |
+|---|---|
+| **Arguments** | None. It scans your codebase for small starter tasks and asks you to pick one or describe your own. |
+| **Creates** | A real change proposal for the chosen task, one artifact at a time, then real code once you confirm implementation. Archives the change proposal at the end. |
+| **Response** | A narrated walkthrough of the full cycle with pauses for your input: explore, create, build each artifact, implement, archive. Ends with a recap and a pointer to `openspec-propose`. Takes about 15 to 20 minutes. |

docs-lab/reference/supported-tools.md

@@ -0,0 +1,132 @@
+# Supported tools
+
+> Which AI coding tools OpenSpec supports, and each one's command syntax.
+
+Every tool in the matrix runs the same OpenSpec workflows. A skill and its command are
+the same workflow instructions. The only difference is what you type. Which form init
+installs is the delivery setting, covered in
+[Set up your project](../start/setup.md#the-workflow-files-skills-and-commands).
+
+## Support matrix
+
+Invocations are shown for the apply workflow. Every workflow follows the same shape.
+The id goes to `openspec init --tools <id>` to skip the picker ([CLI](cli.md)).
+
+| Tool | `--tools` id | Skills | Skill invocation | Commands | Command invocation |
+|---|---|---|---|---|---|
+| Amazon Q Developer | `amazon-q` | `.amazonq/skills/` | `/openspec-apply-change` | `.amazonq/prompts/` | `@opsx-apply` |
+| Antigravity | `antigravity` | `.agents/skills/` | `/openspec-apply-change` | `.agents/workflows/` | `/opsx-apply` |
+| Auggie (Augment CLI) | `auggie` | `.augment/skills/` | `/openspec-apply-change` | `.augment/commands/` | `/opsx-apply` |
+| Bob Shell | `bob` | `.bob/skills/` | `/openspec-apply-change` | `.bob/commands/` | `/opsx-apply` |
+| Claude Code | `claude` | `.claude/skills/` | `/openspec-apply-change` | `.claude/commands/opsx/` | `/opsx:apply` |
+| Cline | `cline` | `.cline/skills/` | `/openspec-apply-change` | `.clinerules/workflows/` | `/opsx-apply` |
+| CodeArts | `codeartsagent` | `.codeartsdoer/skills/` | `/openspec-apply-change` | none | none |
+| CodeBuddy Code (CLI) | `codebuddy` | `.codebuddy/skills/` | `/openspec-apply-change` | `.codebuddy/commands/opsx/` | `/opsx:apply` |
+| Codex | `codex` | `.agents/skills/` | `$openspec-apply-change` | none | none |
+| Continue | `continue` | `.continue/skills/` | `/openspec-apply-change` | `.continue/prompts/` | `/opsx-apply` |
+| CoStrict | `costrict` | `.cospec/skills/` | `/openspec-apply-change` | `.cospec/openspec/commands/` | `/opsx-apply` |
+| Crush | `crush` | `.crush/skills/` | `/openspec-apply-change` | `.crush/commands/opsx/` | `/opsx:apply` |
+| Cursor | `cursor` | `.cursor/skills/` | `/openspec-apply-change` | `.cursor/commands/` | `/opsx-apply` |
+| Devin Desktop (formerly Windsurf) | `devin` | `.devin/skills/` | `/openspec-apply-change` | `.devin/workflows/` | `/opsx-apply` |
+| Factory Droid | `factory` | `.factory/skills/` | `/openspec-apply-change` | `.factory/commands/` | `/opsx-apply` |
+| ForgeCode | `forgecode` | `.forge/skills/` | `/openspec-apply-change` | none | none |
+| Gemini CLI | `gemini` | `.gemini/skills/` | `/openspec-apply-change` | `.gemini/commands/opsx/` | `/opsx:apply` |
+| GitHub Copilot | `github-copilot` | `.github/skills/` | `/openspec-apply-change` | `.github/prompts/` | `/opsx-apply` |
+| Hermes Agent | `hermes` | `.hermes/skills/` | `/openspec-apply-change` | none | none |
+| iFlow | `iflow` | `.iflow/skills/` | `/openspec-apply-change` | `.iflow/commands/` | `/opsx-apply` |
+| Junie | `junie` | `.junie/skills/` | `/openspec-apply-change` | `.junie/commands/` | `/opsx-apply` |
+| Kilo Code | `kilocode` | `.kilocode/skills/` | `/openspec-apply-change` | `.kilocode/workflows/` | `/opsx-apply` |
+| Kimi Code | `kimi` | `.kimi-code/skills/` | `/skill:openspec-apply-change` | none | none |
+| Kiro | `kiro` | `.kiro/skills/` | `/openspec-apply-change` | `.kiro/prompts/` | `/opsx-apply` |
+| Lingma | `lingma` | `.lingma/skills/` | `/openspec-apply-change` | `.lingma/commands/opsx/` | `/opsx:apply` |
+| MiniMax Code | `minimax-code` | `~/.minimax/skills/` (global) | `/openspec-apply-change` | none | none |
+| Mistral Vibe | `vibe` | `.vibe/skills/` | `/openspec-apply-change` | none | none |
+| Oh My Pi | `oh-my-pi` | `.omp/skills/` | `/openspec-apply-change` | `.omp/commands/` | `/opsx-apply` |
+| OpenCode | `opencode` | `.opencode/skills/` | `/openspec-apply-change` | `.opencode/commands/` | `/opsx-apply` |
+| Pi | `pi` | `.pi/skills/` | `/openspec-apply-change` | `.pi/prompts/` | `/opsx-apply` |
+| Qoder | `qoder` | `.qoder/skills/` | `/openspec-apply-change` | `.qoder/commands/opsx/` | `/opsx:apply` |
+| Qwen Code | `qwen` | `.qwen/skills/` | `/openspec-apply-change` | `.qwen/commands/` | `/opsx-apply` |
+| Trae | `trae` | `.trae/skills/` | `/openspec-apply-change` | `.trae/commands/` | `/opsx-apply` |
+| ZCode | `zcode` | `.zcode/skills/` | `/openspec-apply-change` | `.zcode/commands/opsx/` | `/opsx:apply` |
+| Zoo Code | `roocode` | `.roo/skills/` | `/openspec-apply-change` | `.roo/commands/` | `/opsx-apply` |
+| Shared `.agents` skills | `agents` | `.agents/skills/` | `/openspec-apply-change` | none | none |
+
+- **Skill invocation**: whether a tool registers skills as typed entries is the tool's
+  own behavior. The column shows the spelling OpenSpec uses in generated files and in
+  the hint init prints. Check your tool's docs if typing it does nothing.
+- **Command file formats**: most tools take `.md` command files. Gemini CLI takes
+  `.toml`, Continue `.prompt`, Kiro and GitHub Copilot `.prompt.md`. The spelling you
+  type is the same either way.
+
+## Per-tool notes
+
+A tool not listed here behaves exactly as its row reads.
+
+### Antigravity
+
+- **Current folder**: Antigravity v1.20.5 and later read workspace skills and
+  workflows from `.agents/`.
+- **Legacy folder**: after OpenSpec writes replacements, it removes equivalent
+  generated files from `.agent/`. Custom files and changed generated files stay in
+  `.agent/` for you to review.
+- **Shared skills**: Antigravity shares `.agents/skills/` with Codex, Zed Agent, and
+  the `agents` target. OpenSpec writes that skill tree once while still writing
+  Antigravity commands to `.agents/workflows/`.
+
+### Cline
+
+Cline reads commands from `.clinerules/workflows/`, not from its `.cline/` folder.
+Skills stay in `.cline/skills/`.
+
+### Codex
+
+- **Invocation**: type `$openspec-<skill>`. Codex does not recognize the
+  `/openspec-<skill>` form ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **No command files**: Codex runs skills directly, so init skips commands even when
+  delivery includes them and prints `Commands skipped for: codex (uses skills)`.
+- **Shared folder**: Codex skills land in `.agents/skills/`, the same tree Antigravity,
+  Zed Agent, and the `agents` target use. Selecting more than one keeps a single
+  compatible tree, and its handoffs spell both `$openspec-*` and `/openspec-*` when
+  Codex owns it.
+- **Legacy path**: skills installed under `.codex/skills/` by older versions are
+  migrated on the next `openspec update`.
+
+### Devin Desktop (formerly Windsurf)
+
+- **Two agents**: command files in `.devin/workflows/` work only in Devin Desktop.
+  Devin Local runs skills only, so generated skills reference `/openspec-<skill>`,
+  which works in both.
+- **Rename**: `--tools windsurf` still resolves to `devin`. A project holding
+  OpenSpec files in the legacy `.windsurf/` folder is offered the move on the next
+  `openspec update`.
+
+### GitHub Copilot
+
+Prompt files register as slash commands in the Copilot IDE extensions (VS Code,
+JetBrains, Visual Studio). Copilot CLI does not read `.github/prompts/`.
+
+### Hermes Agent
+
+Hermes loads skills only from `~/.hermes/skills/` by default. Add the project's
+`.hermes/skills/` folder to `skills.external_dirs` in `~/.hermes/config.yaml`;
+init prints this reminder after install.
+
+### MiniMax Code
+
+- **Global only**: skills go to `~/.minimax/skills/`. Nothing is written inside
+  the repo.
+- **Safe across projects**: a commands-only delivery leaves the global skills in
+  place, so one project's setting cannot remove skills another project uses.
+
+### Shared `.agents` skills
+
+- **When it fits**: any tool that reads the shared `.agents/skills/` folder,
+  including tools with no row in the matrix.
+- **Alongside other targets**: Antigravity, Codex, Zed Agent, and this target share
+  one physical skill tree. OpenSpec records one writer in `.openspec-target` and
+  writes the tree once per run. Each tool's separate command files are still
+  generated.
+- **What OpenSpec claims**: only the `openspec-*` folders and the
+  `.openspec-target` marker. Anything else under `.agents/` is left alone.
+- **`AGENTS.md`**: not created or edited. The target is the `.agents/` folder, not
+  the file.

docs-lab/sources.md

@@ -0,0 +1,45 @@
+# Where every current page goes
+
+The old-to-new mapping: the source material for each `docs-lab/` page while drafting,
+and the redirect list at cutover. The target structure is the page index in
+[README.md](README.md).
+
+| Current (`docs/`) | Destination |
+|---|---|
+| README.md (index) | `start/overview.md`, rewritten as pitch and routing |
+| getting-started.md | `start/quickstart.md` |
+| installation.md | split: `start/installation.md` (machine-level: matrix, update, uninstall) · `start/setup.md` (project-level: init, what init writes, skills-vs-commands delivery, stores router) |
+| how-commands-work.md | `start/quickstart.md` (inline labels) · `help/faq.md` · `help/troubleshooting.md` |
+| existing-projects.md | `guides/existing-codebases.md` ("Existing codebases"); walkthrough half to `start/quickstart.md` |
+| overview.md | `guides/concepts.md` |
+| concepts.md | `guides/concepts.md` (core) · delta format to `reference/schemas/spec-driven/index.md` (Delta specs section) · embedded glossary table deleted |
+| explore.md | `guides/explore.md` |
+| workflows.md | `guides/apply.md` (execution patterns, continue/ff) · `reference/skills.md` |
+| opsx.md | split four ways: config to `customize/project-config.md` · commands to `reference/skills.md` · philosophy to `guides/concepts.md` · architecture to `reference/architecture/` |
+| reviewing-changes.md + writing-specs.md | `guides/review-the-plan.md` (merged) |
+| editing-changes.md | `guides/change-course.md` |
+| team-workflow.md | `guides/teams.md` |
+| examples.md | parked: `guides/examples.md` skeleton kept off the index and sync config until real archived changes exist (see README TODOs) |
+| customization.md | `customize/project-config.md` + `customize/schemas.md` + `customize/overview.md` (decision ladder) · schema.yaml fields to `reference/schemas/schema-yaml.md` |
+| multi-language.md | `customize/project-config.md` §context, the "Another language" note |
+| stores-beta/user-guide.md | `multi-repo/stores.md` · worksets section to `multi-repo/worksets.md` |
+| commands.md | `reference/skills.md` (legacy `/openspec:*` section removed) |
+| cli.md | `reference/cli.md` (minus install, which moves to `start/installation.md`) |
+| supported-tools.md | `reference/supported-tools.md` |
+| glossary.md | `reference/glossary.md` |
+| faq.md | `help/faq.md` (unpublished-model claim deleted; update/uninstall to `start/installation.md`) |
+| troubleshooting.md | `help/troubleshooting.md`, canonical home for all 5 copies, plus Getting help |
+| migration-guide.md | `help/legacy/migration.md` (demoted) |
+| agent-contract.md | **off-site**, to repo-side contributor docs |
+
+New pages with no single current source: `customize/overview.md`, `customize/profiles.md`
+(today: scattered two-line fragments across 12 pages), and the
+`reference/schemas/` and `reference/configuration/` sections (which replaced the
+planned `reference/file-formats.md`).
+
+## Cutover
+
+Point `website/docs.sync.config.mjs` here, add old-to-new redirects in
+`website/public/_redirects`, and verify `llms.txt` / `llms-full.txt` /
+per-page markdown routes. `docs/` stays in place, untouched. The site just
+stops reading it.

docs-lab/start/installation.md

@@ -0,0 +1,149 @@
+# Installation
+
+> Install the `openspec` CLI on your machine, update it, and uninstall it.
+
+
+## Prerequisites
+
+OpenSpec is a Node.js CLI. You need version 20.19.0 or newer.
+
+In your terminal:
+
+```bash
+node --version
+```
+
+If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from [nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf, volta).
+
+The workflow itself runs inside an AI coding tool: Claude Code, Cursor, or any other tool on the [supported list](../reference/supported-tools.md).
+
+## Install with your AI assistant
+
+Paste this into your AI chat:
+
+```text
+Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.
+```
+
+Or, in your terminal, pipe it into a CLI agent (Claude Code shown):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude
+```
+
+That fetches [install.md at the repo root](https://github.com/Fission-AI/OpenSpec/blob/main/install.md), a prompt written for any agent that can run shell commands (a few IDE integrations can't). Expect your assistant to:
+
+1. Check your Node version, and stop if it's older than 20.19.0.
+2. Skip the install if the CLI is already on your machine. Otherwise, show you the install command and wait for your confirmation before running it.
+3. Verify `openspec` is on your PATH.
+4. Name the folder it thinks you mean, suggest the AI tool you're already talking to, and ask which others you use, then run `openspec init` there (the [project setup](setup.md) step).
+5. Report what init created and the exact spelling to invoke OpenSpec in your tool.
+
+It stops before anything privileged and never edits your shell startup files. The [manual methods below](#install-methods) are the source of truth, and the prompt runs them for you.
+
+This install method is new and can have varying results depending on model used. Only use if you're comfortable correcting AI mistakes. Otherwise we recommend following the standard method below.
+
+## Install methods
+
+Install the CLI globally; [setting up your project](setup.md) comes after.
+
+In your terminal:
+
+```npm
+npm install -g @fission-ai/openspec@latest
+```
+
+### Yarn
+
+`yarn global add` is Yarn Classic (1.x) only. Modern Yarn removed global installs, so use npm, pnpm, or bun instead. A global CLI doesn't have to share your project's package manager.
+
+### Bun
+
+Bun installs OpenSpec but doesn't run it, so you still need Node on your machine (the [prerequisite](#prerequisites) above). Without it, every command fails with `env: node: No such file or directory`. Bun treats [every Node CLI](https://bun.com/docs/pm/bunx#shebangs) this way.
+
+### Deno
+
+Deno installs the CLI from npm and needs explicit permission flags. In your terminal:
+
+```bash
+deno install --global \
+  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
+  npm:@fission-ai/openspec@latest
+```
+
+Some commands launch another program: [`openspec config edit`](../reference/cli.md) opens your editor. Deno interrupts those with a permission prompt on every run. To stop it asking, add a scoped `--allow-run=<program>` to the install command.
+
+> [!NOTE]
+> If Deno can't resolve `@latest`, pin a version range instead: `npm:@fission-ai/openspec@^1.7.0`.
+
+### Nix
+
+The OpenSpec repo ships a Nix flake. Install it into your profile. In your terminal:
+
+```bash
+nix profile install github:Fission-AI/OpenSpec
+```
+
+Or run a one-off command first, without installing:
+
+```bash
+nix run github:Fission-AI/OpenSpec -- --version
+```
+
+That leaves nothing on your PATH, so there's no install to check afterward.
+
+To put OpenSpec in a project dev shell instead, add the flake as an input and use its default package; [flake.nix](https://github.com/Fission-AI/OpenSpec/blob/main/flake.nix) lists the outputs.
+
+### Check it worked
+
+Whichever method you used, in your terminal:
+
+```bash
+openspec --version
+```
+
+If that prints a version number, the CLI is on your PATH. It installs once per machine.
+
+Next, [set up your project](setup.md). If your assistant already ran init, that page shows what it wrote and how to adjust it.
+
+## Updating
+
+In your terminal, in each project where you ran init:
+
+```bash
+openspec update
+```
+
+When a newer CLI is out, [`openspec update`](../reference/cli.md#openspec-update) says so and can install it for you; that upgrade is once per machine. Every run refreshes the project's generated skills and commands, which never update on their own. A current project prints `✓ All 2 tool(s) up to date (v1.7.0)`.
+
+
+> [!WARNING]
+> On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
+
+> [!NOTE]
+> A global npm install belongs to one Node installation. Switch Node versions with nvm and the `openspec` command doesn't come along, so install it again under the new version.
+
+## Uninstalling
+
+To uninstall OpenSpec, run through the steps below; none of them touch your source code. You can also point your agent at this section and let it handle the removal.
+
+**1. Remove [shell completions](../reference/cli.md#openspec-completion)**, if you set them up, while the CLI can still do it. In your terminal:
+
+```bash
+openspec completion uninstall
+```
+
+**2. Remove the package.** In your terminal:
+
+```npm
+npm uninstall -g @fission-ai/openspec
+```
+
+On Deno: `deno uninstall --global openspec`. On Nix: `nix profile remove openspec`. Your shell should no longer find `openspec`.
+
+**3. Delete what's left, or keep it.**
+
+- Generated agent files: `openspec-*` skills and `opsx` commands under directories like `.claude/` or `.agents/`, per project. [Supported tools](../reference/supported-tools.md) lists each tool's paths; MiniMax Code keeps skills in `~/.minimax/skills`.
+- Leftovers from older versions: marker blocks in `CLAUDE.md` or `AGENTS.md` (delete the block, keep the file) and `opsx-*.md` prompts in `~/.codex/prompts`.
+- The `openspec/` folder: pause first. `specs/` and `changes/archive/` are your record of the system, plain Markdown that reads fine without OpenSpec.
+- Per-machine state: settings and the telemetry id in `~/.config/openspec/`; schema overrides and store registrations in `~/.local/share/openspec/` (Windows: `%APPDATA%\openspec`, `%LOCALAPPDATA%\openspec`). Registrations are pointers; the store repos they point to are untouched.

docs-lab/start/overview.md

@@ -0,0 +1,14 @@
+# Overview
+
+TODO: this page is being rewritten from scratch.
+
+<!-- Emptied 2026-08-21. The previous skeleton (section headings, narrative beats, and
+the diagram-options gallery) was cleared so the page starts clean. The old goal line
+("OpenSpec gives you and your coding agent a shared, reviewable plan before code is
+written") was dropped as too weak a pitch: the rewrite should sell keeping larger
+features on track and aligned (teams, git-native artifacts, intended behavior matching
+implemented behavior, the control-loop framing). The brief is in docs-lab/Notes.md
+under "Start > Overview". The diagram candidates (docs-lab/diagrams/) were deleted
+with the gallery; recover them from git history if the rewrite wants a starting point.
+README rules that still bind the rewrite: the loop appears here as pitch only, copy and
+no explanation; the quickstart is its one teacher. -->

docs-lab/start/quickstart.md

@@ -0,0 +1,167 @@
+# Quickstart
+
+> Your first change on your existing repo, from idea to archived.
+
+Before you start, you need the CLI on your machine ([Installation](installation.md)) and OpenSpec initialized in your project ([Set up your project](setup.md)).
+
+## The loop at a glance
+
+Every change moves through the same five steps: you think the idea through with your agent, it drafts a plan, you correct the plan before any code exists, the agent builds from it, and archiving updates your specs with what shipped.
+
+```mermaid
+flowchart LR
+    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
+    propose --> review["3 · Review<br/>you correct the plan"]
+    review --> apply["4 · Apply<br/>agent builds, task by task"]
+    apply --> archive["5 · Archive<br/>specs absorb the change"]
+    archive -. "next change" .-> explore
+```
+
+Every prompt below goes in your AI chat, the same place you ask for code. Each invokes an OpenSpec skill by name, the same spelling in every tool. A plain ask works too ("propose a change to add rate limiting"). Some tools add shorter command aliases (`/opsx:propose` in Claude Code, [other tools vary](../reference/supported-tools.md)).
+
+## Step 1: Explore
+
+Think the idea through with your agent before you ask for a plan. In your AI chat:
+
+```text
+/openspec-explore how rate limiting should work in this app
+```
+
+Explore is a thinking mode. The agent investigates your codebase, asks the questions that matter, sketches options, and challenges assumptions. It writes no code and no files. The output is a sharper idea.
+
+Stay here as long as the problem needs. When the shape feels right, hand it off:
+
+```text
+/openspec-propose
+```
+
+That line starts propose for you, carrying everything you settled. Skip the first prompt in step 2.
+
+## Step 2: Propose
+
+Propose turns the idea into a reviewable plan. Coming from explore, it's already running. Starting cold, when the change is clear in your head, ask directly. In your AI chat:
+
+```text
+/openspec-propose add rate limiting
+```
+
+The agent asks what it needs to, then writes a change folder:
+
+```
+openspec/changes/add-rate-limiting/
+├── proposal.md    why, and what changes
+├── specs/         what "done" means, as testable requirements
+├── design.md      technical decisions (only when the change needs one)
+└── tasks.md       the implementation checklist
+```
+
+No code yet. Propose stops at the plan.
+
+## Step 3: Review and correct the plan
+
+Fix the plan while it's still words and nothing is built yet. Read in this order:
+
+- **`proposal.md`**: is this the right problem, at the right size?
+- **`specs/`**: the highest-value read. Would you accept these requirements as done?
+- **`tasks.md`**: do the tasks cover the specs, and nothing more?
+
+To fix something, either works:
+
+- Edit the file yourself. The artifacts are plain markdown, and the files are the plan.
+- Tell your agent what's wrong ("the spec is missing the unauthenticated case"). It revises the artifacts.
+
+## Step 4: Apply
+
+Apply turns the plan into code. Start a fresh chat session, since implementation goes better on a clean context window. In your AI chat:
+
+```text
+/openspec-apply-change add-rate-limiting
+```
+
+The agent reads the change folder, then works through `tasks.md`, checking off each task as it lands.
+
+- **Interrupted, or out of context?** Open a new session and ask it to apply again. It resumes at the first unchecked task.
+- **Plan turned out wrong?** Fix the artifacts (either way from step 3), then continue applying.
+- **Progress** lives in the `tasks.md` checkboxes. There is no hidden state.
+
+## Step 5: Archive
+
+Archiving does two things: it updates your main specs with the change's requirements, and it moves the change folder into the archive folder (in `/openspec/changes/archive/*`).
+
+When every box in `tasks.md` is checked, in your AI chat:
+
+```text
+/openspec-archive-change add-rate-limiting
+```
+
+Step through what archiving does:
+
+```file-steps
+## The finished change
+> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
+  openspec/
+  ├── specs/                                   (no rate-limiting spec yet)
+  └── changes/
+      └── add-rate-limiting/
+          ├── proposal.md
+          ├── tasks.md                         every box checked
+          └── specs/
+              └── rate-limiting/
+                  └── spec.md                  the delta: ADDED requirements
+
+## Requirements land in specs/
+> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
+  openspec/
+  ├── specs/
++ │   └── rate-limiting/
++ │       └── spec.md                          gains "Requirement: Rate limiting"
+  └── changes/
+      └── add-rate-limiting/
+          └── specs/
+              └── rate-limiting/
+                  └── spec.md                  the delta, source of the merge
+
+## The folder moves to archive/
+> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
+  openspec/
+  ├── specs/
+  │   └── rate-limiting/
+  │       └── spec.md
+  └── changes/
+-     └── add-rate-limiting/
++     └── archive/
++         └── 2026-08-08-add-rate-limiting/
++             ├── proposal.md
++             ├── tasks.md
++             └── specs/rate-limiting/spec.md
+
+## Specs describe the system as built
+> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
+  openspec/
+  ├── specs/
+  │   └── rate-limiting/
+  │       └── spec.md                          the spec as built
+  └── changes/
+      └── archive/
+          └── 2026-08-08-add-rate-limiting/
+```
+
+Git is a separate concern. Commit the change folder with the code, and nothing else about your workflow changes. When to archive relative to a PR is a team convention; the [Teams](../guides/teams.md) guide has the tradeoff.
+
+## Going further
+
+- [Concepts](../guides/concepts.md): what the two artifacts are, and how a delta describes a change.
+- [Explore](../guides/explore.md): getting more out of explore mode.
+- [Apply](../guides/apply.md): pacing, context windows, resuming long changes.
+- [Review the plan](../guides/review-the-plan.md): what to look for in specs before you build.
+- [Profiles](../customize/profiles.md): optional workflows beyond the core set (verify before archive, incremental planning).
+
+## Advanced guides
+
+<!-- Planned pages, not yet written or in the README page map. Listed here so the quickstart routes to them once they exist. -->
+
+Not written yet; guides we plan to add:
+
+- **Prototype first**: spike the code before any spec, then backfill the proposal from what the prototype taught you.
+- **Building iteratively**: a sequence of small changes instead of one big proposal.
+- **Revising an implemented change**: the plan needs to move again after apply, but the change hasn't merged or archived yet.

docs-lab/start/setup.md

@@ -0,0 +1,115 @@
+# Set up your project
+
+> Add OpenSpec to a project: run init, see what it wrote, and adjust it.
+
+## Pick where OpenSpec lives
+
+- **In your repo (the default)**: specs and changes sit next to the code they describe and are versioned with it. The rest of this page follows this path.
+- **In a store**: a separate planning repo shared by the repos that use it, for multi-repo setups or keeping planning out of the repo entirely. [Stores (beta)](../multi-repo/stores.md) covers when that's worth it and how to set one up.
+
+## Initialize your project
+
+With the CLI installed ([Installation](installation.md)), run init at the root of your project. In your terminal:
+
+```bash
+cd <your-project>
+openspec init
+```
+
+Init asks which AI tools you use, writes the workflow files for the ones you pick, and reports what you got:
+
+```
+OpenSpec Setup Complete
+
+Created: Claude Code
+6 skills and 6 commands in .claude/
+Config: openspec/config.yaml (schema: spec-driven)
+```
+
+Restart your IDE for the new commands to take effect.
+
+Re-running init is safe:
+
+- Tools you already set up print `Refreshed` instead of `Created`.
+- Running init again with a new tool selected adds that tool.
+- The `--tools` flag skips the picker ([CLI reference](../reference/cli.md)).
+
+## What init installs
+
+Running init creates two things in your project:
+
+- An `openspec/` folder at the repo root
+- Workflow files (skills and commands) added to your AI tool's folder (`.agents/`, `.claude/`, etc.)
+
+Commit all of it like the rest of your source ([FAQ](../help/faq.md) covers why). Init changes nothing else in your repo (if it finds leftovers from an older OpenSpec version, it asks before cleaning them up).
+
+### The `openspec/` folder
+
+Every OpenSpec artifact lives here, at the root of your project. Here's what that looks like:
+
+```
+openspec/
+├── config.yaml     project settings and context for the AI
+├── specs/          your specs (empty for now)
+└── changes/        in-motion changes (empty for now)
+    └── archive/    completed changes move here
+```
+
+[Concepts](../guides/concepts.md) explains both artifacts; [Project config](../customize/project-config.md) covers `config.yaml`.
+
+### The workflow files (skills and commands)
+
+These are the OpenSpec workflows, the actions you'll use as you work. Here they are as installed skills, in the shared `.agents/` folder most tools use:
+
+```
+.agents/skills/
+├── openspec-explore/              think through an idea first
+├── openspec-propose/              propose a change
+├── openspec-apply-change/         implement a change's tasks
+├── openspec-update-change/        revise a change's plan
+├── openspec-sync-specs/           sync a change's spec updates into specs/
+├── openspec-archive-change/       move a finished change to the archive
+├── openspec-verify-change/        check the implementation matches the plan (not included by default)
+└── openspec-bulk-archive-change/  archive several changes at once (not included by default)
+```
+
+This is the default set plus two optional workflows. [Profiles](../customize/profiles.md) lists all twelve.
+
+By default each workflow installs in two forms:
+
+- **Skill** (`openspec-apply-change`): instructions your agent picks up on its own when you ask for the work.
+- **Command** (`/opsx:apply` in Claude Code): a typed entry point for the same workflow, under a shorter name.
+
+The two are functionally identical. A workflow's skill and its command carry the same instructions.
+
+Why two: commands came first, and every tool spells them its own way. Skills are the newer standard shared across tools, but not every tool can invoke a skill directly, so commands stay as those tools' entry point.
+
+Some tools install in skill form only. Where the tool runs skills directly, init skips commands and says so (`Commands skipped for: codex (uses skills)`).
+
+We prefer skills and expect to retire commands eventually.
+
+#### Change what gets installed
+
+The interactive picker changes the delivery form and the workflow set ([Profiles](../customize/profiles.md)). In your terminal:
+
+```bash
+openspec config profile
+```
+
+Here's switching to skills only:
+
+```
+Current profile settings
+  Delivery: both
+
+? What do you want to configure? Delivery only
+? Delivery mode (how workflows are installed): Skills only
+
+Config changes:
+  delivery: both -> skills
+? Apply changes to this project now? (Y/n) y
+```
+
+Answering yes applies it to the current project on the spot. Other projects pick it up on their next `openspec update`. The setting is global, per machine.
+
+Setup is done. The [Quickstart](quickstart.md) takes your first change from here.

docs/README.md

@@ -76,6 +76,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l
 | [Customization](customization.md) | Project config, custom schemas, shared context |
 | [Multi-Language](multi-language.md) | Generate artifacts in languages other than English |
 | [Supported Tools](supported-tools.md) | The 30+ AI tools OpenSpec integrates with, and where files land |
+| [Community Showcase](community.md) | Projects and resources built with and for OpenSpec |
 
 ### When you need help
 

docs/agent-contract.md

@@ -27,15 +27,16 @@ Diagnostics appear in two positions: **status arrays** (`status: StoreDiagnostic
 
 ## 3. Root selection and `RootOutput`
 
-All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `instructions archive`, `new change`, `archive`, `doctor`, `context`) resolve one OpenSpec root with one precedence:
+All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `instructions archive`, `new change`, `archive`, `doctor`, `context`, `schemas`) resolve one OpenSpec root with one precedence:
 
 1. `--store <id>` → the registered store's root (`source: "store"`).
 2. Otherwise, nearest ancestor with `openspec/`: planning shape → `source: "nearest"` (a `store:` pointer is ignored with a stderr warning); config-only dir with a valid `store:` pointer → that store, `source: "declared"`.
 3. No nearest root + global `defaultStore` set (`openspec config set defaultStore <id>`) → that store, `source: "global_default"`; a stale id fails with the underlying store error and a `fix` naming `openspec config unset defaultStore`.
 4. No nearest root, no default + registered stores exist → error `no_root_with_registered_stores`.
-5. No root, no default, no stores: scaffolding commands treat the cwd as `source: "implicit"`; diagnostic commands (`doctor`, `context`) fail with `no_openspec_root` instead — they inspect, never scaffold.
+5. No root, no default, no stores: commands may treat the cwd as `source: "implicit"`; `doctor`, `context`, `list`, and bulk `validate` instead fail with `no_openspec_root`. `list` preserves the implicit fallback for legacy projects with `openspec/project.md`.
 
-Successful JSON payloads embed the root:
+Successful JSON payloads normally embed the root; successful `schemas --json`
+deliberately remains the compatibility bare array documented in §4.13:
 
 ```json
 "root": { "path": "/abs/path", "source": "store" | "declared" | "global_default" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }
@@ -55,7 +56,9 @@ Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id
 `{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }`. Exit 1 when any item fails.
 
 ### 4.4 `status --json`
-`{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }`. Each artifact's `requires` is its direct dependency ids (present for every status, so the transitive required set is computable even when the artifact is `done`); `missingDeps` appears only when `blocked`. The `artifacts` array is in dependency order, with the schema's `artifacts:` declaration order breaking ties between artifacts that become ready at the same time (never alphabetical), so the first `ready` entry is the artifact to write next; `missingDeps` uses that same order. `"skipped"` marks an artifact whose `generates` path is under `specs/` in a change whose `.openspec.yaml` declares `skip_specs: true`; it satisfies dependencies but must not be created. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
+`{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }`. `isPlanningComplete` means every non-skipped planning artifact exists; skipped artifacts count as satisfied without being created. It does not mean implementation tasks are complete. `isComplete` is retained as a compatibility alias with the same value. Each artifact's `requires` is its direct dependency ids (present for every status, so the transitive required set is computable even when the artifact is `done`); `missingDeps` appears only when `blocked`. The `artifacts` array is in dependency order, with the schema's `artifacts:` declaration order breaking ties between artifacts that become ready at the same time (never alphabetical), so the first `ready` entry is the artifact to write next; `missingDeps` uses that same order. `"skipped"` marks an artifact whose `generates` path is under `specs/` in a change whose `.openspec.yaml` declares `skip_specs: true`; it satisfies dependencies but must not be created. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
+
+`--all` (batch, mutually exclusive with `--change` — combining them is an error with the `{ "changes": [], "root": null, "status": [d] }` null-shape): `{ "changes": [ <per-change status object, no per-change root>, ... ], "root" }`, sorted by change name. A change that fails to load contributes `{ "changeName", "status": [d] }` in place; the sweep continues, preserves the complete envelope, and exits 1 in both text and JSON modes. An invalid `--schema` fails the whole invocation with the null-shape, even when no changes exist.
 
 ### 4.5 `instructions <artifact> --json`
 `{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "skipped"?, "warning"?, "template", "dependencies": [{id,done,path,description,skipped?}], "unlocks", "root" }`. `unlocks` lists the artifacts this one makes ready, in the schema's declaration order (the same order `status` recommends them). `"skipped": true` (with `"warning"`) appears when the change declares `skip_specs: true` and this artifact is skipped — do not create its files. A dependency entry with `skipped: true` is satisfied without files — do not try to read its paths.
@@ -72,7 +75,7 @@ Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id
 Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Failure: `{ "change": null, "status": [d] }`, exit 1.
 
 ### 4.9 `archive <name> --json`
-Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. `specsUpdated` is true only when at least one spec file was written; an already-synced change archives with all-zero totals and the skips listed in `warnings`. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
+Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. `specsUpdated` is true only when at least one spec file was written or retired (a capability whose last requirement the change removed has its spec deleted, which requires `retire_capabilities: true` in the change's `.openspec.yaml`; every retirement is named in `warnings`, with a pasteable Git recovery command only when the spec lived in the caller's checkout); an already-synced change archives with all-zero totals and the skips listed in `warnings`. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
 
 ### 4.10 `doctor --json`
 `{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }`. `drift` (present only for a git-backed store checkout that has an upstream tracking ref) is ahead/behind counts against the last-fetched upstream, not the live remote. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
@@ -84,7 +87,7 @@ Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "spe
 setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }`. unregister/remove: `{ "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }`. list: `{ "stores": [{id, root}], "status": [] }`. doctor: `{ "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] }` (`null` = unknown/not probed). Health findings exit 0; failures exit 1 with the matching null-shape. Prompt cancellation exits 130.
 
 ### 4.13 `schemas --json` / `templates --json`
-`schemas`: bare array `[ {name, description, artifacts, source} ]`. `templates`: keyed object `{ "<artifactId>": {path, source} }`. Both cwd-based, no root/status keys.
+`schemas`: success remains a bare array `[ {name, description, artifacts, source} ]`; it resolves the canonical root-selection precedence and accepts `--store <id>`. Root-selection failure: `{ "schemas": [], "root": null, "status": [d] }`, exit 1. `templates`: keyed object `{ "<artifactId>": {path, source} }`, still cwd-based with no root/status keys.
 
 ## 5. Exit-code contract
 
@@ -119,7 +122,7 @@ setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, regis
 `relationship_registry_unreadable`, `root_pointer_ignored`, `root_pointer_invalid`, `pointer_declarations_inert`.
 
 ### Archive (JSON mode)
-`archive_change_name_required`, `archive_change_not_found`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_error`.
+`archive_change_name_required`, `archive_change_not_found`, `archive_change_symlink`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_error`.
 
 ### Context writes
 `context_file_exists`, `context_output_dir_missing`.
@@ -137,5 +140,5 @@ Recorded by the capstone audit; published-key renames are product decisions defe
 4. Four parallel envelope type declarations exist in src; archive diagnostics never carry `target`.
 5. `list --json` reuses the `status` key as a string enum per change.
 6. Only `validate` output carries a `version` field.
-7. `schemas`/`templates` ignore root selection (cwd-based, no `--store`).
+7. `templates` ignores root selection (cwd-based, no `--store`).
 8. Deprecated noun forms (`change`/`spec` subcommands) emit unenveloped payloads without `root`/`status`.

docs/cli.md

@@ -50,7 +50,7 @@ These commands support `--json` output for programmatic use by AI agents and scr
 | `openspec status` | See artifact progress | `--json` for structured status |
 | `openspec instructions` | Get next steps | `--json` for agent instructions |
 | `openspec templates` | Find template paths | `--json` for path resolution |
-| `openspec schemas` | List available schemas | `--json` for schema discovery |
+| `openspec schemas` | List available schemas | `--json` for schema discovery; `--store <id>` to select a registered root |
 | `openspec store setup <id>` | Create and register a local store | `--json` with explicit inputs for structured setup output |
 | `openspec store register <path>` | Register an existing store | `--json` for structured registration output |
 | `openspec store unregister <id>` | Forget a local store registration | `--json` for structured cleanup output |
@@ -88,6 +88,10 @@ Default behavior uses global config defaults: profile `core`, delivery `both`, w
 openspec init [path] [options]
 ```
 
+Use `--language <language>` to add a language instruction to a new project's
+`openspec/config.yaml`. For an existing project, edit the config's `context`
+field so OpenSpec never overwrites project-specific guidance.
+
 **Arguments:**
 
 | Argument | Required | Description |
@@ -99,15 +103,18 @@ openspec init [path] [options]
 | Option | Description |
 |--------|-------------|
 | `--tools <list>` | Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list |
+| `--language <language>` | Write artifacts in this language when creating a new config |
 | `--force` | Auto-cleanup legacy files without prompting |
 | `--profile <profile>` | Override global profile for this init run (`core` or `custom`) |
 | `--no-animation` | Show a static welcome screen instead of the animated one |
+| `--copilot-cloud` | Set up GitHub Copilot [cloud coding-agent files](supported-tools.md#github-copilot-cloud-coding-agent) without prompting |
+| `--no-copilot-cloud` | Skip GitHub Copilot cloud coding-agent files without prompting |
 
 `--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`).
 
 The welcome animation is also skipped when the `OPENSPEC_NO_ANIMATION` environment variable is set (any value, including empty), when `NO_COLOR` is set to a non-empty value, or when the OS reduced-motion preference is enabled (macOS Reduce Motion, GNOME animations disabled).
 
-**Supported tool IDs (`--tools`)** — `windsurf` is also accepted, as an alias for `devin`: `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codeartsagent`, `codex`, `devin`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `hermes`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `zcode`
+**Supported tool IDs (`--tools`)** — `windsurf` is also accepted, as an alias for `devin`: `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `command-code`, `codeartsagent`, `codex`, `devin`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `hermes`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `minimax-code`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `codeassistant`, `qoder`, `qwen`, `rovodev`, `roocode`, `trae`, `zed`, `zcode`, `agents`
 
 > This list mirrors `AI_TOOLS` in `src/core/config.ts`. See [Supported Tools](supported-tools.md) for each tool's skill and command paths.
 
@@ -123,6 +130,9 @@ openspec init ./my-project
 # Non-interactive: configure for Claude and Cursor
 openspec init --tools claude,cursor
 
+# Non-interactive: configure global MiniMax Code skills
+openspec init --tools minimax-code
+
 # Configure for all supported tools
 openspec init --tools all
 
@@ -144,6 +154,7 @@ openspec/
 .claude/skills/         # Claude Code skills (if claude selected)
 .cursor/skills/         # Cursor skills (if cursor selected)
 .cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
+.agents/skills/         # Shared skills for AGENTS.md-compatible tools (if agents selected)
 ... (other tool configs)
 ```
 
@@ -526,7 +537,7 @@ openspec show add-dark-mode --json
 
 ### `openspec validate`
 
-Validate changes and specs for structural issues.
+Validate changes and specs for structural issues, and check a change's MODIFIED requirements against the main specs they would replace.
 
 ```
 openspec validate [item-name] [options]
@@ -547,12 +558,15 @@ A change with zero spec deltas fails validation unless its `.openspec.yaml` decl
 | `--all` | Validate all changes and specs |
 | `--changes` | Validate all changes |
 | `--specs` | Validate all specs |
+| `--archived` | Validate that archived changes have all tasks completed (for pre-commit linting) |
 | `--type <type>` | Specify type when name is ambiguous: `change` or `spec` |
 | `--strict` | Enable strict validation mode |
 | `--json` | Output as JSON |
 | `--concurrency <n>` | Max parallel validations (default: 6, or `OPENSPEC_CONCURRENCY` env) |
 | `--no-interactive` | Disable prompts |
 
+`--archived` is its own scope: it does not validate spec deltas (already applied at archive time), it verifies that every change under `changes/archive/` has all of its `tasks.md` checkboxes ticked, exiting non-zero if any are unchecked. This catches changes that were archived with unfinished work — handy in a pre-commit hook.
+
 **Examples:**
 
 ```bash
@@ -570,6 +584,9 @@ openspec validate --all --json
 
 # Strict validation with increased parallelism
 openspec validate --all --strict --concurrency 12
+
+# Fail if any archived change still has unchecked tasks
+openspec validate --archived
 ```
 
 **Output (text):**
@@ -621,38 +638,65 @@ openspec archive [change-name] [options]
 
 | Argument | Required | Description |
 |----------|----------|-------------|
-| `change-name` | No | Change to archive (prompts if omitted) |
+| `change-name` | No | Change to archive (prompts if omitted; required when nothing can answer the prompt) |
 
 **Options:**
 
 | Option | Description |
 |--------|-------------|
-| `-y, --yes` | Skip confirmation prompts |
+| `-y, --yes` | Skip confirmation prompts. Required when nothing can answer them — an AI agent, a CI job, or any run with stdin closed |
 | `--skip-specs` | Skip spec updates for one archive run. A change that permanently has no spec deltas should declare `skip_specs: true` in its `.openspec.yaml` instead — it archives with no flag |
-| `--no-validate` | Skip validation (requires confirmation) |
+| `--no-validate` | Skip validation (requires confirmation). Also disables capability retirement — with no validator verdict, nothing is retired |
 
 **Examples:**
 
 ```bash
-# Interactive archive
+# Interactive archive (asks which change, then confirms)
 openspec archive
 
 # Archive specific change
 openspec archive add-dark-mode
 
-# Archive without prompts (CI/scripts)
+# Archive without prompts (agents, CI, scripts)
 openspec archive add-dark-mode --yes
 
 # Archive a tooling change that doesn't affect specs
 openspec archive update-ci-config --skip-specs
 ```
 
+**Retire a capability:** Add the retirement marker to the change metadata:
+
+```yaml
+# openspec/changes/retire-legacy/.openspec.yaml
+schema: spec-driven
+retire_capabilities: true
+```
+
+Then archive the change normally:
+
+```bash
+openspec archive retire-legacy --yes
+```
+
+When the change removes the capability's last requirement, OpenSpec deletes its
+live `spec.md`. Other capability deltas in the same change still update their
+main specs. Without the marker, archive stops before changing any files and
+tells you to add it.
+
 **What it does:**
 
 1. Validates the change (unless `--no-validate`)
 2. Prompts for confirmation (unless `--yes`)
-3. Merges delta specs into `openspec/specs/`
-4. Moves change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+3. Claims the archive destination before changing any main spec
+4. Validates and merges the active delta specs into `openspec/specs/` — a capability whose last requirement the change removes is retired, and its spec file deleted, but only when the change's `.openspec.yaml` declares `retire_capabilities: true` next to its `schema:`
+5. Moves the change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+6. If a spec mutation or final move fails before a complete archive is secured, restores the specs and leaves or returns the change at its active path
+7. If a verified fallback copy completes but staged-source cleanup fails, retains the complete archive and committed spec state for recovery
+
+**Without a terminal:** an AI agent, a CI job, or any run with stdin closed cannot
+answer step 2, so archive stops before touching anything, exits 1, and names the
+command to rerun — `openspec archive <name> --yes`, carrying whatever other flags
+you passed. Pass `--yes` (and the change name) up front to skip the round trip.
 
 ---
 
@@ -741,6 +785,7 @@ A change that declares `skip_specs: true` shows its specs stage as `[~] specs (s
 {
   "changeName": "add-dark-mode",
   "schemaName": "spec-driven",
+  "isPlanningComplete": false,
   "isComplete": false,
   "applyRequires": ["tasks"],
   "artifacts": [
@@ -752,6 +797,11 @@ A change that declares `skip_specs: true` shows its specs stage as `[~] specs (s
 }
 ```
 
+`isPlanningComplete` reports whether every non-skipped planning artifact exists;
+skipped artifacts count as satisfied without being created. It does not report
+whether implementation tasks are complete. `isComplete` is retained as a
+compatibility alias with the same value.
+
 Artifacts are listed in dependency order - a dependency never appears after
 something that requires it - and artifacts that become ready at the same time
 (spec-driven's `specs` and `design` both need only `proposal`) keep the order the
@@ -884,6 +934,7 @@ openspec schemas [options]
 | Option | Description |
 |--------|-------------|
 | `--json` | Output as JSON |
+| `--store <id>` | Use a registered store as the OpenSpec root |
 
 **Example:**
 
@@ -1105,7 +1156,7 @@ openspec config list
 # Get a specific value
 openspec config get telemetry.enabled
 
-# Set a value
+# Set a value (disable anonymous usage telemetry)
 openspec config set telemetry.enabled false
 
 # Set a string value explicitly
@@ -1131,6 +1182,11 @@ openspec config profile
 openspec config profile core
 ```
 
+**Telemetry opt-out:** `telemetry.enabled` defaults to on when unset (opt-out model).
+Set it to `false` to disable anonymous usage stats and the `openspec update` version check.
+Environment variables take precedence over config: `OPENSPEC_TELEMETRY=0`, `DO_NOT_TRACK=1`,
+and a truthy `CI` value (e.g. `true`/`1`/`yes`) always disable telemetry regardless of the config value.
+
 `openspec config profile` starts with a current-state summary, then lets you choose:
 - Change delivery + workflows
 - Change delivery only
@@ -1172,13 +1228,13 @@ openspec feedback <message> [options]
 
 | Argument | Required | Description |
 |----------|----------|-------------|
-| `message` | Yes | Feedback message |
+| `message` | Yes | Feedback summary; long text is shortened in the issue title and preserved in the body |
 
 **Options:**
 
 | Option | Description |
 |--------|-------------|
-| `--body <text>` | Detailed description |
+| `--body <text>` | Additional details included after the summary |
 
 **Requirements:** GitHub CLI (`gh`) must be installed and authenticated.
 
@@ -1218,13 +1274,39 @@ openspec completion install
 # Install for specific shell
 openspec completion install zsh
 
-# Generate script for manual installation
+# Generate script for manual installation (bash)
 openspec completion generate bash > ~/.bash_completion.d/openspec
 
 # Uninstall
 openspec completion uninstall
 ```
 
+**Windows (PowerShell):** Install completions for the current PowerShell host:
+
+```powershell
+$env:PROFILE = $PROFILE
+openspec completion install powershell
+. $PROFILE
+```
+
+`$env:PROFILE` tells OpenSpec which profile to configure in this session. The
+installer creates missing profile directories and adds a managed block that loads
+`OpenSpecCompletion.ps1`. Reloading the profile enables completions immediately.
+
+To uninstall from the current host, run:
+
+```powershell
+$env:PROFILE = $PROFILE
+openspec completion uninstall powershell
+```
+
+Restart PowerShell after uninstalling to clear completions from the current session.
+
+Completions are opt-in. The CLI mentions them once, on stderr, the first time you
+run a command in an interactive terminal, and never again — it also stays quiet
+if you already have completions installed. Set `OPENSPEC_NO_COMPLETIONS=1` to
+suppress that tip entirely.
+
 ---
 
 ## Exit Codes
@@ -1240,12 +1322,13 @@ openspec completion uninstall
 
 | Variable | Description |
 |----------|-------------|
-| `OPENSPEC_TELEMETRY` | Set to `0` to disable telemetry and the `openspec update` version check |
-| `DO_NOT_TRACK` | Set to `1` to disable telemetry and the `openspec update` version check (standard DNT signal) |
+| `OPENSPEC_TELEMETRY` | Set to `0` to disable telemetry and the `openspec update` version check (overrides `telemetry.enabled` in global config) |
+| `DO_NOT_TRACK` | Set to `1` to disable telemetry and the `openspec update` version check (standard DNT signal; overrides config) |
 | `OPENSPEC_CONCURRENCY` | Default concurrency for bulk validation (default: 6) |
 | `EDITOR` or `VISUAL` | Editor for `openspec config edit` |
 | `NO_COLOR` | Disable color output when set |
 | `OPENSPEC_NO_ANIMATION` | Disable the `openspec init` welcome animation when set |
+| `OPENSPEC_NO_COMPLETIONS` | Set to `1` to suppress the one-time tip about shell completions |
 | `OPENSPEC_NO_UPDATE_CHECK` | Disable the `openspec update` check for a newer published CLI when set (any value, including empty). Also skipped when `CI` is set (unless `false`/`0`/`no`/`off`) or `NODE_ENV=test` |
 | `npm_config_registry` | Registry the `openspec update` version check asks. Must be an `http(s)` URL or it falls back to `https://registry.npmjs.org`. No `.npmrc` file is read |
 

docs/commands.md

@@ -673,7 +673,7 @@ Different AI tools use slightly different command syntax. Use the format that ma
 |--------------------------|----------------|---------------|
 | `.../commands/opsx/<id>.*` | `/opsx:propose`, `/opsx:apply` | Claude Code, Gemini CLI, Crush |
 | `.../opsx-<id>.*` | `/opsx-propose`, `/opsx-apply` | Cursor, Devin Desktop, Copilot (IDE), Trae, Oh My Pi |
-| none — skills only | `/openspec-propose`, `/openspec-apply-change` | CodeArts, ForgeCode, Hermes, Mistral Vibe |
+| none — skills only | `/openspec-propose`, `/openspec-apply-change` | CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, shared `.agents` |
 | none — Kimi Code | `/skill:openspec-propose` | Kimi Code |
 | none — Codex CLI | `$openspec-propose` | Codex |
 

docs/community.md

@@ -0,0 +1,19 @@
+# Community Showcase
+
+A community-owned awesome list of projects and resources built with and for OpenSpec. Tools, integrations, workflows, and learning resources are welcome. Community members grow and maintain this showcase through pull requests.
+
+Listed projects are maintained independently. Inclusion does not imply official support or endorsement by OpenSpec. See each project's documentation and issue tracker for setup and support.
+
+## Projects and resources
+
+- **[OpenSpec UI](https://github.com/VeryComplexAndLongName/OpenSpec-UI)**: A standalone web dashboard and VS Code extension for browsing OpenSpec changes, archives, specs, and tasks.
+
+## Add your project
+
+Open a pull request adding one line to this file with your project's name, a direct link, and a short description of how it relates to OpenSpec.
+
+- Keep entries focused on something built with OpenSpec or supporting its use, rather than general product advertising.
+- Describe what people can use. Avoid promotional claims, referral links, and tracking links.
+- Disclose paid features or required accounts in the entry, if any.
+
+Corrections and updates to existing entries are welcome too.

docs/concepts.md

@@ -190,7 +190,7 @@ openspec/changes/add-dark-mode/
 ├── proposal.md           # Why and what
 ├── design.md             # How (technical approach)
 ├── tasks.md              # Implementation checklist
-├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs
+├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs, retire_capabilities
 └── specs/                # Delta specs
     └── ui/
         └── spec.md       # What's changing in ui/spec.md
@@ -392,7 +392,7 @@ The system MUST expire sessions after 15 minutes of inactivity.
 |---------|---------|------------------------|
 | `## ADDED Requirements` | New behavior | Appended to main spec |
 | `## MODIFIED Requirements` | Changed behavior | Replaces existing requirement |
-| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec |
+| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec; removing the last requirement retires the capability and deletes its spec file, when the change declares `retire_capabilities: true` |
 | `## Purpose` | What a brand-new capability is for | Seeds the Purpose of the main spec being created; ignored when the spec already exists |
 
 ### Why Deltas Instead of Full Specs

docs/customization.md

@@ -18,6 +18,7 @@ The `openspec/config.yaml` file is the easiest way to customize OpenSpec for you
 - **Inject project context** - AI sees your tech stack, conventions, etc.
 - **Add per-artifact rules** - Custom rules for specific artifacts
 - **Add per-operation guidance** - Advisory preferences for apply and archive work
+- **Remember integration choices** - e.g. the [GitHub Copilot cloud coding agent](supported-tools.md#github-copilot-cloud-coding-agent) opt-in
 
 ### Quick Setup
 
@@ -52,6 +53,11 @@ operations:
   archive:
     guidance:
       - Keep the completion summary concise
+
+# Set by `openspec init` when you choose (or decline) the GitHub Copilot
+# cloud coding agent; controls whether `init`/`update` generate its files.
+githubCopilot:
+  cloudAgent: false
 ```
 
 ### How It Works
@@ -412,6 +418,7 @@ Community schemas are not vendored into OpenSpec core — they live in their own
 
 | Schema | Maintainer | Repository | Description |
 |--------|-----------|-----------|-------------|
+| `intent-driven` | @harikrishnan83 | [intent-driven-dev/openspec-schemas](https://github.com/intent-driven-dev/openspec-schemas/tree/main/openspec/schemas/intent-driven) | Captures change intent, observable behaviour, technical design, and durable architectural decisions before implementation. Adds a change-local ADR review manifest and writes qualifying long-lived decisions as immutable, supersedable ADRs. |
 | `superpowers-bridge` | @JiangWay | [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) | Integrates OpenSpec's artifact governance with [obra/superpowers](https://github.com/obra/superpowers) execution skills (brainstorming, writing-plans, TDD via subagents, code review, finishing). Adds an evidence-first `retrospective` artifact filling a gap Superpowers does not natively cover. |
 | `nanopm` | @nmrtn | [nmrtn/nanopm](https://github.com/nmrtn/nanopm/tree/main/openspec-schema) | PM-first workflow. Runs [nanopm](https://github.com/nmrtn/nanopm)'s planning pipeline (audit → strategy → roadmap → PRD) upstream of implementation. Bridges product planning to OpenSpec's spec-driven engineering workflow. Artifacts read from `.nanopm/` if present — proposal sources the audit, design sources the strategy, and tasks source the PRD breakdown. |
 | `e2e-runbooks` | @Lukk17 | [Lukk17/openspec-schemas](https://github.com/Lukk17/openspec-schemas/tree/master/openspec/schemas/e2e-runbooks) | Capability-level end-to-end test runbooks. Each capability gets an immutable spec, an immutable tasks-template, and one timestamped run record per execution. Assertions are observable behaviour only (HTTP status, response body, persisted state — never log substrings); each run records start/end UTC, duration, and best-estimate LLM token consumption. |

docs/faq.md

@@ -108,7 +108,7 @@ A spec that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMO
 
 ### Where do archived changes go?
 
-To `openspec/changes/archive/YYYY-MM-DD-<name>/`, with all artifacts preserved. Nothing is deleted; the change just moves out of your active list.
+To `openspec/changes/archive/YYYY-MM-DD-<name>/`, with all change artifacts preserved. The change moves out of your active list. A change that explicitly declares `retire_capabilities: true` can also delete a main capability spec when it removes that capability's final requirement.
 
 ## Configuration and customization
 

docs/how-commands-work.md

@@ -78,7 +78,7 @@ The intent is identical everywhere. The spelling follows the file your tool load
 | `.../commands/opsx/<id>.*` | `/opsx:propose` | Claude Code, Gemini CLI, Crush |
 | `.../opsx-<id>.*` | `/opsx-propose` | Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi |
 | `.amazonq/prompts/opsx-<id>.md` | `@opsx-propose` | Amazon Q Developer |
-| none — skills only | `/openspec-propose` | CodeArts, ForgeCode, Hermes, Mistral Vibe |
+| none — skills only | `/openspec-propose` | CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, shared `.agents` |
 | none — Kimi Code | `/skill:openspec-propose` | Kimi Code |
 | none — Codex CLI | `$openspec-propose` | Codex |
 
@@ -104,7 +104,7 @@ works too, for the tools that surface slash commands at all.
 When you run `openspec init` (or `openspec update`), OpenSpec writes small files into your project so your AI tool can find the workflow. Depending on your tool and settings, these are **skills**, **commands**, or both.
 
 - **Skills** live in places like `.claude/skills/openspec-*/SKILL.md`. They're the emerging cross-tool standard: a folder of instructions your assistant auto-detects.
-- **Commands** live in places like `.cursor/commands/opsx-<id>.md` or `.claude/commands/opsx/<id>.md` — the layout is the tool's, and it decides how you type the command. They're the older per-tool slash command files. Codex does not get generated command files; use `.codex/skills/openspec-*`.
+- **Commands** live in places like `.cursor/commands/opsx-<id>.md` or `.claude/commands/opsx/<id>.md` — the layout is the tool's, and it decides how you type the command. They're the older per-tool slash command files. Codex does not get generated command files; use `.agents/skills/openspec-*`.
 
 You don't have to care which one your tool uses. You just type the slash command and it works. But knowing these files exist helps when something goes wrong: if your commands vanish, it usually means these files are missing or stale, and `openspec update` regenerates them.
 
@@ -114,7 +114,7 @@ See [Supported Tools](supported-tools.md) for the exact paths per tool, and [Mig
 
 Quick checks, fastest first:
 
-1. **Type a slash in your AI chat.** Start typing `/opsx` and watch for autocomplete suggestions. If they appear, you're set. On a skills-only tool (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe) `/opsx` never completes even on a healthy install — try the skill name from the table above instead.
+1. **Type a slash in your AI chat.** Start typing `/opsx` and watch for autocomplete suggestions. If they appear, you're set. On a skills-only tool (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, or the shared `.agents` target) `/opsx` never completes even on a healthy install — try the skill name from the table above instead.
 2. **Look for the files.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories ([Supported Tools](supported-tools.md) lists them).
 3. **Re-run setup.** From your project root, run `openspec update`. This regenerates the skill and command files for whatever tools you configured.
 4. **Restart your assistant.** Many tools scan for skills and commands at startup, so a fresh window can be the missing step.

docs/installation.md

@@ -98,6 +98,23 @@ yarn global add @fission-ai/openspec@latest
 
 Yarn 2 and later (Berry) removed the `global` command. On those versions, install OpenSpec with npm, pnpm, or bun instead — a global CLI doesn't need to share your project's package manager.
 
+### deno
+
+Deno sometimes has issues parsing the @latest tag, but we can specify a version while installing initially.
+If that happens, you could try to change the @latest tag with the version, something like `@^1.3.1`
+
+```bash
+deno install --global \
+  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
+  npm:@fission-ai/openspec@latest
+# or
+deno install --global \
+  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
+  npm:@fission-ai/openspec@^1.3.1
+```
+
+Note: If your subcommands launch external tools, like config edit, feedback, or workspace open, you may need a scoped --allow-run=<program>.
+
 ### bun
 
 Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.

docs/migration-guide.md

@@ -47,7 +47,7 @@ Only OpenSpec-managed files that are being replaced:
 - Cline: `.clinerules/workflows/openspec-*.md`
 - Roo: `.roo/commands/openspec-*.md`
 - GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
-- Codex: OpenSpec now uses `.codex/skills/openspec-*`; legacy cleanup only targets OpenSpec's allowlisted prompt filenames in `$CODEX_HOME/prompts` or `~/.codex/prompts`, and only removes them after replacement skills exist.
+- Codex: OpenSpec now uses the canonical `.agents/skills/openspec-*` path. OpenSpec-managed `SKILL.md` files under the former `.codex/skills` path are reconciled only after replacements exist; custom files and divergent copies stay in place. If an unmarked `.agents` tree already contains OpenSpec skills, OpenSpec preserves its existing Codex (`$openspec-*`) or generic (`/openspec-*`) rendering instead of guessing from the legacy directory. Select `codex` explicitly with `openspec init` to switch ownership. Legacy prompt cleanup still targets only OpenSpec's allowlisted filenames in `$CODEX_HOME/prompts` or `~/.codex/prompts`.
 - And others (Augment, Continue, Amazon Q, etc.)
 
 The migration detects whichever tools you have configured and cleans up their legacy files.
@@ -157,7 +157,7 @@ openspec init --force --tools claude
 
 The `--force` flag skips prompts and auto-accepts cleanup.
 
-This includes cleanup of OpenSpec-managed Codex prompt files in the global Codex prompt directory. Cleanup only targets OpenSpec's allowlisted legacy Codex prompt filenames, removes them only after replacement `.codex/skills/openspec-*` skills exist, and preserves all other files.
+This includes cleanup of OpenSpec-managed Codex prompt files in the global Codex prompt directory. Cleanup only targets OpenSpec's allowlisted legacy Codex prompt filenames, removes them only after replacement `.agents/skills/openspec-*` skills exist, and preserves all other files.
 
 ---
 
@@ -411,7 +411,7 @@ OPSX uses the emerging **skills** standard:
 
 Skills are recognized across multiple AI coding tools and provide richer metadata.
 
-Codex is skills-only in OPSX. OpenSpec no longer generates Codex custom prompt files; use the generated `.codex/skills/openspec-*` directories instead.
+Codex is skills-only in OPSX. OpenSpec no longer generates Codex custom prompt files; use the generated `.agents/skills/openspec-*` directories instead.
 
 ---
 

docs/multi-language.md

@@ -4,6 +4,18 @@ Configure OpenSpec to generate artifacts in languages other than English.
 
 ## Quick Setup
 
+For a new project, set the language during initialization:
+
+```bash
+openspec init --language "Portuguese (pt-BR)"
+```
+
+This writes the language instruction to `openspec/config.yaml`. If the project
+already has a config, edit its `context` field directly so existing project
+guidance is preserved.
+
+You can also configure the same behavior manually:
+
 Add a language instruction to your `openspec/config.yaml`:
 
 ```yaml
@@ -12,6 +24,7 @@ schema: spec-driven
 context: |
   Language: Portuguese (pt-BR)
   All artifacts must be written in Brazilian Portuguese.
+  Keep OpenSpec structural headings and SHALL/MUST keywords in English.
 
   # Your other project context below...
   Tech stack: TypeScript, React, Node.js
@@ -19,6 +32,10 @@ context: |
 
 That's it. All generated artifacts will now be in Portuguese.
 
+OpenSpec's document structure and normative `SHALL`/`MUST` keywords remain in
+English because validation relies on them. The surrounding requirement and
+scenario prose can use your selected language.
+
 ## Language Examples
 
 ### Portuguese (Brazil)

docs/opsx.md

@@ -165,7 +165,7 @@ rules:
 | `/opsx:apply` | Implement tasks, updating artifacts as needed |
 | `/opsx:update` | Revise a change's planning artifacts and keep them coherent |
 | `/opsx:verify` | Validate implementation against artifacts (expanded workflow) |
-| `/opsx:sync` | Sync delta specs to main (default workflow, optional) |
+| `/opsx:sync` | Merge delta specs into main specs (optional) |
 | `/opsx:archive` | Archive when done |
 | `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) |
 | `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) |
@@ -215,6 +215,12 @@ Works through tasks, checking them off as you go. If you're juggling multiple ch
 ```
 Revises the change's existing planning artifacts and keeps them coherent - in any direction (a design edit may ripple back to the proposal). Planning artifacts only: it never edits code, and it never creates missing artifacts (that's `/opsx:continue`). Every edit is confirmed with you first. If the change was already implemented, it recommends `/opsx:apply` so the code catches up with the revised plan. If your revision changes the change's *intent*, start fresh instead - see [When to Update vs. Start Fresh](#when-to-update-vs-start-fresh).
 
+### Sync delta specs
+```text
+/opsx:sync
+```
+Merges the current change's delta specs into your main `openspec/specs/` without archiving — the change stays active. It applies the whole delta: a requirement under `## REMOVED` is deleted from the main spec and a renamed one is retitled in place, while content the delta doesn't mention is left untouched. Syncing is optional — archive prompts you to sync first if you haven't. Reach for it when you want main specs updated before archiving, when a parallel change needs to build on specs this one just added, or when you want to review the merged main spec before archiving.
+
 ### Finish up
 ```
 /opsx:archive   # Move to archive when done (prompts to sync specs if needed)
@@ -478,7 +484,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
   │  • Create proposal.md                   │
   │  • Create tasks.md                      │
   │  • Create design.md                     │
-  │  • Create specs/<capability>/spec.md    │
+  │  • Create delta spec files              │
   │                                         │
   │  No awareness of what exists or         │
   │  dependencies between artifacts         │

docs/stores-beta/user-guide.md

@@ -165,6 +165,98 @@ machine-wide default from a repo's own pointer. Clear it with
 `openspec config unset defaultStore`. If the id is not registered, commands
 error and tell you to register it or clear the stale default.
 
+## Example: one feature, two component repos
+
+Suppose `add-checkout-promo` changes both `checkout-api` and
+`checkout-web`. The team wants one shared product contract, while each code
+repo still needs its own implementation tasks, branch, and review.
+
+Use two layers:
+
+1. Keep the shared behavior in `team-plans`.
+2. Keep implementation plans in each component repo and reference the store
+   as read-only upstream context.
+
+First, plan the shared contract in the store:
+
+```bash
+openspec new change add-checkout-promo --store team-plans
+openspec status --change add-checkout-promo --store team-plans
+```
+
+The proposal and specs should describe the behavior at the boundary between
+the components — for example, the promotion fields returned by the service
+and how the frontend handles an ineligible checkout. Review this change in
+the store repo like any other branch and pull request.
+
+### What context does planning see?
+
+Selecting a store changes the OpenSpec root; it does not discover or read
+every code repo that uses that store. Store instructions see the artifacts
+and configured context in the store. They see component code only when those
+folders are also available to the agent or editor and the agent reads them.
+
+A workset is a convenient way to open the planning store and both code repos
+together:
+
+```bash
+openspec workset create checkout-promo \
+  --member ~/openspec/team-plans \
+  --member ~/src/checkout-api \
+  --member ~/src/checkout-web \
+  --tool code
+openspec workset open checkout-promo
+```
+
+This makes the folders visible in one IDE workspace. It does not copy source
+context into the store, select affected repos, or grant an agent permission
+to edit them. Put durable cross-component facts in the shared specs; do not
+rely on a planner remembering source it happened to inspect.
+
+### How does implementation start in each repo?
+
+When no explicit `--store` or nearer `openspec/` root applies, a
+`store: team-plans` pointer routes commands to that store. It does not split
+one store task list by the directory from which `apply` was invoked. OpenSpec
+currently does not route tasks to repos.
+
+When each component needs an independently scoped apply/review cycle, give it
+a local OpenSpec root and reference the central store instead of pointing at
+it:
+
+```yaml
+# checkout-api/openspec/config.yaml (and likewise in checkout-web)
+schema: spec-driven
+references:
+  - team-plans
+```
+
+After the shared contract is approved and available in the store's main
+specs, create a small local change for the component's part:
+
+```bash
+cd ~/src/checkout-api
+openspec new change implement-checkout-promo-api
+
+cd ~/src/checkout-web
+openspec new change implement-checkout-promo-ui
+```
+
+The reference index in each repo's instructions supplies the store spec's
+summary and exact `openspec show ... --store team-plans` fetch command. Each
+local proposal cites that shared contract, and its tasks describe only work
+in that component. Then run `/opsx:apply` in each repo separately; root
+resolution keeps the artifacts and implementation edits scoped to that repo.
+The service and frontend changes can now be tested, reviewed, merged, and
+archived independently.
+
+If implementation must begin while the shared store change is still active,
+fetch it explicitly with
+`openspec show add-checkout-promo --store team-plans`; reference indexes list
+canonical store specs, not active store changes. Keep the store branch and
+component branches linked in their pull-request descriptions so reviewers
+can see which version of the contract each implementation follows.
+
 ## Story: requirements that cross team lines
 
 A platform team owns the requirements. Product teams build against them,
@@ -335,9 +427,11 @@ tells you which case you're in.
   `openspec/config.yaml` declares `store: <id>` is treated as externalized
   planning, not as a store checkout to register. Remove the `store:` line first
   if you intentionally want to convert that repo into a local store root.
-- **Some commands stay where they are.** `view`, `templates`, `schemas`,
-  and the deprecated noun forms (`openspec change show`, ...) act on the
-  current directory only — no `--store`.
+- **Some commands stay where they are.** `templates` and the
+  deprecated noun forms (`openspec change show`, ...) act on the current
+  directory only — no `--store`. `schemas` follows the canonical root-selection
+  precedence and accepts `--store <id>` while keeping its successful JSON array
+  shape unchanged.
 - **Per-machine state is per-machine.** The store registry and worksets
   are local settings. Nothing about your machine's layout is
   ever committed to shared planning.

docs/supported-tools.md

@@ -9,7 +9,7 @@ For each selected tool, OpenSpec can install:
 1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md`
 2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files
 
-Codex is skills-only: OpenSpec installs `.codex/skills/openspec-*/SKILL.md` for Codex even when delivery is set to `commands`, and it does not generate Codex custom prompt files.
+Codex is skills-only: OpenSpec installs `.agents/skills/openspec-*/SKILL.md` for Codex even when delivery is set to `commands`, and it does not generate Codex custom prompt files. Existing OpenSpec-managed skills under the legacy `.codex/skills` path are reconciled after their replacements are written; custom and divergent files are preserved.
 
 By default, OpenSpec uses the `core` profile, which includes:
 - `propose`
@@ -33,7 +33,7 @@ way it loads the file OpenSpec wrote. Find your tool's command path in the
 | `.../opsx-<id>.*` — the filename is the command | `/opsx-<id>` | Every other tool with generated command files, except Amazon Q and Devin |
 | `.devin/workflows/opsx-<id>.md` — read by only one of Devin's two agents | `/opsx-<id>` on Devin Desktop, `/openspec-<skill>` on Devin Local | Devin Desktop\*\*\*\* |
 | `.amazonq/prompts/opsx-<id>.md` — a prompt, not a command | `@opsx-<id>` | Amazon Q Developer |
-| none — skills only | `/openspec-<skill>` | CodeArts, ForgeCode, Hermes, Mistral Vibe |
+| none — skills only | `/openspec-<skill>` | CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, shared `.agents` |
 | none — Kimi Code | `/skill:openspec-<skill>` | Kimi Code |
 | none — Codex CLI | `$openspec-<skill>` | Codex ([`/openspec-<skill>` is not recognized](https://github.com/openai/codex/issues/11817)) |
 
@@ -70,9 +70,10 @@ to read the hint.
 | IBM Bob Shell (`bob`) | `.bob/skills/openspec-*/SKILL.md` | `.bob/commands/opsx-<id>.md` |
 | Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
 | Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
+| Command Code (`command-code`) | `.commandcode/skills/openspec-*/SKILL.md` | `.commandcode/commands/opsx-<id>.md` |
 | CodeArts (`codeartsagent`) | `.codeartsdoer/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
-| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | Not generated (skills-only; use `.codex/skills/openspec-*`) |
+| Codex (`codex`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (skills-only; use `$openspec-*`) |
 | Devin Desktop, formerly Windsurf (`devin`) | `.devin/skills/openspec-*/SKILL.md` | `.devin/workflows/opsx-<id>.md`\*\*\*\* |
 | ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
@@ -89,22 +90,117 @@ to read the hint.
 | Kimi Code (`kimi`) | `.kimi-code/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
 | Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
 | Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
+| MiniMax Code (`minimax-code`) | `~/.minimax/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use MiniMax Code skills) |
 | Mistral Vibe (`vibe`) | `.vibe/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | Oh My Pi (`oh-my-pi`) | `.omp/skills/openspec-*/SKILL.md` | `.omp/commands/opsx-<id>.md` |
 | OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/commands/opsx-<id>.md` |
 | Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-<id>.md` |
+| SourceCraft Code Assistant for VS Code (`codeassistant`) | `.codeassistant/skills/openspec-*/SKILL.md` | `.codeassistant/commands/opsx-<id>.md` |
 | Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/<id>.md` |
 | Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-<id>.md` |
+| [Rovo Dev CLI](https://support.atlassian.com/rovo/docs/use-rovo-dev-cli/) (`rovodev`) | `.rovodev/skills/openspec-*/SKILL.md` | Not generated. Rovo has no slash-command surface — it matches skills automatically or by prompt (e.g. "use the openspec-propose skill"); `/skills` only manages them. Generated content references skills by name, never as `/openspec-*` commands. |
 | [Zoo Code](https://github.com/Zoo-Code-Org/Zoo-Code) (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
 | Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | `.trae/commands/opsx-<id>.md` |
+| [Zed Agent](https://zed.dev/docs/ai/skills) (`zed`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (skills-only; use `/openspec-*` or `@openspec-*`) |
 | ZCode (`zcode`) | `.zcode/skills/openspec-*/SKILL.md` | `.zcode/commands/opsx/<id>.md` |
+| Shared `.agents` skills (`agents`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 
-\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.
+\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly. Selecting `github-copilot` can also set up the GitHub-hosted **cloud coding agent** — see [GitHub Copilot cloud coding agent](#github-copilot-cloud-coding-agent) below.
 
 \*\*\* Hermes loads skills from `~/.hermes/skills/` by default. To use project-local OpenSpec skills, add the project `.hermes/skills/` directory to `skills.external_dirs` in `~/.hermes/config.yaml`; Hermes then exposes skills with user-facing slash invocations such as `/openspec-propose`.
 
 \*\*\*\* Windsurf was [rebranded to Devin Desktop](https://docs.devin.ai/desktop/devin-desktop-faq) on June 2, 2026, and its config directory moved: `.devin/` is the preferred read + write location, `.windsurf/` a legacy read-only fallback. OpenSpec follows the rename — the tool id is `devin`, and `--tools windsurf` still resolves to it so existing setup scripts keep working. A project still holding OpenSpec files in `.windsurf/` is offered the move on the next `openspec update`; declining leaves them in place, and files you wrote yourself are never touched. Workflows are invoked by filename, so `.devin/workflows/opsx-apply.md` is `/opsx-apply`. The [Devin Local agent does not support workflows](https://docs.devin.ai/desktop/devin-local) — only skills, and it does not read `.windsurf/` at all — so whenever OpenSpec writes Devin skills it keeps their bodies, and the getting-started hint, on `/openspec-*` skill invocations, which work on both agents. Under commands-only delivery no skills are written and both fall back to `/opsx-*`.
 
+SourceCraft Code Assistant support targets its VS Code extension. Its [custom commands](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands) and [skills](https://sourcecraft.dev/portal/docs/ru/code-assistant/operations/agent/skills) are available only in VS Code. This integration does not configure SourceCraft web or JetBrains.
+
+With skills-only delivery, ask Code Assistant to use the `openspec-propose` skill with your idea. Skills activate through request matching; OpenSpec does not generate `/openspec-*` commands for this tool.
+
+MiniMax Code is a global skills-only integration. OpenSpec writes only its
+`openspec-*` directories under `~/.minimax/skills/`; it does not create
+repo-local `.minimax` or `.mavis` directories. Commands-only delivery leaves
+existing global MiniMax Code skills untouched so one project's delivery setting
+cannot remove skills used by another project.
+
+### GitHub Copilot cloud coding agent
+
+GitHub's [Copilot coding agent](https://docs.github.com/en/copilot/using-github-copilot/coding-agent) runs on GitHub in a GitHub Actions environment — separate from Copilot in your editor. OpenSpec can set it up to use the OpenSpec CLI by generating two files:
+
+- `.github/workflows/copilot-setup-steps.yml` — installs `@fission-ai/openspec` in the agent's environment
+- `.github/agents/openspec.agent.md` — tells the agent how to drive OpenSpec
+
+Because this writes a GitHub Actions workflow into your repository, it is **opt-in**:
+
+| How | Behavior |
+|-----|----------|
+| `openspec init` (interactive) | Asks whether to set up cloud files. Default is **No**. |
+| `openspec init --copilot-cloud` | Sets them up without prompting (for scripts/CI). |
+| `openspec init --no-copilot-cloud` | Skips them without prompting, and removes any previously generated ones. |
+| `openspec update` | Never prompts. Refreshes the files only if you opted in (or the project already has them). If you opted out, it removes OpenSpec-managed cloud files. |
+
+Your choice is saved in `openspec/config.yaml` as `githubCopilot.cloudAgent: true|false`, so non-interactive updates honor it. OpenSpec only ever writes or removes files whose content it generated — if you customize `copilot-setup-steps.yml` or `openspec.agent.md`, or already have your own, it is left untouched (and `init`/`update` tell you so).
+
+### When to pick the shared `.agents` target
+
+`agents` is the vendor-neutral option: it writes skills to `.agents/skills/`, the
+shared root many agent tools read, instead of a tool-specific directory.
+
+| Situation | Pick |
+|-----------|------|
+| Your tool has its own row above | Its own ID — you get that tool's integration, including slash commands where it supports them |
+| Several agents on one repo, all reading `.agents/skills` | `agents` — one skill tree instead of one per tool |
+| Your tool isn't listed yet but reads `.agents/skills` | `agents` |
+
+Selecting it alongside a tool-specific ID is fine; each normally writes to its
+own root. Codex and Zed Agent are the exceptions because they use the same canonical
+`.agents` root. If Codex is selected with Zed or `agents`, OpenSpec keeps one
+Codex-led tree. Its handoffs name both `$openspec-*` for Codex and
+`/openspec-*` for other agents, so `--tools all` and existing multi-agent
+setups keep working without two writers overwriting the same files.
+OpenSpec also offers it automatically once a project has a `.agents/skills/`
+directory — a bare `.agents/` is not enough, since tools use that root for rules
+and subagent definitions too. Note `.agents` is not `.agent`: the singular
+directory belongs to Antigravity.
+
+Two things to know:
+
+- **Skills only.** No command adapter exists, so no `opsx-*` command files are
+  written; with a commands-inclusive delivery mode `openspec init` lists `agents`
+  among the tools it reports under `Commands skipped for: … (no adapter)`.
+  Invoke the workflows by skill name —
+  most assistants that read `.agents/skills` spell that `/openspec-propose`, the form
+  OpenSpec's setup hint prints. The target is vendor-neutral, so check your
+  assistant's own docs if it uses another form.
+- **No `AGENTS.md` is created or edited.** The target is the `.agents/` directory.
+  If your root `AGENTS.md` still carries OpenSpec marker blocks from an older
+  version, `openspec update` strips them — see the [Migration Guide](migration-guide.md).
+
+Zed support here is for the built-in Zed Agent. Zed External Agents and Terminal
+Threads use their own integrations. Agent Skills require
+[Zed v1.4.2](https://github.com/zed-industries/zed/releases/tag/v1.4.2) or newer.
+Project-local skills are unavailable in an untrusted worktree until you
+[grant trust](https://zed.dev/docs/worktree-trust).
+
+Because `.agents/skills/` is shared by Codex, Zed Agent, and the vendor-neutral target,
+it is worth knowing what OpenSpec claims there:
+it writes, refreshes, and removes only the `openspec-*` skill directories for your
+selected workflows, plus an `.openspec-target` marker that records whether Codex,
+Zed Agent, or the vendor-neutral target rendered that shared tree. Anything else in that
+directory is left alone. Treat the `openspec-*` names and marker as OpenSpec's —
+edits inside them are replaced on the next `openspec update`, the same as for
+every other tool.
+
+For pre-marker projects, OpenSpec infers ownership from managed skill references:
+`$openspec-*` means Codex and `/openspec-*` means the vendor-neutral target. A
+generic canonical tree alongside legacy `.codex/skills` is treated as an older
+dual-target install and consolidated into the compatible shared tree.
+
+`openspec update` honors this ownership too. If a project owns `.agents` as the
+vendor-neutral target and a leftover Codex install is detected only from stray
+prompt files, the update leaves the established `agents` tree in place instead of
+rewriting it with Codex syntax, and preserves those legacy prompt files rather
+than deleting them. To hand the shared tree to Codex, run `openspec init --tools
+codex` explicitly.
+
 ## Non-Interactive Setup
 
 For CI/CD or scripted setup, use `--tools` (and optionally `--profile`):
@@ -123,7 +219,7 @@ openspec init --tools none
 openspec init --profile core
 ```
 
-**Available tool IDs (`--tools`)** — `windsurf` is also accepted, as an alias for `devin`: `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codeartsagent`, `codex`, `devin`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `hermes`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `zcode`
+**Available tool IDs (`--tools`)** — `windsurf` is also accepted, as an alias for `devin`: `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `command-code`, `codeartsagent`, `codex`, `devin`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `hermes`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `minimax-code`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `codeassistant`, `trae`, `zed`, `zcode`, `agents`
 
 ## Workflow-Dependent Installation
 

docs/troubleshooting.md

@@ -59,7 +59,7 @@ If `/opsx:propose` (or your tool's equivalent) doesn't appear or doesn't do anyt
 
 5. **Check you initialized this project.** Skills are written per project. If you cloned a repo or switched folders, run `openspec init` (or `openspec update`) there.
 
-6. **Confirm your tool supports command files.** Codex, CodeArts, ForgeCode, Hermes, Kimi Code and Mistral Vibe don't get generated `opsx-*` command files; they use skill-based invocations instead, so `/opsx` will never autocomplete for them. Type `$openspec-propose` in Codex, `/skill:openspec-propose` in Kimi Code, and `/openspec-propose` in the rest. Amazon Q does get command files, but loads them into its prompt library rather than its slash menu — type `@opsx-propose` there, not `/opsx`. Every tool's form is listed in [How To Invoke](supported-tools.md#how-to-invoke).
+6. **Confirm your tool supports command files.** Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent, and the shared `.agents` target don't get generated `opsx-*` command files; they use skill-based invocations instead, so `/opsx` will never autocomplete for them. Type `$openspec-propose` in Codex, `/skill:openspec-propose` in Kimi Code, and `/openspec-propose` in the rest. The shared `.agents` target is vendor-neutral, so `/openspec-propose` is the common form rather than a guaranteed one — if your assistant does not answer to it, check its own docs for how it invokes a skill. Amazon Q does get command files, but loads them into its prompt library rather than its slash menu — type `@opsx-propose` there, not `/opsx`. Every tool's form is listed in [How To Invoke](supported-tools.md#how-to-invoke).
 
 ## Working with changes
 
@@ -92,10 +92,19 @@ Validation checks your specs and changes for structural problems. Read the messa
 openspec validate <name>           # validate one item
 openspec validate --all            # validate everything
 openspec validate --all --strict   # stricter checks, good for CI
+openspec validate --archived       # fail if archived changes have unchecked tasks
 ```
 
 Common causes are a missing required section (like a spec with no scenarios) or a malformed delta header. Fix the file and re-run. The [CLI reference](cli.md#openspec-validate) documents the output format.
 
+One message deserves its own note:
+
+```text
+MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"
+```
+
+A `MODIFIED` requirement replaces the whole requirement block, so it has to carry every scenario that survives the change, not only the ones you edited. Copy the named scenarios from `openspec/specs/<capability-path>/spec.md` back into the delta, preserving any domain directories in the path. This often appears on an older change after someone else's change added a scenario to the same requirement — archive refuses that change either way, and validation now says so before you implement it.
+
 ### The AI created incomplete or wrong artifacts
 
 The AI didn't have enough context. A few levers help:
@@ -109,6 +118,20 @@ The AI didn't have enough context. A few levers help:
 
 Archive won't *block* on incomplete tasks, but it warns you, because archiving usually means the work is done. If tasks remain on purpose (you're filing a partial change), proceed. Otherwise finish the tasks first. Archive will also offer to sync your delta specs into the main specs if you haven't synced yet; say yes unless you have a reason not to.
 
+### "User force closed the prompt with 0 null"
+
+Something ran `openspec archive` where nothing can answer a question — an AI agent calling it from a tool, a CI job, or any shell with stdin closed. Archive asks up to three confirmations, and an unanswerable one used to fail with that raw message.
+
+Pass `--yes` to answer them up front:
+
+```bash
+openspec archive <change-name> --yes
+```
+
+Keep any flags you were already passing — `--skip-specs` and `--no-validate` change what archive does, so a bare `--yes` rerun is not the same command. Current versions name the flag for you and print a `Fix:` line you can paste. If you meant to pick from a list, pass the change name explicitly: the picker needs an answer too.
+
+If you instead ran archive with its output redirected to a file or captured by a tool and *did* pipe an answer (`printf 'y\n' | openspec archive …`), older versions wrote terminal escape codes into that capture while drawing the prompt — in some environments enough to bloat the file badly. Current versions read the confirmation prompts as plain text whenever stdout is not a terminal, and a no-argument `openspec archive` (which would otherwise draw an interactive change picker) asks you to pass a change name up front instead of rendering a menu into the capture. Either way, redirected and agent runs stay clean; passing `--yes` (with a change name) skips the prompts entirely.
+
 ## Configuration
 
 ### My `config.yaml` isn't being applied
@@ -153,7 +176,7 @@ You're in CI or a non-interactive shell, and OpenSpec found old files to clean u
 openspec init --force
 ```
 
-For Codex, OpenSpec may detect old managed prompt files in `$CODEX_HOME/prompts` or `~/.codex/prompts`. That cleanup is limited to OpenSpec's allowlisted legacy Codex prompt filenames, and non-interactive `openspec init` removes only the files whose replacement `.codex/skills/openspec-*` skills exist. Non-interactive `openspec update` leaves all legacy cleanup untouched unless you pass `--force`.
+For Codex, OpenSpec may detect old managed prompt files in `$CODEX_HOME/prompts` or `~/.codex/prompts`. That cleanup is limited to OpenSpec's allowlisted legacy Codex prompt filenames, and non-interactive `openspec init` removes only the files whose replacement `.agents/skills/openspec-*` skills exist. Non-interactive `openspec update` leaves all legacy cleanup untouched unless you pass `--force`.
 
 ### Commands didn't appear after migrating
 

docs/workflows.md

@@ -28,6 +28,75 @@ OPSX (fluid actions):
 
 > **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
 
+## Workflow at a Glance
+
+The default workflow stays fluid: exploration and verification are optional, and
+you can update planning artifacts whenever implementation reveals something new.
+
+```mermaid
+flowchart TD
+    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
+    Idea --> Propose["/opsx:propose"]
+    Explore --> Propose
+    Propose --> Review{"Planning artifacts<br/>ready?"}
+    Review -->|"Refine"| Update["/opsx:update"]
+    Update --> Review
+    Review -->|"Implement"| Apply["/opsx:apply"]
+    Apply -->|"Plan changed"| Update
+    Apply --> Archive["/opsx:archive"]
+    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
+    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
+    Verify --> Verified{"Ready to archive?"}
+    Verified -->|"Fix implementation"| Apply
+    Verified -->|"Revise plan"| Update
+    Verified -->|"Ready"| Sync
+    Verified -->|"Ready"| Archive
+    Sync --> Archive
+```
+
+The AI assistant drives the workflow, while the CLI provides deterministic
+scaffolding, status, and artifact instructions:
+
+```mermaid
+sequenceDiagram
+    actor Human
+    participant Assistant as AI assistant
+    participant CLI as OpenSpec CLI
+    participant Files as Planning and implementation files
+
+    Human->>Assistant: /opsx:propose "change"
+    Assistant->>CLI: openspec new change
+    CLI->>Files: Scaffold change metadata
+    Assistant->>CLI: Request status and artifact instructions
+    CLI-->>Assistant: Build order, paths, and templates
+    Assistant->>Files: Write schema-defined planning artifacts
+    Assistant-->>Human: Present artifacts for review
+
+    Human->>Assistant: /opsx:apply
+    Assistant->>CLI: Request apply instructions
+    CLI-->>Assistant: Context files and task state
+    Assistant->>Files: Implement tasks and update checkboxes
+    Assistant-->>Human: Report implementation status
+
+    Human->>Assistant: /opsx:archive
+    Assistant->>CLI: Request archive inputs and artifact status
+    CLI-->>Assistant: Planning paths and artifact completion
+    Assistant->>Files: Read task state and compare delta specs
+    opt Delta specs exist
+        Assistant-->>Human: Offer to sync before archiving
+        alt Sync accepted
+            Human->>Assistant: Confirm sync
+            Assistant->>Files: Merge delta specs into main specs
+        else Sync skipped
+            Human->>Assistant: Archive without syncing
+        end
+    end
+    Assistant->>Files: Move the change into the archive
+    Assistant-->>Human: Report archive location and sync result
+
+    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives
+```
+
 ## Two Modes
 
 ### Default Quick Path (`core` profile)

docs/writing-specs.md

@@ -56,9 +56,9 @@ A change describes its edits to the specs with three section types. Using the ri
 - **`## MODIFIED Requirements`** — behavior that already existed and is changing. Include the full new version; a short note on what changed helps a reviewer.
 - **`## REMOVED Requirements`** — behavior going away, with a line on why.
 
-On archive, ADDED gets appended to the main spec, MODIFIED replaces the old version, and REMOVED is deleted. If you mark a real change as ADDED, you end up with two competing requirements; if you describe new behavior as MODIFIED, there's nothing to replace. When in doubt, open the current spec and see whether the requirement is already there.
+On archive, ADDED gets appended to the main spec, MODIFIED replaces the old version, and REMOVED is dropped from it. Remove the last requirement a capability has and you retire it: rather than leave a spec with nothing in it, archive deletes `openspec/specs/<capability>/spec.md`. Because that is the one archive step that removes a file, it has to be asked for — add `retire_capabilities: true` to the change's `.openspec.yaml`, alongside the `schema:` that file already needs. Without it the archive aborts and tells you so. Retirement deletes the whole file, so it is also refused while the spec holds anything outside its title, `## Purpose`, and its requirement blocks — a `## Notes` section, a comment under a requirement. The abort names those lines; move them into `## Purpose` or a requirement, or delete the spec by hand. For a spec in the caller's checkout, the archive output also names the `git checkout` that restores a committed file; selected stores receive checkout-scoped recovery guidance instead. If you mark a real change as ADDED, you end up with two competing requirements; if you describe new behavior as MODIFIED, there's nothing to replace. When in doubt, open the current spec and see whether the requirement is already there.
 
-One more section is worth knowing about. When your delta creates a capability that doesn't exist yet, open it with `## Purpose` — a sentence or two on what the capability is for. Archive uses it as the Purpose of the main spec it creates; skip it and you get a `TBD` placeholder to fill in by hand. An existing spec already has a Purpose, so a delta's is ignored there — edit `openspec/specs/<capability>/spec.md` directly to change one.
+One more section is worth knowing about. When your delta creates a capability that doesn't exist yet, open it with `## Purpose` — a sentence or two on what the capability is for. Archive uses it as the Purpose of the main spec it creates; skip it and you get a `TBD` placeholder to fill in by hand. An existing spec already has a Purpose, so a delta's is ignored there — edit `openspec/specs/<capability-path>/spec.md` directly to change one. Here, `<capability-path>` is the directory relative to `specs/`, such as `user-auth` in a flat project or `identity/user-auth` in a project organized by domain.
 
 ## Right-size the change
 

flake.nix

@@ -39,6 +39,7 @@
                 ./test
                 ./package.json
                 ./pnpm-lock.yaml
+                ./pnpm-workspace.yaml
                 ./tsconfig.json
                 ./build.js
                 ./vitest.config.ts
@@ -49,16 +50,16 @@
 
             pnpmDeps = pkgs.fetchPnpmDeps {
               inherit (finalAttrs) pname version src;
-              pnpm = pkgs.pnpm_9;
+              pnpm = pkgs.pnpm_10;
               fetcherVersion = 3;
-              hash = "sha256-AHPKWjhrk4aTJvp9uqTJk15vASEZyRUoSw0W9oV2650=";
+              hash = "sha256-SNPeEUa+amkZYRO5tHeUwDBT4betXYPKnfZiEyhN7fE=";
             };
 
             nativeBuildInputs = with pkgs; [
               nodejs_22
               npmHooks.npmInstallHook
               pnpmConfigHook
-              pnpm_9
+              pnpm_10
             ];
 
             buildPhase = ''
@@ -98,7 +99,7 @@
           default = pkgs.mkShell {
             buildInputs = with pkgs; [
               nodejs_22
-              pnpm_9
+              pnpm_10
             ];
 
             shellHook = ''

install.md

@@ -0,0 +1,70 @@
+# openspec
+
+> OpenSpec gives you and your coding agent a shared, reviewable plan before code is written. This file installs its CLI and sets up your project.
+
+I want you to install OpenSpec and set up my project. Follow the steps below in order, and stop where a step tells you to stop.
+
+OBJECTIVE: Install the OpenSpec CLI globally and initialize the user's project.
+
+DONE WHEN:
+
+- `openspec --version` prints a version number
+- the project the user confirmed has an `openspec/` folder created or refreshed by `openspec init`
+- the user has been told the exact spelling to invoke OpenSpec in their AI coding tool
+
+TODO:
+
+- [ ] Check the Node.js runtime
+- [ ] Install the CLI globally, with the user's confirmation
+- [ ] Verify `openspec` is on PATH
+- [ ] Confirm which folder to set up, then run `openspec init --tools <ids>` there
+- [ ] Report what init actually created and how to invoke it
+
+## 1. Runtime
+
+Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If Node is missing or older, say so and stop, but leave the user with their next move: point them at https://nodejs.org, or if they use a version manager like nvm, name the command that would switch to a newer version. Don't install Node, switch versions, or reconfigure the user's version manager yourself.
+
+## 2. Install
+
+Run `openspec --version` first. If it already prints a version, the CLI is installed: say so, offer to update it with the install command below, and if the user declines skip ahead to step 4.
+
+Use whichever package manager is already on PATH, preferring npm:
+
+```bash
+npm install -g @fission-ai/openspec@latest
+pnpm add -g @fission-ai/openspec@latest
+bun add --global @fission-ai/openspec@latest
+yarn global add @fission-ai/openspec@latest   # Yarn 1.x only
+```
+
+Don't pick based on this project's lockfile: a global install has nothing to do with how this repo's own dependencies are installed. If none of those four is available, stop and say so; don't improvise an install. (On Nix, point the user at the Nix section of https://openspec.dev/docs/installation instead.)
+
+Show the exact command and get confirmation before running it; this installs software outside the project, and the user may want a different package manager to own it.
+
+Stop and ask again if the install needs sudo or admin rights, fails with a permissions error, or reports that its global bin directory is missing or unconfigured. Never edit shell startup files (.bashrc, .zshrc, .profile, fish, PowerShell profile), and never run a setup command that edits them; show the change and let the user make it.
+
+## 3. PATH
+
+Run `openspec --version`. If the command isn't found, it may only be missing from this shell: say where the package manager installed it and how to add that directory to PATH for the user's shell and OS, then stop until they confirm. If it prints an older version than the one the install just reported, an earlier copy is shadowing it on PATH; report both versions instead of continuing. If the user uses a version manager, say so rather than editing PATH around it: with nvm or fnm the CLI is tied to the Node version that was active at install time, and with asdf or volta a shim may need regenerating.
+
+## 4. Initialize
+
+Work out where `openspec/` should go, and lead with your best guess rather than an open question: the root of the project the user is working in is almost always right. Name the folder you picked and let them correct it, for example "you're in ~/code/acme-api, so I'll set OpenSpec up there". Prefer the version control root over the current directory, and in a monorepo say which package you chose and why. To target a folder other than the current one, pass it: `openspec init <path> --tools <ids>`.
+
+init creates `openspec/` wherever you point it and won't warn you when that's wrong. If the folder is a home directory, a temp directory, or holds no project at all, stop and ask where the project is.
+
+Then work out which AI coding tools the user works with, and again lead with an inference instead of an open question: you are probably running inside one of them, so name it and ask what else they use, suggesting a few common options (Claude Code, Cursor, Copilot, Codex). Say what the answer changes: each tool named gets its own skill and command files in the project, and re-running init later adds more, so a short list now costs nothing. Map each tool to an id from `openspec init --help` (Copilot is `github-copilot`, Zoo Code is `roocode`). `--tools` takes a comma-separated list, so name all of them.
+
+`openspec init --tools <ids>` deletes leftovers from older OpenSpec versions automatically, without asking, including `opsx-*.md` prompt files in the home directory (Codex keeps them in `~/.codex/prompts`). Before running it, look for those: `.../commands/openspec/` folders, OpenSpec marker blocks in files like CLAUDE.md or AGENTS.md, and home-directory `opsx-*.md` prompts. List whatever you find, say plainly that init will delete these, and wait for a go-ahead; if you find nothing, say so and carry on without asking. An existing `openspec/` folder is not a problem: init refreshes it and leaves specs and changes alone.
+
+Then run: `openspec init --tools <ids>`, adding the path when it isn't the current folder.
+
+## 5. Report
+
+Don't assume what should exist; relay what init actually printed: how many skills and/or commands it created and where, the config file line, any "Setup required" note, and what to restart or reload. Some tools are skills-only and correctly create zero command files, so missing commands is not a failure on its own. If init said nothing was generated, relay the fix it suggested instead of retrying.
+
+Finish by telling the user how to invoke OpenSpec in their tool, taking the exact spelling from the files init created rather than from its summary line: the punctuation differs per tool (`/opsx:propose` in some, `/opsx-propose` in others, `@opsx-propose` in Amazon Q), and tools that get skills instead of commands are invoked by skill name (`/openspec-propose`, or `$openspec-propose` in Codex, or `/skill:openspec-propose` in Kimi Code).
+
+EXECUTE NOW: Complete the TODO list above to achieve: the OpenSpec CLI installed, this project initialized, and the user told exactly how to invoke OpenSpec in their AI coding tool.
+
+More context for agents: https://openspec.dev/llms.txt

openspec/changes/add-init-agents-target/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-29

openspec/changes/add-init-agents-target/proposal.md

@@ -0,0 +1,33 @@
+## Why
+
+`.agents/skills` has become the shared, vendor-neutral location modern agent tools read. OpenSpec already carried an `agents` entry in `AI_TOOLS`, but with `available: false` and no `skillsDir` it was unreachable — every real gate keys off `skillsDir`. Teams running several agents on one repo, or a tool with no first-class integration yet, had to generate for some other tool and move the files by hand (#1480), or pick a vendor target they do not use (#1104, #653).
+
+## What Changes
+
+- Enable `agents` in `AI_TOOLS` with `skillsDir: '.agents'`, making it selectable interactively and via `--tools agents`.
+- Scope detection to `detectionPaths: ['.agents/skills']` so a bare `.agents/` written by another framework does not select — or silently install into — the target.
+- Rename the entry to `Shared .agents skills`. The old label said "AGENTS.md", but OpenSpec writes no `AGENTS.md` — it strips its markers out of one.
+- Document the target, including when to prefer it over a tool-specific integration.
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define the `.agents` skills root and its scoped detection path
+- `cli-init`: record that the shared target installs skills and skips command generation
+
+## Impact
+
+- `src/core/config.ts` - enable the `agents` entry, scope detection, correct the label
+- `.changeset/add-agents-tool.md` - minor release note, including the `--tools all` behavior change
+- `docs/supported-tools.md`, `docs/cli.md`, `docs/commands.md`, `docs/how-commands-work.md`, `docs/troubleshooting.md` - list `agents` among skills-only tools and explain when to choose it
+- `test/core/*`, `test/commands/*`, `test/cli-e2e/*` - cover init, update, detection, and the deprecated alias
+
+## Non-Goals
+
+- No command adapter for `agents`. There is no cross-vendor slash-command format, so commands stay skills-only (the Kimi/Hermes pattern).
+- No `.pi`, `.codex`, or `.agent` migration into `.agents`. Moving vendor tools to the shared root is separate work (#830, #1157).

openspec/changes/add-init-agents-target/specs/ai-tool-paths/spec.md

@@ -0,0 +1,23 @@
+# ai-tool-paths Delta Specification
+
+## ADDED Requirements
+
+### Requirement: Shared .agents skills target
+
+OpenSpec SHALL provide a vendor-neutral `agents` tool target rooted at the shared `.agents` directory, for assistants that read skills from the shared location rather than a vendor-specific one.
+
+#### Scenario: Shared agents target paths defined
+
+- **WHEN** looking up the `agents` tool
+- **THEN** `skillsDir` SHALL be `.agents`
+
+#### Scenario: Detection keys off the shared skills subtree
+
+- **WHEN** a project contains a `.agents/skills` path
+- **THEN** OpenSpec SHALL detect `agents` as an available target
+
+#### Scenario: A bare shared root does not select the target
+
+- **GIVEN** a project contains `.agents` but no `.agents/skills` path
+- **WHEN** OpenSpec detects available tools
+- **THEN** `agents` SHALL NOT be reported as available

openspec/changes/add-init-agents-target/specs/cli-init/spec.md

@@ -0,0 +1,20 @@
+# cli-init Delta Specification
+
+## ADDED Requirements
+
+### Requirement: Shared .agents target initialization
+
+`openspec init` SHALL accept the shared `agents` target wherever tool IDs are selected, and SHALL treat it as a skills-only tool.
+
+#### Scenario: Non-interactive selection of the shared target
+
+- **WHEN** the user runs `openspec init --tools agents`
+- **THEN** OpenSpec SHALL generate skills for the `agents` target
+- **AND** initialization SHALL NOT fail because `agents` has no registered command adapter
+
+#### Scenario: Shared agents target skips command-file generation
+
+- **GIVEN** the configured delivery includes command generation
+- **WHEN** the user selects the shared `agents` target during initialization
+- **THEN** command-file generation SHALL be skipped because no `agents` adapter is registered
+- **AND** `agents` SHALL be listed among the tools reported as having commands skipped

openspec/changes/add-init-agents-target/tasks.md

@@ -0,0 +1,21 @@
+## 1. Tests
+
+- [x] 1.1 Cover `agents` init, update, detection, and the deprecated `experimental --tool` alias
+- [x] 1.2 Assert a bare `.agents/` directory does not select the target
+
+## 2. Registry
+
+- [x] 2.1 Enable `agents` in `src/core/config.ts` with `skillsDir: '.agents'`
+- [x] 2.2 Scope detection with `detectionPaths: ['.agents/skills']`
+- [x] 2.3 Rename the entry to `Shared .agents skills` so it names the directory instead of a file OpenSpec never writes
+
+## 3. Docs
+
+- [x] 3.1 Add `agents` to the tool ID lists in `docs/cli.md` and `docs/supported-tools.md`
+- [x] 3.2 Add the Tool Directory row and the skills-only invocation rows across `docs/supported-tools.md`, `docs/commands.md`, `docs/how-commands-work.md`, and `docs/troubleshooting.md`
+- [x] 3.3 Document when to choose the shared target over a tool-specific integration
+
+## 4. Verification
+
+- [x] 4.1 Run `pnpm run build` and the full Vitest suite
+- [x] 4.2 Validate with `openspec validate --strict`, and confirm `openspec archive` applies cleanly against a scratch copy of `openspec/`

openspec/changes/add-validation-findings-report/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-21

openspec/changes/add-validation-findings-report/design.md

@@ -0,0 +1,192 @@
+## Context
+
+See `proposal.md` for motivation and measured output size. Bulk validation currently has one documented JSON contract: top-level `version: "1.0"`, a complete `items` array for the requested scope, `summary`, and `root`. Human bulk output lists every item before totals.
+
+The preserved feasibility candidate proves that completed validation results can be projected while retaining totals, severities, scope, and exit status. It is not the proposed contract: the candidate reused `items` under top-level version `1.0`, which could let a consumer interpret a subset as the complete scope.
+
+Implementation measurement on August 27, 2026 used this repository's 83-change archive, not the original 895-change corpus (which is not available in this checkout). `openspec validate --archived --json` emitted 14,690 bytes; adding `--report findings` emitted 4,047 bytes, a 72.5% reduction. Both retained all 12 failing items, totals of 71 passed and 12 failed, the same root, and exit 1. Explicit `--report full` matched the default document after normalizing `durationMs`. The findings items exactly matched the issue-bearing full records after the same normalization. Byte counts can vary with timings and checkout paths. This measures output size, not runtime.
+
+The implementation baseline was updated from main on August 27, 2026. Its full-result top-level inventory is `items`, `summary`, `version`, and `root`; there is no advisory collection outside item results. Existing `INFO` issues inside item records are retained by whole-record projection. A future top-level advisory such as `overlaps` requires an explicit contract update defining its JSON field and human section before inclusion.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Reduce human and agent-facing output when a bulk validation scope is dominated by clean items.
+- Preserve the current complete report as the default and as explicit `full` mode.
+- Give JSON findings an exact discriminator and a document that is intentionally distinct from full v1.
+- Preserve complete item records, item order, issue detail and severity, requested scope, summary totals, root selection, and exit status.
+- Reject ambiguous report requests before prompts, root selection, progress UI, or validation work.
+
+**Non-Goals:**
+
+- Improving validation runtime or skipping validation work for valid requests.
+- Changing validation rules, strict-mode semantics, concurrency, full-report ordering, or exit codes.
+- Adding summary-only output, alternate serializers, TOON, a general output framework, project defaults, or new dependencies.
+- Changing omitted-`--report` targeted, interactive, or mixed-flag behavior.
+- Automatically copying unknown future top-level report fields into the findings document.
+
+## Decisions
+
+### 1. Use one bulk report selector; keep serialization orthogonal
+
+`--report` accepts `full` and `findings`. Omitting it preserves every existing command flow. Explicit `--report full` and `--report findings` are bulk-report selectors: both require an explicit, unambiguous bulk scope and neither is accepted with an item name. In particular, `openspec validate <item> --report full` is intentionally rejected rather than treated as a targeted alias.
+
+This keeps report content separate from serialization: `--report findings` selects the findings contract, while `--json` serializes that contract. Help text is `Select bulk report content: full|findings; combine with --json for JSON`.
+
+The existing CLI has command-specific projections (`--deltas-only`, `--requirements`, and `--no-scenarios`) but no generic `--only`, `--report`, or `--format` vocabulary. `--findings-only` and `--only findings` read like in-place filters on the existing JSON document. `--report findings` makes the separately versioned document intentional and avoids adding more booleans if another report contract is justified later.
+
+### 2. Resolve active scope combinations and reject archive ambiguity
+
+For an explicit report request, the canonical scope is resolved as follows:
+
+| Input flags | Canonical scope |
+|---|---|
+| `--changes` | `changes` |
+| `--specs` | `specs` |
+| `--changes --specs` | `all` |
+| `--all`, including `--all` plus either active subset | `all` |
+| `--archived` | `archived` |
+
+`--archived` combined with any active scope flag is rejected. An item name combined with any explicit report option is rejected, whether or not a bulk flag is also present. An explicit report option without a bulk scope and an unsupported report value are also rejected. Omitted `--report` retains current precedence and behavior, including existing mixed-flag behavior; this proposal does not retroactively tighten old invocations.
+
+### 3. Fail invalid report requests before doing work
+
+Report mode and scope are normalized before root resolution or validation. Invalid human requests write a targeted error to stderr, write nothing to stdout, render no prompt or spinner, perform no validation, and exit 1.
+
+With `--json`, every parsed invalid report request writes exactly one JSON document to stdout, writes no human text to either stream, performs no root resolution or validation, and exits 1:
+
+```json
+{
+  "status": [
+    {
+      "severity": "error",
+      "code": "invalid_validation_report_request",
+      "message": "The requested validation report and scope cannot be combined.",
+      "fix": "Use --report full|findings with one active bulk scope or --archived, without an item name."
+    }
+  ]
+}
+```
+
+The `code` is stable. The message may identify the specific conflict while retaining that code and one-status-entry shape. Values are case-sensitive: only `full` and `findings` are supported. Missing option arguments, such as bare `--report`, are CLI syntax errors handled by the existing parser before command execution; they are outside this structured report-request contract. This change does not alter generic parser error handling.
+
+A valid report request can still fail during root resolution or scope discovery. Those failures retain the existing command diagnostic, nonzero exit status, and JSON `status` envelope rather than emitting a findings document with misleading empty totals. Per-item validation failures remain item results and do produce a completed report.
+
+### 4. Use a distinct item-findings JSON document
+
+After root resolution, scope discovery, and validation complete, `--json --report findings` returns a document like this three-item example:
+
+```json
+{
+  "report": {
+    "kind": "validation-findings",
+    "version": "1.0",
+    "scope": "archived",
+    "returnedItems": 1,
+    "totalItems": 3
+  },
+  "itemFindings": [
+    {
+      "id": "example-change",
+      "type": "change",
+      "valid": false,
+      "issues": [
+        {
+          "level": "ERROR",
+          "path": "tasks.md",
+          "message": "4 incomplete tasks (15/19 completed)"
+        }
+      ],
+      "durationMs": 3
+    }
+  ],
+  "summary": {
+    "totals": { "items": 3, "passed": 2, "failed": 1 },
+    "byType": {
+      "change": { "items": 3, "passed": 2, "failed": 1 }
+    }
+  },
+  "root": {
+    "path": "<resolved-root>",
+    "source": "nearest"
+  }
+}
+```
+
+The typed projection is exactly the full result's item records filtered by `item.issues.length > 0`. It preserves full-report order and returns each selected record whole rather than rebuilding a fixed field list, so current fields and future additive item fields survive. `report.returnedItems` equals `itemFindings.length`; `report.totalItems` equals `summary.totals.items`. `ERROR`, `WARNING`, and `INFO` all count as item findings, regardless of whether the item's `valid` field is true.
+
+The findings document has no top-level `items` or top-level `version`, and it carries the exact `report.kind: "validation-findings"` discriminator and exact JSON-string `report.version: "1.0"`. Contract tests assert the version value and its string type. Tests also assert that the document does not conform to the documented full-v1 contract, which requires top-level `version: "1.0"` and a complete `items` array. No claim is made about how arbitrary permissive parsers behave.
+
+The implementation explicitly maps the current full-result inventory: `items` becomes filtered `itemFindings`; `summary` and `root` are retained whole; top-level `version` is replaced by the findings discriminator and version under `report`. It does not generically spread unknown full-result fields. No top-level advisory collection exists in this baseline, so none is emitted. Any future advisory must be explicitly named in the contract, remain separate from `itemFindings`, and not affect `returnedItems`.
+
+JSON findings emit exactly one document on stdout and no stderr text.
+
+### 5. Define human findings sections and order each stream independently
+
+Human findings preserve stream ownership, but stdout and stderr may be buffered or interleaved by the caller. The contract therefore defines ordering independently within each stream and makes no relative-order promise between a stdout section and a stderr section.
+
+Within stdout, sections appear in this order:
+
+1. `Scope:` line.
+2. If `itemFindings` is empty, `No item findings.`; otherwise there is no item row or item block on stdout.
+3. `Totals:` for the complete scope.
+4. The existing first-failure `Details:` command for active scopes when one is currently provided; findings mode does not invent a details line for archived scope.
+
+Within stderr, sections appear in this order:
+
+1. Item-finding blocks in full-report item order. Each block prints its item heading once, followed by every issue in issue order with its original `ERROR`, `WARNING`, or `INFO` label, path, and message. All three severities use stderr.
+2. Any future advisory section explicitly added to the contract would follow item-finding blocks on stderr and remain distinct from item findings. There is no such section in this implementation.
+
+Clean item rows are omitted. `No item findings.` says nothing about separately rendered advisories. Tests capture and assert each stream independently rather than asserting a merged stdout/stderr sequence. A valid findings request may retain existing progress behavior, which is outside this final-report per-stream ordering contract; the invalid-request path never renders progress UI.
+
+### 6. Use one typed projector for active and archived results
+
+Active and archived validation currently assemble similar result/summary envelopes on separate paths. Implementation defines one typed findings projection over the shared full-result contract and routes both paths through it. This prevents scope, ordering, whole-record preservation, and returned/total count rules from drifting. Human and JSON renderers consume that same projection; they do not independently filter.
+
+### 7. Keep verdict, root, and platform behavior unchanged
+
+For valid requests, findings mode validates the same requested items as full mode. `summary` is the full-scope summary and exit status is identical for the same scope and strictness. Warning- and info-only records remain visible even when they do not fail a non-strict run.
+
+The report uses the same resolved repo or store root and unchanged path values as full validation, including platform-native root paths and existing POSIX-normalized issue paths. No path construction or rewriting is introduced. The `--report` flag is registered on every currently supported completion surface: Bash, Zsh, Fish, and PowerShell. Only Zsh and Fish suggest the fixed `full` and `findings` values because only those existing generators consume registry value metadata. Bash and PowerShell remain unchanged beyond flag registration. This proposal does not add a completion capability or broaden the set of generators; any additional shell or agent completion surface requires separate justification.
+
+## Alternatives Considered
+
+### Reuse full-v1 `items` with only issue-bearing records
+
+Rejected. Projection metadata does not undo the documented meaning of the complete `items` collection; a consumer can silently undercount clean items.
+
+### Introduce projected `items` in a new full JSON version
+
+Rejected for this contribution. A v2 union can be safe, but it creates a broader protocol migration for a narrow projection. A separate discriminator and `itemFindings` collection avoid changing full v1.
+
+### Human-only compact output
+
+Rejected as the recommendation. It is the smallest surface, but leaves the structured agent/log use case unsolved.
+
+### Use `--findings-only` or `--only findings`
+
+Rejected. Both frame the behavior as filtering the existing output shape. The report selector makes the distinct JSON contract intentional and composes with `--json` as content plus serialization.
+
+### Document external filtering only
+
+Safe and still supported. Callers can filter full JSON through `jq` or PowerShell, but the complete document still crosses the CLI boundary and each integration must recreate scope, summary, and exit-code discipline.
+
+### Add summary mode or a general output framework
+
+Rejected. Summary-only output omits actionable item findings. Alternate serializers, preferences, and frameworks expand maintenance and compatibility risk without evidence they are required.
+
+## Risks / Trade-offs
+
+- **A second JSON report contract is durable API surface.** Mitigation: one exact discriminator/version, one item projector, and reuse of full item records, summary, and root.
+- **Output savings depend on corpus shape.** The measured matrix ranged from 4.9% on an issue-dense synthetic human case to 95.7% on the real 895-change archive. The 6,740-byte figure belongs to the feasibility candidate, not this exact envelope. Mitigation: claim output reduction only and remeasure the implemented envelope.
+- **Item findings can be confused with top-level advisories.** Mitigation: `itemFindings`, `No item findings.`, separate advisory sections, and counts that cover item records only.
+- **Unknown top-level fields could be dropped.** Mitigation: an explicit baseline inventory and contract updates for future named sections; no unbounded generic preservation promise.
+- **Active and archived paths could drift.** Mitigation: one typed projector and shared contract tests.
+
+## Migration Plan
+
+- Ship as an additive option with no persisted configuration.
+- Existing invocations and documented full-v1 parsers continue using the unchanged full report.
+- New callers opt in and parse `report.kind: "validation-findings"` plus `itemFindings`.
+- A rollback removes the option without migrating data or restoring files.

openspec/changes/add-validation-findings-report/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+Bulk validation currently prints one result for every item in scope, including clean items. That complete report is useful for audit and automation, but it can dominate agent context and CI logs in large, mostly-clean repositories. In one real 895-change archive, the complete JSON report was 157,396 bytes while a feasibility candidate's projected-v1 envelope was 6,740 bytes (95.7% smaller) with all 19 failures and the same exit status. The proposed envelope is different and may have a slightly different byte count; savings vary with issue density. This is evidence about output volume, not validation runtime.
+
+## What Changes
+
+- Add an opt-in `--report <full|findings>` mode to explicit bulk validation scopes: `--all`, `--changes`, `--specs`, and `--archived`.
+- Keep current behavior when `--report` is omitted, and preserve current human and JSON output for valid explicit bulk `--report full` requests.
+- In findings mode, project complete item records whose `issues.length > 0` into `itemFindings`, preserving full-report order, every issue severity, and all current or future additive item fields.
+- Give JSON findings an exact `report.kind: "validation-findings"` discriminator and exact JSON-string `report.version: "1.0"`. It does not reuse the full-v1 `items` field or claim conformance with that document.
+- Use the current full-result inventory (`items`, `summary`, `version`, and `root`); there are no top-level advisory collections to project. Future advisory sections require an explicit contract decision.
+- Require an explicit, non-conflicting bulk scope for either report value. Parsed invalid report requests return one stable structured JSON diagnostic before root selection, prompts, spinners, or validation. Missing option arguments retain existing CLI parser errors; root and discovery failures retain existing command diagnostics.
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `cli-validate`: Add a compatibility-safe, opt-in findings report for bulk human and JSON validation output.
+
+## Impact
+
+- **Public CLI:** one additive report option on bulk `openspec validate`; no default behavior change.
+- **JSON consumers:** the existing full-v1 complete-`items` document remains unchanged. Consumers choosing findings mode parse a separately identified schema with `itemFindings`.
+- **Documentation and completions:** document the two report modes, their scope rules, and the findings JSON envelope; register `--report` on the existing Bash, Zsh, Fish, and PowerShell completion surfaces, with fixed `full`/`findings` value suggestions only in Zsh and Fish.
+- **Implementation:** validation command output, CLI option registration, completions, documentation, focused tests, and a release changeset. No new dependency or project-level preference.

openspec/changes/add-validation-findings-report/specs/cli-validate/spec.md

@@ -0,0 +1,260 @@
+## ADDED Requirements
+
+### Requirement: Bulk validation SHALL provide an opt-in item-findings report
+
+The `validate` command SHALL support case-sensitive `--report full` and `--report findings` for explicit, unambiguous bulk scopes. Omitting `--report` SHALL retain current targeted, interactive, bulk, human, and JSON behavior. Findings mode SHALL return whole issue-bearing item records separately from top-level advisories while preserving full item order, complete requested-scope totals, root selection, issue severities, strict-mode semantics, and exit status. The current full-result fields are `items`, `summary`, `version`, and `root`; this implementation SHALL NOT invent advisory fields or copy unknown top-level fields. A future advisory section requires an explicit contract update.
+
+#### Scenario: Default and explicit bulk full output remain compatible
+
+- **WHEN** a user runs bulk validation without `--report` or with a valid explicit `--report full` request
+- **THEN** human output SHALL retain the current complete item listing and totals, or the current empty-scope message when no items exist
+- **AND** JSON output SHALL retain the documented full-v1 top-level `version: "1.0"` and complete `items` collection
+- **AND** the two bulk invocations SHALL have equivalent observable output and exit status for the same scope
+
+#### Scenario: Explicit report values select a bulk report
+
+- **WHEN** a user supplies `--report full` or `--report findings` with exactly one resolvable bulk scope and no item name
+- **THEN** validation SHALL run that bulk report without prompting for a scope
+
+#### Scenario: Explicit report values do not alias targeted or interactive flows
+
+- **WHEN** a user supplies an explicit report value with an item name or without a bulk scope
+- **THEN** validation SHALL reject the request rather than treating explicit `full` as a targeted or interactive alias
+
+#### Scenario: A changes-only report retains changes scope
+
+- **WHEN** a findings report request uses `--changes` alone
+- **THEN** `report.scope` SHALL be `changes`
+
+#### Scenario: A specs-only report retains specs scope
+
+- **WHEN** a findings report request uses `--specs` alone
+- **THEN** `report.scope` SHALL be `specs`
+
+#### Scenario: Combined active scopes normalize to all
+
+- **WHEN** a findings report request uses `--changes --specs`, `--all`, or `--all` with either active subset flag
+- **THEN** the complete active scope SHALL be validated and `report.scope` SHALL be `all`
+
+#### Scenario: Archived and active scopes cannot be combined for a report
+
+- **WHEN** a user supplies `--archived` with `--all`, `--changes`, or `--specs` and an explicit report value
+- **THEN** validation SHALL reject the request rather than choosing one scope by precedence
+- **AND** SHALL NOT validate either scope
+
+#### Scenario: Invalid human report requests fail before work
+
+- **WHEN** a non-JSON request has an item/report conflict, archived/active conflict, missing bulk scope, or unsupported report value
+- **THEN** validation SHALL write a targeted diagnostic to stderr and nothing to stdout
+- **AND** SHALL exit with code 1
+- **AND** SHALL NOT resolve a root, prompt, render a spinner, or validate any item
+
+#### Scenario: Invalid JSON report requests return one stable diagnostic
+
+- **WHEN** a JSON request has an item/report conflict, archived/active conflict, missing bulk scope, or unsupported report value
+- **THEN** stdout SHALL contain exactly one JSON document with exactly one `status` entry
+- **AND** that entry SHALL have `severity: "error"` and stable `code: "invalid_validation_report_request"`
+- **AND** it SHALL include a targeted `message` and corrective `fix`
+- **AND** no human text SHALL be written to stdout or stderr
+- **AND** validation SHALL exit with code 1 without resolving a root, prompting, rendering a spinner, or validating any item
+
+#### Scenario: Missing report arguments retain parser errors
+
+- **WHEN** the CLI parser rejects a missing required argument such as bare `--report`
+- **THEN** the existing CLI syntax-error behavior SHALL remain unchanged
+- **AND** the command SHALL NOT run or resolve a root
+- **AND** generic parser errors SHALL NOT be covered by the structured `invalid_validation_report_request` contract
+
+#### Scenario: Root and scope-discovery failures remain diagnostics
+
+- **GIVEN** a syntactically valid report request with a supported scope
+- **WHEN** root resolution fails or scope discovery encounters a fatal error
+- **THEN** validation SHALL retain the existing diagnostic and nonzero exit status for that failure
+- **AND** JSON output SHALL contain the existing `status` diagnostic envelope rather than a findings document with empty totals
+- **AND** a per-item validation failure SHALL instead remain an item result in the completed findings report
+
+#### Scenario: Findings JSON uses an exact distinct contract
+
+- **WHEN** a valid `--json --report findings` request completes root resolution, scope discovery, and validation
+- **THEN** stdout SHALL contain exactly one parseable JSON document and stderr SHALL be empty
+- **AND** `report.kind` SHALL equal `validation-findings`
+- **AND** `report.version` SHALL be the JSON string `"1.0"`
+- **AND** `report` SHALL include canonical `scope`, `returnedItems`, and `totalItems`
+- **AND** `summary` SHALL contain totals for the complete requested scope
+- **AND** `root` SHALL retain the current resolved-root envelope
+
+#### Scenario: Findings JSON is not the documented full-v1 document
+
+- **WHEN** a valid `--json --report findings` request produces a completed report
+- **THEN** the document SHALL NOT contain a top-level `items` field
+- **AND** SHALL NOT contain the full-v1 top-level `version` field
+- **AND** contract tests SHALL reject it against the documented full-v1 shape requiring top-level `version: "1.0"` and complete `items`
+- **AND** compatibility assertions SHALL be limited to documented full-v1 conformance, leaving undocumented permissive parser behavior outside this contract
+
+#### Scenario: Item findings project whole issue-bearing records
+
+- **GIVEN** the corresponding full result has item records in a defined order
+- **WHEN** findings JSON is produced
+- **THEN** `itemFindings` SHALL equal those full item records filtered by `issues.length > 0`
+- **AND** record order and issue order SHALL match the full result
+- **AND** each selected record SHALL preserve every current field and future additive field from that full item record
+- **AND** clean item records SHALL be omitted
+
+#### Scenario: Every item issue severity counts as an item finding
+
+- **GIVEN** separate item records containing only `ERROR`, only `WARNING`, or only `INFO` issues
+- **WHEN** findings mode is produced
+- **THEN** all three records SHALL appear in `itemFindings`
+- **AND** every issue SHALL retain its original severity, path, and message
+- **AND** `valid` and exit behavior SHALL remain whatever full mode reports under the same strictness
+
+#### Scenario: Item counts exclude top-level advisories
+
+- **WHEN** findings JSON is produced
+- **THEN** `report.returnedItems` SHALL equal `itemFindings.length`
+- **AND** `report.totalItems` SHALL equal `summary.totals.items`
+- **AND** separately named top-level advisory records SHALL NOT increase either item count
+
+#### Scenario: Zero item findings in a non-empty scope remain auditable
+
+- **GIVEN** the requested bulk scope contains one or more items and none has an issue
+- **WHEN** validation runs with `--json --report findings`
+- **THEN** `itemFindings` SHALL be an empty array and `report.returnedItems` SHALL be `0`
+- **AND** `report.totalItems`, `report.scope`, `summary`, and `root` SHALL still identify the complete validated scope
+- **AND** the successful exit status SHALL match full mode for the same scope
+
+#### Scenario: Empty JSON scope is explicit and successful
+
+- **GIVEN** the selected bulk scope contains no items
+- **WHEN** validation runs with `--json --report findings`
+- **THEN** `itemFindings` SHALL be empty, item counts and summary totals SHALL be zero, and scope and root SHALL remain explicit
+- **AND** validation SHALL preserve the current successful empty-scope exit status
+
+#### Scenario: Human findings use independently ordered streams
+
+- **GIVEN** a bulk scope with issue-bearing and clean item records
+- **WHEN** validation runs with `--report findings` and without `--json`
+- **THEN** within stdout the final report SHALL emit `Scope:` first, followed by complete-scope `Totals:`, followed by any existing active-scope first-failure `Details:` command
+- **AND** within stderr the final report SHALL emit item-finding blocks in full item order, with each item heading followed by all issues in issue order
+- **AND** `ERROR`, `WARNING`, and `INFO` labels, paths, and messages SHALL all be emitted to stderr
+- **AND** clean item rows SHALL be omitted
+- **AND** within stderr any explicitly named advisory section SHALL be emitted after item-finding blocks
+- **AND** archived scope SHALL NOT gain a new details command
+- **AND** no relative ordering between stdout and stderr sections SHALL be required
+
+#### Scenario: Human output distinguishes no item findings from advisories
+
+- **GIVEN** no item record has an issue
+- **WHEN** validation runs with `--report findings` and without `--json`
+- **THEN** within stdout `No item findings.` SHALL be emitted after `Scope:` and before `Totals:`
+- **AND** any explicitly named advisory section SHALL still be emitted separately to stderr
+- **AND** `No item findings.` SHALL NOT assert that no top-level advisory exists
+- **AND** no relative ordering between that stderr advisory and stdout sections SHALL be required
+
+#### Scenario: Human empty scope is explicit and successful
+
+- **GIVEN** the selected bulk scope contains no items
+- **WHEN** validation runs with `--report findings` and without `--json`
+- **THEN** within stdout the report SHALL contain zero-item `Scope:`, `No item findings.`, and zero `Totals:` in that order
+- **AND** validation SHALL preserve the current successful empty-scope exit status
+
+#### Scenario: Full and findings verdicts remain equal
+
+- **GIVEN** the same bulk scope, root, inputs, and strictness
+- **WHEN** full mode and findings mode run
+- **THEN** both modes SHALL validate the same items
+- **AND** SHALL produce the same complete summary totals and exit status
+- **AND** store and archived scopes SHALL inspect exactly the items their corresponding full invocations inspect
+
+#### Scenario: Completion support follows existing shell capabilities
+
+- **WHEN** completion output is generated for the currently supported Bash, Zsh, Fish, and PowerShell surfaces
+- **THEN** the `--report` flag SHALL be registered on all four surfaces
+- **AND** Zsh and Fish SHALL suggest the fixed values `full` and `findings`
+- **AND** Bash and PowerShell SHALL remain unchanged beyond registering the flag and SHALL NOT be required to suggest fixed values
+- **AND** this change SHALL NOT add another completion generator or completion capability
+
+#### Scenario: Findings output is cross-platform
+
+- **WHEN** the same findings validation scenario runs on Windows, macOS, and Linux
+- **THEN** report selection, projection, totals, severities, streams, and exit status SHALL be equivalent
+- **AND** paths in item records and the root envelope SHALL remain exactly as emitted by full validation, including native root paths and existing POSIX-normalized issue paths
+
+## MODIFIED Requirements
+
+### Requirement: Bulk and filtered validation
+
+The validate command SHALL support flags for bulk validation (--all) and filtered validation by type (--changes, --specs). These flags SHALL select the same items for full and findings reports. Complete per-item listings SHALL apply when `--report` is omitted or is `full`; findings output SHALL follow the item-findings report contract.
+
+#### Scenario: Validate everything
+
+- **WHEN** executing `openspec validate --all`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** validate all specs in openspec/specs/
+- **AND** display a summary showing passed/failed items
+- **AND** exit with code 1 if any validation fails
+
+#### Scenario: Scope of bulk validation
+
+- **WHEN** validating with `--all` or `--changes`
+- **THEN** include all change proposals under `openspec/changes/`
+- **AND** exclude the `openspec/changes/archive/` directory
+
+- **WHEN** validating with `--specs`
+- **THEN** include all specs that have a `spec.md` under `openspec/specs/<capability-path>/spec.md`
+
+#### Scenario: Validate all changes
+
+- **WHEN** executing `openspec validate --changes` with `--report` omitted or set to `full`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** display results for each change
+- **AND** show summary statistics
+
+#### Scenario: Validate all specs
+
+- **WHEN** executing `openspec validate --specs` with `--report` omitted or set to `full`
+- **THEN** validate all specs in openspec/specs/
+- **AND** display results for each spec
+- **AND** show summary statistics
+
+### Requirement: Validation options and progress indication
+
+The validate command SHALL support standard validation options (--strict, --json) and display progress during bulk operations. Explicit bulk reports SHALL use `--report full` or `--report findings`, independently of JSON serialization. The complete JSON schema below SHALL apply when `--report` is omitted or is `full`; findings output SHALL follow the distinct item-findings report contract.
+
+#### Scenario: Strict validation
+
+- **WHEN** executing `openspec validate --all --strict`
+- **THEN** apply strict validation to all items
+- **AND** treat warnings as errors
+- **AND** fail if any item has warnings or errors
+
+#### Scenario: JSON output
+
+- **WHEN** executing `openspec validate --all --json` with `--report` omitted or set to `full`
+- **THEN** output validation results as JSON
+- **AND** include detailed issues for each item
+- **AND** include summary statistics
+
+#### Scenario: JSON output schema for bulk validation
+
+- **WHEN** executing `openspec validate --all --json` (or `--changes` / `--specs`) with `--report` omitted or set to `full`
+- **THEN** output a JSON object with the following shape:
+  - `items`: Array of objects with fields `{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }`
+  - `summary`: Object `{ totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }`
+  - `version`: String identifier for the schema (e.g., `"1.0"`)
+- **AND** exit with code 1 if any `items[].valid === false`
+
+Where `Issue` follows the existing per-item validation report shape `{ level: "ERROR"|"WARNING"|"INFO", path: string, message: string }`.
+
+#### Scenario: Show validation progress
+
+- **WHEN** validating multiple items (--all, --changes, or --specs)
+- **THEN** show progress indicator or status updates
+- **AND** indicate which item is currently being validated
+- **AND** display running count of passed/failed items
+
+#### Scenario: Concurrency limits for performance
+
+- **WHEN** validating multiple items
+- **THEN** run validations with a bounded concurrency (e.g., 4–8 in parallel)
+- **AND** ensure progress indicators remain responsive

openspec/changes/add-validation-findings-report/tasks.md

@@ -0,0 +1,42 @@
+## 1. Request and scope contract
+
+- [x] 1.1 Add `--report <full|findings>` to bulk `validate` help and registration, leave omitted-report behavior unchanged, and verify explicit `--report full` and `--report findings` require a bulk scope without an item name
+- [x] 1.2 Implement one typed request normalizer before root resolution that maps `--changes` to `changes`, `--specs` to `specs`, `--changes --specs` and `--all` plus active subsets to `all`, and `--archived` to `archived`; verify archived+active, item+report, missing-scope, and unsupported-value requests are rejected before validation
+- [x] 1.3 Emit invalid human requests only to stderr and invalid JSON requests as one stdout document with one `status` entry and stable code `invalid_validation_report_request`; verify exit 1, empty opposite streams, and absence of root resolution, prompts, spinners, and validator calls
+- [x] 1.4 Register the `--report` flag on the existing Bash, Zsh, Fish, and PowerShell completion outputs; add fixed `full`/`findings` value suggestions only to Zsh and Fish, leave Bash and PowerShell unchanged beyond flag registration, and verify no completion capability or generator is added
+- [x] 1.5 Verify case-sensitive report values, preserve parser errors for missing option arguments, and preserve root/discovery failure diagnostics without emitting a findings success envelope
+
+## 2. Shared item projection and renderers
+
+- [x] 2.1 Define one typed projector used by active and archived validation that derives `itemFindings` with `full.items.filter(item => item.issues.length > 0)`, preserving full item order, issue order, and whole item records including additive fields; verify both paths use it rather than filtering independently
+- [x] 2.2 Produce the exact findings JSON contract with `report.kind: "validation-findings"`, JSON-string `report.version: "1.0"`, scope/item counts, `itemFindings`, complete `summary`, and `root`; omit full-v1 top-level `items` and `version`
+- [x] 2.3 Implement human findings with independently ordered streams: stdout `Scope:` -> optional `No item findings.` -> `Totals:` -> existing active `Details:`; stderr item blocks/all severities -> explicitly named advisories; add tests that capture each stream independently and make no merged stdout/stderr ordering assertion
+- [x] 2.4 Preserve full-scope validation work, totals, root, strictness, and exit status in findings mode, and verify ERROR-, WARNING-, INFO-only, no-item-finding, empty-scope, failure, active, archived, and selected-store cases
+
+## 3. Baseline and compatibility gate
+
+- [x] 3.1 Update from main before implementation and verify the full-result inventory is exactly `items`, `summary`, `version`, and `root`; explicitly map those fields without copying unknown top-level fields
+- [x] 3.2 Verify existing INFO-bearing full item records appear unchanged in `itemFindings`, and no advisory field is invented when the full report has none
+- [x] 3.3 Add human-byte and normalized-JSON compatibility tests proving omitted `--report` and explicit bulk `--report full` preserve current output for active, spec, archived, empty, and selected-store scopes while ignoring expected timing-field variation between runs
+- [x] 3.4 Add contract tests proving `report.version` is exactly the JSON string `"1.0"` and findings output does not conform to the documented full-v1 shape requiring top-level `version: "1.0"` and complete `items`; do not assert failure behavior for arbitrary undocumented parsers
+
+## 4. Documentation and release tracking
+
+- [x] 4.1 Document report-versus-serialization semantics, canonical/invalid scope combinations, independent within-stream human section ordering, the exact findings JSON and invalid-request JSON documents, item/advisory distinction, exit codes, and the unchanged full-v1 contract
+- [x] 4.2 Document external `jq` and PowerShell filtering as compatible alternatives for existing releases and explain that findings mode reduces emitted output but does not claim faster validation
+- [x] 4.3 Add the appropriate release changeset for the implemented feature and verify release tracking passes
+
+## 5. Verification
+
+- [x] 5.1 Run focused validate command, archived validation, completion, store-root, structured-error, and CLI end-to-end tests and verify all pass
+- [x] 5.2 Run build, full tests, TypeScript checks, lint, and `git diff --check`, and verify all repository checks pass
+- [x] 5.3 Run `openspec validate add-validation-findings-report --strict` and reconcile implementation and documentation against every scenario before marking the change complete
+- [x] 5.4 Measure the available repository archive (a replacement for the unavailable original 895-change corpus) against the implemented `itemFindings` envelope, verify default/full compatibility and complete item findings/totals/exit status, and report the new bytes separately from the 6,740-byte feasibility candidate without a runtime claim
+
+## Verification results
+
+- Build, TypeScript checks, lint, strict validation of this change, release tracking, and `git diff --check` pass.
+- Full suite: 148 files and 4,273 tests pass. The build completed before the run. Local verification used a temporary `USERPROFILE`, unset inherited `ZSH`/`ZSH_CUSTOM`, and allowed localhost HTTP fixtures; the original environment-sensitive failures reproduced on unchanged main.
+- The 83-change archive measurement retains all 12 failures, full totals, root, and exit 1 while reducing JSON output by 72.5%. See `design.md` for the measured bytes and corpus distinction.
+- Independent implementation review found no remaining blockers.
+- Documentation examples were checked against the built CLI. The Bash/jq alternatives were executed. PowerShell examples were source-reviewed only because `pwsh` is unavailable locally; rendered docs QA was unavailable because no browser was connected.

openspec/changes/fix-archive-retirement-guidance/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-19

openspec/changes/fix-archive-retirement-guidance/proposal.md

@@ -0,0 +1,51 @@
+# Never dead-end a capability retirement
+
+## Why
+
+A change whose delta removes the last requirement a capability has rebuilds the
+main spec empty, and an empty spec can never validate. Retirement is what
+archive does instead, and because it deletes a file it has to be asked for: the
+change declares `retire_capabilities: true`. The abort names that marker when it
+is the single thing missing.
+
+Retirement is also refused while the spec holds any non-blank line the merge
+cannot name — a `## Notes` section, a comment under a requirement. Both are
+ordinary things to find in a hand-written spec. When the marker was missing *and*
+such a line was present, neither hint fired: the marker hint was suppressed
+because adding it would not have let the archive through, and the hint that names
+those lines only spoke to authors who had already declared the marker.
+
+The archive then aborted on a bare "Spec must have at least one requirement" with
+no guidance at all — the dead end the marker exists to close, still reachable
+(#1696, worked around there with `--skip-specs` plus a hand-applied sync).
+
+## What Changes
+
+- When this run emptied the capability, the marker is absent, and the spec holds
+  content the merge cannot account for, the abort names that content and says
+  what archive would otherwise do with the spec.
+- It still does not name the marker in that case. The marker is named only when
+  adding it would really let the archive through; a spec with a second
+  `## Requirements` section holding a live requirement must not be pointed toward
+  a deletion. Once the content is resolved, the rerun names the marker.
+- A marker that is present but cannot be honored is reported alongside the
+  blocking content. An author who wrote `retire_capabilities: yes-please`
+  believes they authorised the deletion; making them clear the content first,
+  only to then learn the marker was never read, is two aborts for one mistake.
+- The blocking lines are authored file content printed to a terminal, so they are
+  rendered with control characters replaced and their length bounded — the same
+  treatment a change directory name already gets. This also hardens the
+  marker-declared refusal, which echoed them verbatim.
+- The marker's own reason gets the same treatment, at its source in
+  `readBooleanMarker`, because every reason quotes something the author wrote —
+  a schema name, a parser message carrying one, a filesystem error carrying a
+  path. Fixing it there covers `openspec validate`, which prints the same reason.
+
+No change to what archive writes, deletes, or refuses. Message paths only.
+
+## Impact
+
+- Affected specs: `cli-archive` (MODIFIED: Capability Retirement)
+- Affected code: `src/core/archive.ts`, `src/utils/change-metadata.ts`
+- Affected docs: `docs/writing-specs.md` (states the second refusal condition,
+  which was true before this change but undocumented)

openspec/changes/fix-archive-retirement-guidance/specs/cli-archive/spec.md

@@ -0,0 +1,67 @@
+## MODIFIED Requirements
+
+### Requirement: Capability Retirement
+
+A delta whose REMOVED entries cover every requirement a capability has SHALL retire that capability instead of writing a main spec with no requirements, which can never pass validation.
+
+#### Scenario: Deciding that a rebuilt spec cannot be written
+
+- **WHEN** applying a delta leaves the rebuilt spec with no requirement blocks, and every other nonblank line in the whole file is accounted for as the title, Purpose, Requirements header, or a canonical requirement's statement, scenarios, or fenced examples
+- **THEN** put that rebuilt spec to the spec validator
+- **AND** treat it as retirable only when its sole validation error is that the spec has no requirements
+- **AND** otherwise write or reject it exactly as any other rebuilt spec, so a spec the validator still accepts, one broken in some further way, and one still holding a `###` heading are all left alone
+
+#### Scenario: Validation was skipped
+
+- **WHEN** the archive runs with validation disabled
+- **THEN** retire nothing, because no verdict was produced to justify a deletion
+- **AND** write the rebuilt spec exactly as an archive without this behavior would
+
+#### Scenario: Retirement is not declared
+
+- **WHEN** a rebuilt spec is retirable but the change does not declare `retire_capabilities: true` in its metadata, or declares it in metadata that cannot be honored
+- **THEN** write the spec as any other, so the archive aborts on it exactly as it did before this behavior existed
+- **AND** name the marker as the fix in that abort, and say when a marker that is present cannot be honored, with control characters replaced in the reason because it repeats what the author wrote
+- **AND** say nothing about adding the marker when retiring would not have made the spec writable anyway, while still reporting a marker that is present but cannot be honored
+
+#### Scenario: Delta removes the capability's last requirement
+
+- **WHEN** a retirable rebuilt spec belongs to a capability whose main spec exists
+- **AND** at least one requirement was actually removed by this run
+- **AND** the change declares `retire_capabilities: true`
+- **THEN** delete the capability's `spec.md` instead of writing it
+- **AND** refuse to delete when the target resolves outside the real specs root
+- **AND** delete any in-root directory the deletion leaves empty, and never the specs root itself
+- **AND** count every operation the delta applied in the archive totals
+- **AND** record the retirement in the archive warnings, naming what the deleted file held and giving a pasteable Git recovery command only when the spec lived in the caller's checkout
+
+#### Scenario: Retirement is deferred until every spec is written
+
+- **WHEN** an archive both retires one capability and updates another
+- **THEN** settle the archive destination before touching any spec, so a name collision cannot strand a retirement
+- **AND** perform the deletion only after every spec write has succeeded
+- **AND** report a destination claimed while the merge ran as the same collision, rather than as a raw filesystem error
+
+#### Scenario: Capability directory holds other files
+
+- **WHEN** retiring a capability whose directory still holds other files after `spec.md` is deleted
+- **THEN** leave that directory in place
+
+#### Scenario: Removal was already synced
+
+- **WHEN** a retirable rebuilt spec removed nothing this run and its main spec exists
+- **THEN** leave the file untouched
+- **AND** abort the archive with the validation error, as for any other unwritable spec, unless validation was skipped
+
+#### Scenario: Content the merge cannot account for
+
+- **WHEN** the spec holds any non-blank line the merge cannot name - anywhere in the file, including above the requirements section and inside a requirement block, where content the parser did not read as a new header rides along
+- **THEN** refuse the retirement, because deleting the file would take that content with it
+- **AND** say which lines stood in the way whether or not the change declared the marker, rather than aborting on the bare validation error
+- **AND** name the marker only when adding it would let the archive through, so an author whose spec still holds such content is pointed at that content first
+- **AND** render those lines with control characters replaced and their length bounded, because a spec that redraws the terminal or fills the screen would take the way out of the abort with it
+
+#### Scenario: Main spec is already gone
+
+- **WHEN** a REMOVED-only delta targets a capability that has no main spec, and the change declares `retire_capabilities: true`
+- **THEN** complete the archive without creating or retiring one

openspec/changes/fix-archive-retirement-guidance/tasks.md

@@ -0,0 +1,13 @@
+# Tasks
+
+## 1. Name the blocking content when the marker is absent
+- [x] 1.1 Derive "this run emptied the capability" once, and hint on it in both the marker-missing and content-blocked cases
+- [x] 1.2 Keep the marker unnamed while content still blocks the retirement, while still reporting one that cannot be honored
+
+## 2. Render the blocking lines safely
+- [x] 2.1 Replace control characters and bound each line, sharing one helper with the marker-declared refusal
+- [x] 2.2 Sanitize the marker's own reason at its source, so `validate` is covered too
+- [x] 2.3 Cover the human abort, the `--json` detail, and the rendering with tests
+
+## 3. Record the behavior
+- [x] 3.1 Update the `cli-archive` spec delta and `docs/writing-specs.md`

openspec/changes/fix-schemas-root-selection/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-09

openspec/changes/fix-schemas-root-selection/design.md

@@ -0,0 +1,79 @@
+## Context
+
+See `proposal.md` for motivation and `specs/schema-resolution/spec.md` for the behavioral contract.
+
+The pre-fix CLI has two already-compatible pieces that are not connected:
+
+- `schemasCommand()` passes `process.cwd()` directly to `listSchemasWithInfo()`.
+- `listSchemasWithInfo(projectRoot)` already lists the correct project-local, user, and package schemas when given an authoritative project root.
+- Normal root-scoped commands already call `resolveRootForCommand()`, which implements explicit store, nearest root, local `store:` pointer, global `defaultStore`, rootless fallback, canonicalization, and shared diagnostics.
+
+The mismatch was reproduced against the built CLI with distinct `local-only` and `store-only` schemas. From the local project, `schemas --json` returned `local-only` and omitted `store-only`, while `context --json --store team-context` resolved the operation root to the store. The relevant pre-fix test baseline passes (110 tests), so the reproduction is not caused by an existing failing suite.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make schema discovery and schema consumption resolve the same root.
+- Carry explicit store selection through a supported CLI flag.
+- Reuse the canonical root-selection implementation and its diagnostics.
+- Preserve successful schema-list output compatibility and cross-platform path handling.
+
+**Non-Goals:**
+
+- Change schema resolution precedence within a resolved root.
+- Change schema descriptions, semantic selection policy, or workflow-specific behavior beyond correcting stale `schemas --store` guidance.
+- Add a raw filesystem-root flag or expose a resolved path in successful JSON output.
+- Modify `context`, `templates`, change creation, or the root resolver itself.
+- Refactor the existing `propose` compatibility sequence; only its stale flag-support claim changes.
+
+## Decisions
+
+### 1. Resolve the root at the CLI command boundary
+
+`schemasCommand()` will accept the standard store selector fields and call `resolveRootForCommand()` before invoking `listSchemasWithInfo(root.path)`. This is the same boundary used by `status` and other root-scoped workflow commands.
+
+Resolving inside `listSchemasWithInfo()` was rejected because that function is also a programmatic API with intentional backward-compatible behavior when `projectRoot` is omitted. Root selection is a CLI/session concern; schema enumeration should remain a pure operation over the root it receives.
+
+### 2. Add the standard store option and rejection path
+
+The Commander registration for `schemas` will add `--store <id>` using `COMMON_FLAGS.store` and the shared hidden `--store-path` option. `SchemasOptions` will carry `store` and `storePath`, and command-completion metadata will add the same common store flag. Because the repository enforces that every command exposing `--store` is named by the shared store-selection guidance, that shared command list, committed generated skill snapshots, and generated-content parity hashes will be updated to include `schemas`. Formal CLI/JSON agent-contract references will be synchronized, and the existing `propose` compatibility flow will only lose its now-false assertion that `schemas` cannot accept the flag; its root-resolution sequence remains unchanged.
+
+A raw `--root` or `--cwd` flag was rejected because it would bypass registry validation, store identity checks, canonicalization, and existing diagnostics. Asking an Agent to run `cd <root.path> && openspec schemas` was rejected because generated tool permissions and working-directory support differ across Agents.
+
+### 3. Preserve canonical root precedence without a schemas-specific fallback
+
+The command will use `resolveRootForCommand()` unchanged:
+
+1. Explicit `--store`.
+2. Nearest OpenSpec root, including resolution of a config-only `store:` pointer.
+3. Global `defaultStore` when no nearer root exists.
+4. An implicit current-directory root only when no root or registered-store selection is available.
+
+Invalid pointers, stale defaults, unknown stores, and the presence of unselected registered stores remain fail-closed. Adding a schemas-only catch-and-fallback path was rejected because it would recreate the mismatch this change removes.
+
+### 4. Preserve success output; use the existing JSON failure contract
+
+Successful human output remains the current listing, and successful JSON remains the top-level schema array. No root metadata is added, avoiding a breaking output-shape change.
+
+When root resolution fails under `--json`, the existing command adapter will emit one machine-readable failure document with an empty schema list, null root, and the shared status diagnostic. Human mode keeps the standard root banner and error/fix presentation used by other commands.
+
+### 5. Test the user-visible command, not an implementation mock
+
+A focused CLI suite will construct real temporary roots and registered stores with distinct valid project-local schemas. It will exercise explicit store selection, local pointers, global defaults, nearest-root precedence, rootless compatibility, fail-closed errors, paths with spaces, and the hidden removed option. Completion metadata gets a focused registry assertion.
+
+The tests will use Node path utilities and canonical fixture helpers, following `test/AGENTS.md`; no path identity assertion will compare non-canonical spellings.
+
+## Risks / Trade-offs
+
+- **Users with registered stores but no selected root can no longer use `schemas` as an unscoped built-in-only listing.** → Return the same actionable selection diagnostic as other root-scoped commands; selecting a store or entering a root makes the result authoritative.
+- **Adding root resolution introduces new JSON failure paths.** → Assert one-document failure output and non-zero exit behavior explicitly.
+- **Store roots containing spaces or platform-specific separators could expose path assumptions.** → Resolve paths internally and add a real CLI fixture with a spaced store path; never compose a shell command.
+- **The feature PR still needs to integrate its schema-selection flow with explicit store choice.** → This fix synchronizes shared guidance and the existing `propose` compatibility wording, but leaves feature-specific selection/confirmation behavior to that branch after this independent CLI fix merges.
+
+## Migration Plan
+
+1. Ship the root-aware `schemas` command and `--store` option.
+2. Update dependent feature-specific schema-selection guidance in its own branch; the shared store-capable command list and existing `propose` compatibility wording already support `schemas --store` after this fix.
+3. Existing successful unscoped output remains compatible; scripts targeting a registered store should add `--store <id>`.
+4. Rollback removes the option and returns `schemasCommand()` to `process.cwd()` without changing schema files or registered-store state.

openspec/changes/fix-schemas-root-selection/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+`openspec schemas` discovers project-local schemas from the shell's current directory, while commands that consume a schema resolve an authoritative OpenSpec root first. When an explicit store, a local `store:` pointer, or `defaultStore` selects a different root, discovery can recommend a schema that is unavailable where the change will actually be created. Agents currently have to work around this mismatch by resolving a path and trying to change their shell working directory, which is not reliable across supported tools.
+
+## What Changes
+
+- Make `openspec schemas` resolve its project root through the same root-selection contract used by normal OpenSpec commands before listing schemas.
+- Add `--store <id>` to `openspec schemas`, including the standard hidden `--store-path` rejection path, so explicit store selection is carried directly by the CLI.
+- Honor nearest roots, local `store:` pointers, and global `defaultStore` using existing precedence and diagnostics; do not add a parallel schema-specific root resolver.
+- Preserve the successful human and JSON schema-list output shapes and the existing rootless fallback when no root or registered store exists.
+- Add CLI regression coverage for explicit stores, declared pointers, global defaults, nearest-root precedence, error handling, and completion metadata.
+- Update the shared store-capable command guidance, committed generated skill snapshots, and generated-content parity hashes to name `schemas`, plus the formal CLI and JSON agent-contract references; preserve the existing `propose` compatibility flow while removing its now-false claim that `schemas` cannot accept `--store`.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `schema-resolution`: `openspec schemas` resolves and lists schemas from the authoritative OpenSpec root, including explicitly selected and configured stores.
+
+## Impact
+
+- Affected CLI surface: `openspec schemas [--json] [--store <id>]`.
+- Affected code: workflow schemas command, CLI option registration, command completion metadata, the shared store-capable command list, and directly affected command-contract documentation.
+- Affected tests: a focused schemas command suite plus CLI/completion regression coverage.
+- No schema format, selection policy, workflow-specific flow, or change-creation behavior is modified; the only workflow-specific wording change corrects the stale claim that `schemas` cannot accept `--store`.

openspec/changes/fix-schemas-root-selection/specs/schema-resolution/spec.md

@@ -0,0 +1,80 @@
+## ADDED Requirements
+
+### Requirement: Schemas command SHALL honor authoritative root selection
+
+`openspec schemas` SHALL resolve the authoritative OpenSpec root with the same precedence and diagnostics as other root-scoped commands, then list schemas using that root. The command SHALL accept `--store <id>` for explicit registered-store selection. Successful human output and successful `--json` output SHALL retain their existing formats.
+
+#### Scenario: Nearest project root supplies schemas
+
+- **GIVEN** the current directory is inside an OpenSpec root containing a project-local schema
+- **WHEN** the user runs `openspec schemas --json`
+- **THEN** the result SHALL include that root's project-local schema
+
+#### Scenario: Explicit store overrides the current project
+
+- **GIVEN** the current project and a registered store contain different project-local schemas
+- **WHEN** the user runs `openspec schemas --json --store <id>`
+- **THEN** the result SHALL include schemas from the selected store root
+- **AND** it SHALL NOT include schemas that exist only in the current project
+
+#### Scenario: Local store pointer supplies schemas
+
+- **GIVEN** the nearest `openspec/config.yaml` is a config-only root declaring `store: <id>`
+- **WHEN** the user runs `openspec schemas --json` without an explicit store flag
+- **THEN** the result SHALL include schemas from the declared store root
+
+#### Scenario: Global default store supplies schemas
+
+- **GIVEN** no nearer OpenSpec root or pointer exists
+- **AND** global configuration declares `defaultStore: <id>`
+- **WHEN** the user runs `openspec schemas --json`
+- **THEN** the result SHALL include schemas from the default store root
+
+#### Scenario: Explicit store preserves root-selection precedence
+
+- **GIVEN** a nearest project root, a global default store, and an explicitly selected registered store all exist
+- **WHEN** the user runs `openspec schemas --json --store <id>`
+- **THEN** the explicitly selected store SHALL supply the project-local schemas
+
+#### Scenario: Nearest root precedes the global default
+
+- **GIVEN** a nearest project root and a global default store contain different schemas
+- **WHEN** the user runs `openspec schemas --json` without `--store`
+- **THEN** the nearest project root SHALL supply the project-local schemas
+
+#### Scenario: Rootless listing remains available without registered stores
+
+- **GIVEN** no OpenSpec root, pointer, global default, or registered store exists
+- **WHEN** the user runs `openspec schemas --json`
+- **THEN** the command SHALL list user and package schemas using the current directory as its implicit root, as before
+
+#### Scenario: Registered stores require an authoritative selection
+
+- **GIVEN** no OpenSpec root, pointer, or global default exists
+- **AND** one or more stores are registered
+- **WHEN** the user runs `openspec schemas --json` without `--store`
+- **THEN** the command SHALL fail with the standard root-selection diagnostic that asks the user to select a registered store
+- **AND** it SHALL NOT silently list schemas from the current directory
+
+#### Scenario: Invalid or unavailable store fails closed
+
+- **WHEN** explicit, declared, or global-default store resolution fails
+- **THEN** `openspec schemas` SHALL report the existing root-selection diagnostic and exit non-zero
+- **AND** it SHALL NOT fall back to schemas from the current directory
+
+#### Scenario: Removed store-path option is rejected deliberately
+
+- **WHEN** the user runs `openspec schemas --store-path <path>`
+- **THEN** the command SHALL reject the removed option with the standard instruction to register the store and use `--store <id>`
+
+#### Scenario: Success output remains compatible
+
+- **WHEN** root resolution succeeds
+- **THEN** human output SHALL retain the existing schema listing and source labels
+- **AND** `--json` output SHALL remain the existing top-level array of schema information
+
+#### Scenario: Store path works across supported platforms
+
+- **GIVEN** the selected store root uses a valid platform-native path, including a path containing spaces
+- **WHEN** the user runs `openspec schemas --json --store <id>`
+- **THEN** the command SHALL list schemas from that store without requiring the user or an Agent to compose a shell `cd` command

openspec/changes/fix-schemas-root-selection/tasks.md

@@ -0,0 +1,22 @@
+## 1. Lock the root-selection regression with CLI tests
+
+- [x] 1.1 Add `test/commands/schemas.test.ts` with real temporary local and registered-store roots, valid distinct project schemas, isolated XDG data/config homes, canonical cleanup, and a store path containing spaces.
+- [x] 1.2 Add failing cases proving `schemas --json --store <id>` returns the store-only schema rather than the cwd-only schema, and `schemas --store-path <path>` reaches the deliberate removed-option diagnostic.
+- [x] 1.3 Add failing cases proving config-only `store:` and global `defaultStore` roots supply schemas without a flag, while a nearest real root wins over `defaultStore`.
+- [x] 1.4 Add failing cases for rootless compatibility, unselected registered-store failure, invalid/unavailable store failure, one-document JSON diagnostics, and unchanged successful array output.
+- [x] 1.5 Extend `test/core/completions/command-registry.test.ts` to require the common `store` flag on the `schemas` definition and require the shared store-selection guidance to name it.
+- [x] 1.6 Run `pnpm exec vitest run test/commands/schemas.test.ts test/core/completions/command-registry.test.ts` and verify the new tests fail only because `schemas` lacks authoritative root selection and `--store` support.
+
+## 2. Implement canonical schemas root selection
+
+- [x] 2.1 Extend `SchemasOptions` in `src/commands/workflow/schemas.ts` with `store` and `storePath`, resolve through `resolveRootForCommand()`, return on a JSON resolution failure, and pass `root.path` to `listSchemasWithInfo()`.
+- [x] 2.2 Update the `schemas` registration in `src/cli/index.ts` with `--store <id>`, the shared hidden `--store-path` option, and JSON-aware failure handling without changing successful output shapes.
+- [x] 2.3 Add `COMMON_FLAGS.store` to the `schemas` entry in `src/core/completions/command-registry.ts`, add `schemas` to the shared store-capable command guidance, synchronize committed generated skill snapshots and the formal CLI/JSON agent-contract references, remove the stale `propose` claim without changing its compatibility flow, and refresh generated-content parity hashes.
+- [x] 2.4 Run `pnpm run build`, then rerun `pnpm exec vitest run test/commands/schemas.test.ts test/core/completions/command-registry.test.ts` and verify all root, error, output-compatibility, and completion cases pass.
+
+## 3. Regression and cross-platform verification
+
+- [x] 3.1 Run `pnpm exec vitest run test/cli-e2e/basic.test.ts test/commands/context.test.ts test/commands/global-default-store.test.ts test/core/root-selection.test.ts test/core/artifact-graph/resolver.test.ts` to verify adjacent root and schema behavior.
+- [x] 3.2 Run `pnpm run lint`, `pnpm run build`, and `pnpm test`; confirm no successful `schemas` output regression and no changes outside the scoped CLI, tests, generated guidance/documentation, and proposal files.
+- [x] 3.3 Run `pnpm exec openspec validate fix-schemas-root-selection --strict` and `git diff --check`.
+- [ ] 3.4 Verify the focused schemas suite on Windows CI, specifically the spaced native store path and absence of hard-coded path separators.

openspec/changes/spec-diffs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-15

openspec/changes/spec-diffs/design.md

@@ -0,0 +1,92 @@
+## Context
+
+`openspec show <change>` currently displays the raw proposal markdown (text mode) or a parsed JSON with deltas extracted from the proposal's Capabilities section. Delta spec files under `openspec/changes/<name>/specs/<cap>/spec.md` contain full requirement text including unchanged content copied from the base spec at `openspec/specs/<cap>/spec.md`.
+
+Reviewers need to see *what changed* without manually diffing files. The `--diff` flag adds this capability to the existing show command.
+
+The project currently has no diff dependency. chalk is already available for colorized output.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Let users see per-requirement diffs of delta specs via `openspec show <change> --diff`
+- Support both text (colorized) and JSON output modes
+- Keep the implementation minimal — no changes to storage format, validation, or the archive workflow
+
+**Non-Goals:**
+- Changing the delta spec format to store diffs instead of full text (future work, approach 2 from proposal)
+- Diffing non-spec artifacts (proposal, design, tasks)
+- Providing interactive diff navigation or side-by-side views
+- Git-aware diffing (this compares files on disk)
+
+## Decisions
+
+### 1. Per-requirement diffing, not whole-file
+
+**Choice:** Diff individual requirement blocks, not entire spec files.
+
+The delta spec format already categorizes requirements by operation (`## ADDED`, `## MODIFIED`, `## REMOVED`, `## RENAMED`). Only MODIFIED requirements need a diff — the others are self-explanatory:
+
+- **ADDED** — display the full requirement text (it's all new)
+- **REMOVED** — display the removal notice (Reason/Migration already present)
+- **RENAMED** — display the FROM:/TO: (already present)
+- **MODIFIED** — match by requirement name (`### Requirement: <name>`) against the base spec at `openspec/specs/<cap>/spec.md`, extract both blocks, and compute a unified diff of those blocks
+
+**Rationale:** The existing `ChangeParser` already parses delta specs into individual requirements with operations. The `MarkdownParser` already parses base specs into requirement blocks. We match by the `### Requirement:` header text (the same matching the archive step uses). This gives focused, meaningful output without noise from unchanged requirements.
+
+**Alternative rejected:** Whole-file diff of base spec vs delta spec. This works but shows context from unchanged requirements that were copied verbatim into the delta file, which is exactly the noise the user wants to eliminate.
+
+### 2. Diff library: `diff` (npm)
+
+**Choice:** Use the `diff` npm package (BSD-3-Clause, zero runtime dependencies, about 1 MB unpacked) for the MODIFIED requirement case.
+
+**Alternatives considered:**
+- **Implement from scratch** — Unified diff is well-specified but subtle (context lines, hunk headers). A library avoids bugs and maintenance burden.
+- **Shell out to `diff` command** — Not cross-platform (Windows lacks `diff` by default). Violates the project's cross-platform requirements.
+
+The `diff` package provides `structuredPatch()`, which generates structured unified-diff hunks from two strings. OpenSpec renders those hunks without synthetic file headers.
+
+### 3. Requirement block extraction
+
+**Choice:** Extract raw markdown text for a requirement block from a spec file by:
+1. Finding the `### Requirement: <name>` header line
+2. Collecting all lines until the next `###` header at the same or higher level (or EOF)
+3. Including the header line itself in the extracted block
+
+This reuses `MarkdownParser.extractRequirementsSection()` to limit matching to the requirements section, then scans raw markdown so the diff remains human-readable.
+
+**Matching:** Requirement names are matched exactly after trimming. A case- or interior-whitespace-folded match is used only to produce a useful preview together with a warning, because archive matching is exact. When a MODIFIED requirement follows one or more RENAMED entries, the rename lineage resolves back to the original main-spec name.
+
+### 4. Integration point: `ChangeCommand.show()`
+
+**Choice:** Add diff logic to `ChangeCommand.show()` in `src/commands/change.ts`. When `--diff` is set:
+- Discover delta files with the shared `discoverSpecFiles()` helper and parse each one with `parseDeltaSpec()`
+- In text mode: group output by capability and show each requirement with its operation and, for MODIFIED, the colorized diff
+- In JSON mode: enrich each MODIFIED delta with its available `diff` and `warning` fields
+- Propagate discovery and read failures so an unreadable spec cannot appear as an empty or partial diff
+
+**Alternative:** A separate `openspec diff` command. Rejected because the diff is about *viewing* a change, which is what `show` does. Adding a flag is more discoverable and consistent.
+
+### 5. Diff output format
+
+**Text mode:** Per capability, per requirement:
+- Header: capability name and operation
+- ADDED/REMOVED/RENAMED: display the requirement text as-is (prefixed with operation label)
+- MODIFIED: unified diff of the requirement block, colorized with chalk (green for `+`, red for `-`, dim for headers/context). A textually identical block prints `(no textual changes)`.
+
+**JSON mode:** `--json --diff` extends the existing `--json` output (same `{ id, title, deltaCount, deltas }` structure). A MODIFIED delta receives each diagnostic that applies: `diff`, `warning`, or both. ADDED/REMOVED/RENAMED deltas are unchanged. This is backwards-compatible: consumers that do not request `--diff` receive the existing shape.
+
+### 6. Flag registration
+
+Add `--diff` to:
+- `openspec show` (top-level, passed through as a change-only flag)
+- `openspec change show` (direct)
+
+Add `'diff'` to the `CHANGE_FLAG_KEYS` set in `src/commands/show.ts` so it triggers a warning when used with `--type spec`.
+
+## Risks / Trade-offs
+
+- **\[New dependency\]** Adding `diff` increases the installed package set by about 1 MB unpacked. → It has no runtime dependencies and uses the BSD-3-Clause license. The lockfile and Nix dependency hash pin the package.
+- **\[Requirement name mismatch\]** If a MODIFIED requirement's `### Requirement:` header does not match the base spec exactly, archive will reject it. → Show a folded near-match diff when possible, but retain a warning in both text and JSON output. Otherwise show the full MODIFIED text with a warning.
+- **\[Unreadable input\]** Suppressing a discovery or read error could produce a misleading partial diff. → Propagate all discovery and delta-read errors, and suppress only `ENOENT` when probing for an absent main spec.
+- **\[Path display on Windows\]** Capability names derived from directory names are platform-safe already. Paths used in diff headers should use forward slashes for readability. → Normalize display paths using `.replace(/\\/g, '/')` for display only; use `path.join()` for all filesystem operations.

openspec/changes/spec-diffs/proposal.md

@@ -0,0 +1,51 @@
+## Why
+
+When proposing a change, delta spec files under `openspec/changes/<name>/specs/` duplicate large portions of existing specs in `openspec/specs/`. A MODIFIED requirement must include the entire requirement block (all scenarios), making it hard to see what actually changed versus what was copied verbatim. This friction slows review and increases the risk of errors.
+
+## What Changes
+
+Add a `--diff` flag to `openspec show` (change type) that renders each delta spec as a unified diff against the corresponding main spec in `openspec/specs/`. This is the smallest viable improvement: it doesn't change the storage format or workflow, just adds a new way to view the deltas.
+
+### Approaches considered
+
+Three approaches were evaluated:
+
+1. **Stop storing delta specs; edit main specs on the branch directly.** This would eliminate duplication entirely but conflicts with the spec-driven workflow where changes are proposed, reviewed, and archived as discrete artifacts before the main specs are updated. Deferred — would require rethinking the change lifecycle.
+
+2. **Store deltas as diffs instead of full specs.** The `specs/<cap>/spec.md` files inside a change would contain unified diffs (or a structured delta format) rather than full requirement text. This eliminates duplication at the source but complicates authoring (AI and humans must produce correct diffs), parsing, validation, and the archive/apply step that merges deltas into main specs. Promising for a future change, but high complexity.
+
+3. **Add `openspec show --diff` to render deltas against main specs.** (Chosen.) Leave the storage format unchanged. When displaying a change, compute the diff on the fly by comparing each delta spec file against its matching main spec. This gives reviewers the view they need with minimal code changes and zero workflow disruption.
+
+### What this change delivers
+
+- A `--diff` flag on `openspec show <change>` (and `openspec change show <change>`) that outputs a human-readable unified diff per delta spec
+
+**JSON mode** (`--json --diff`): The existing JSON structure (`{ id, title, deltaCount, deltas }`) is preserved. Only deltas with `operation: "MODIFIED"` include a `"diff"` field containing unified-diff text. Deltas with `operation: "ADDED"`, `"REMOVED"`, or `"RENAMED"` do not include a `"diff"` field (it is absent from the object). When no matching requirement block is found for a MODIFIED delta — no match in the main spec, or no main spec for that capability at all — the delta includes a `"warning"` field (string) instead of `"diff"`, describing the mismatch. A header that matches only after folding case and interior whitespace carries both: the `"diff"` the author meant and a `"warning"` that archive matches names exactly.
+
+**Text mode** (`--diff` without `--json`): The proposal markdown is printed first, followed by a "Specifications Changed (diffs)" section. MODIFIED deltas show colorized unified diffs (additions in green, removals in red); ADDED deltas show the full requirement text as all-additions in green; REMOVED deltas show the authored removal block, Reason and Migration included, in red; RENAMED deltas show old and new names. When a MODIFIED delta has no matching requirement block — or its capability has no main spec — the raw requirement text is printed with a warning instead of a diff. Without `--diff`, `openspec show <change>` prints the proposal and nothing else, exactly as before.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `cli-show`: Add `--diff` flag support for change display, computing unified diffs of delta specs against their main specs
+
+## Non-goals
+
+- Changing the delta spec storage format (approach 2 above — future work)
+- Changing when or how main specs are updated (approach 1 above — future work)
+- Diffing non-spec artifacts (proposal, design, tasks)
+- Git-aware diffing (this compares files on disk, not git history)
+
+## Impact
+
+- `src/commands/show.ts` — pass `--diff` flag through to change display
+- `src/commands/change.ts` — implement diff rendering in `show()` for text and JSON modes
+- `src/cli/index.ts` — register `--diff` option on the show and change show commands
+- `src/utils/requirement-diff.ts` — new: pull one requirement block out of a spec and diff it against the delta block (`diff` package)
+- `src/core/parsers/requirement-blocks.ts` — expose the raw REMOVED blocks so a removal's Reason/Migration text survives into the output
+- `src/core/completions/command-registry.ts` — offer `--diff` in shell completions

openspec/changes/spec-diffs/specs/cli-show/spec.md

@@ -0,0 +1,101 @@
+## MODIFIED Requirements
+
+### Requirement: Output format options
+
+The show command SHALL support various output formats consistent with existing commands.
+
+#### Scenario: JSON output
+
+- **WHEN** executing `openspec show <item> --json`
+- **THEN** output the item in JSON format
+- **AND** include parsed metadata and structure
+- **AND** maintain format consistency with existing change/spec show commands
+
+#### Scenario: Flag scoping and delegation
+
+- **WHEN** showing a change or a spec via the top-level command
+- **THEN** accept common flags such as `--json`
+- **AND** pass through type-specific flags to the corresponding implementation
+  - Change-only flags: `--deltas-only` (alias `--requirements-only` deprecated), `--diff`
+  - Spec-only flags: `--requirements`, `--no-scenarios`, `-r/--requirement`
+- **AND** ignore irrelevant flags for the detected type with a warning
+
+#### Scenario: Text mode change display is unchanged without --diff
+
+- **WHEN** executing `openspec show <change-name>` in text mode without `--diff`
+- **THEN** print the proposal markdown and nothing else, exactly as before `--diff` existed
+
+#### Scenario: Diff output in text mode
+
+- **WHEN** executing `openspec show <change-name> --diff` in text mode (no `--json`)
+- **THEN** display the proposal markdown text
+- **AND** for each delta spec file under `openspec/changes/<change-name>/specs/<cap>/spec.md`, display the parsed deltas grouped by capability
+- **AND** for ADDED requirements, display the full requirement text with a green "ADDED" label
+- **AND** for REMOVED requirements, display the authored removal block, including its Reason and Migration text, with a red "REMOVED" label
+- **AND** for RENAMED requirements, display the FROM:/TO: with a cyan "RENAMED" label
+- **AND** for MODIFIED requirements, extract the matching requirement block from the main spec at `openspec/specs/<cap>/spec.md` by `### Requirement:` header name, compute a unified diff of the main block vs the delta block, and display it colorized (green for `+` lines, red for `-` lines, plain for context lines)
+- **AND** when a MODIFIED requirement's name matches a RENAMED entry's TO name in the same spec, the system SHALL look up the main block using the RENAMED entry's FROM name instead
+- **AND** when multiple RENAMED entries form a chain, the system SHALL resolve the MODIFIED name back to the original main requirement
+- **AND** when a MODIFIED requirement's header matches a main requirement only after folding case and interior whitespace, display the diff together with a warning that archive matches names exactly
+- **AND** if a MODIFIED requirement has no matching main requirement (and no corresponding RENAMED entry), display the full text with a warning
+- **AND** if the capability has no main spec at all, display the full text with a warning naming the missing spec, rather than rendering the requirement as an addition
+- **AND** if the MODIFIED block is textually identical to the matching main block, display `(no textual changes)`
+
+#### Scenario: Diff output in JSON mode
+
+- **WHEN** executing `openspec show <change-name> --json --diff`
+- **THEN** the output SHALL use the same JSON structure as `--json` alone (`{ id, title, deltaCount, deltas }`)
+- **AND** for each MODIFIED delta, the delta object SHALL include an additional `diff` string field containing the unified diff of the main requirement block vs the delta requirement block
+- **AND** when a MODIFIED requirement corresponds to a RENAMED entry, the main block SHALL be looked up using the RENAMED FROM name
+- **AND** ADDED, REMOVED, and RENAMED deltas SHALL NOT have a `diff` field
+- **AND** if a MODIFIED requirement has no matching main requirement, or its capability has no main spec, the delta object SHALL include a `warning` string field instead of `diff`
+- **AND** if a MODIFIED requirement matched only after folding case and interior whitespace, the delta object SHALL include both `diff` and `warning`
+- **AND** a textually identical MODIFIED block SHALL include `diff` as an empty string
+
+#### Scenario: Diff input cannot be read
+
+- **WHEN** delta discovery fails, a delta spec cannot be read, or a main spec exists but cannot be read
+- **THEN** the command SHALL exit with an error
+- **AND** the command SHALL NOT present the result as an empty delta set, a missing main spec, or a partial diff
+
+#### Scenario: Diff with no delta specs
+
+- **WHEN** executing `openspec show <change-name> --diff` and the change has no delta spec files
+- **THEN** print a message reporting that the change has no delta specs to diff
+- **AND** exit with code 0
+
+#### Scenario: Diff flag on non-change item
+
+- **WHEN** executing `openspec show <spec-name> --diff`
+- **THEN** ignore the `--diff` flag with a warning (flag is not applicable to specs)
+
+## ADDED Requirements
+
+### Requirement: Requirement block extraction for diffing
+
+The system SHALL extract raw markdown text for individual requirement blocks from spec files to support per-requirement diffing.
+
+#### Scenario: Extract requirement block by name
+
+- **WHEN** a requirement name is provided and a spec file contains a matching `### Requirement: <name>` header
+- **THEN** the system SHALL return the raw markdown text from the `### Requirement:` header line through all content until the next `###` header at the same or higher level (or end of file)
+
+#### Scenario: Requirement name matching
+
+- **WHEN** a requirement name matches a `### Requirement:` header exactly (after trimming)
+- **THEN** the system SHALL return that block and report the match as exact
+- **AND** when only a case- or interior-whitespace-folded match exists, the system SHALL return that block, report the match as inexact, and report the name as the main spec spells it
+- **AND** an exact match SHALL take precedence over a folded one
+
+#### Scenario: Requirement name not found in the main spec
+
+- **WHEN** a MODIFIED delta requirement name does not match any `### Requirement:` header in the main spec, exactly or folded
+- **THEN** the system SHALL return null for the main block
+- **AND** the caller SHALL display the full MODIFIED requirement text with a warning that no main requirement was found
+
+#### Scenario: Main spec paths resolve against the selected root
+
+- **WHEN** resolving the main spec path for a given capability
+- **THEN** the system SHALL build `openspec/specs/<cap>/spec.md` under the same OpenSpec root the change was read from, so `--store <id>` diffs against that store's main specs rather than the working directory
+- **AND** the system SHALL use `path.join()` for filesystem operations
+- **AND** display paths SHALL use forward slashes regardless of platform

openspec/changes/spec-diffs/tasks.md

@@ -0,0 +1,62 @@
+## 1. Add diff dependency
+
+- [x] 1.1 Install the `diff` npm package: `pnpm add diff` (v9 ships its own types, so no `@types/diff`)
+
+## 2. Requirement block extraction
+
+- [x] 2.1 In `src/utils/requirement-diff.ts`, add `extractRequirementBlock(specContent, requirementName): MatchedRequirementBlock | null`. Match exactly first, then report a folded case/whitespace match as inexact, and return raw markdown through the next peer or higher header.
+- [x] 2.2 Add unit tests for `extractRequirementBlock`: exact match, case-insensitive match, whitespace-insensitive match, no match returns null, last requirement in file (no following header), requirement inside code fence is not matched
+
+## 3. Per-requirement diff utility
+
+- [x] 3.1 In `src/utils/requirement-diff.ts`, add `diffRequirementBlock(baseBlock, deltaBlock): string` using `structuredPatch()` from `diff`, rendering only unified-diff hunks.
+- [x] 3.2 Add unit tests: base exists (expect removals + additions), base is null (all additions), identical blocks (empty/minimal diff)
+- [x] 3.3 Add function `buildRenameMap(renames: Array<{ from: string; to: string }>): Map<string, string>` that returns a map from normalized TO name → normalized FROM name, for use when looking up base blocks for MODIFIED requirements that were also renamed
+- [x] 3.4 Add unit tests for `buildRenameMap`: single rename, multiple renames, chained renames, empty list
+
+## 4. CLI flag registration
+
+- [x] 4.1 In `src/cli/index.ts`, add `.option('--diff', 'Show per-requirement diffs for delta specs')` to the `show` command and the `change show` subcommand
+- [x] 4.2 In `src/commands/show.ts`, add `'diff'` to the `CHANGE_FLAG_KEYS` set so it warns when used with `--type spec`
+
+## 5. Text mode diff display
+
+- [x] 5.1 In `src/commands/change.ts` `show()` method, discover files with `discoverSpecFiles()` and parse them with `parseDeltaSpec()`. Display ADDED, REMOVED, and RENAMED content directly; for MODIFIED, read the selected root's main spec, extract the matching block, and print a colorized unified diff.
+- [x] 5.2 Build a rename map from the parsed RENAMED entries for the current spec. For MODIFIED requirements whose normalized name matches a RENAMED TO name, look up the base block using the RENAMED FROM name instead of the MODIFIED name
+- [x] 5.3 Handle the no-delta-specs case: print "No delta specs to diff for change '<name>'" and return (exit code 0)
+- [x] 5.4 Handle the MODIFIED-no-base-match case: print the full MODIFIED requirement text with a warning that no matching base requirement was found
+- [x] 5.5 Add integration test: text mode diff with a change that has one MODIFIED and one ADDED requirement
+- [x] 5.6 Add integration test: text mode RENAMED + MODIFIED on the same requirement — shows both the rename label and the body diff, with the base block looked up by the old name
+- [x] 5.7 Add integration test: text mode MODIFIED with no matching base requirement — shows warning and full text
+
+## 6. JSON mode diff output
+
+- [x] 6.1 In `src/commands/change.ts` `show()` method, when `options.diff` and `options.json` are both set: for each MODIFIED delta, compute the diff (using rename map for base lookup) and add a `diff` string field to the delta object in the JSON output
+- [x] 6.2 Add integration test: JSON mode diff output includes `diff` field on MODIFIED deltas only (not on ADDED/REMOVED/RENAMED)
+- [x] 6.3 Add integration test: JSON mode RENAMED + MODIFIED — `diff` field on the MODIFIED delta shows changes relative to the old-name base block
+
+## 7. Cross-platform and CI verification
+
+- [x] 7.1 Ensure all path operations in new code use `path.join()` or `path.resolve()`; display paths normalize to forward slashes
+- [x] 7.2 Ensure unit tests use `path.join()` for expected path values, not hardcoded slash strings
+- [x] 7.3 Verify all existing tests pass (`pnpm test`)
+- [x] 7.4 Verify Windows CI passes (no path-separator issues in requirement matching or file discovery)
+
+## 8. Review follow-ups
+
+- [x] 8.1 Keep `openspec show <change>` without `--diff` a raw proposal passthrough; `--diff` is purely additive
+- [x] 8.2 Print the no-delta-specs message instead of returning silently, and cover it with a test
+- [x] 8.3 Keep the authored Reason/Migration body of a REMOVED requirement: `parseDeltaSpec` now returns `removedBlocks` alongside `removed`
+- [x] 8.4 Resolve main specs through the command's root (`--store <id>`), not `process.cwd()`, with a store-scoped regression test
+- [x] 8.5 Collect text-mode and JSON-mode diffs in one shared pass so the two surfaces cannot drift
+- [x] 8.6 Drive the CLI in tests with `execFileSync`/`spawnSync` argv arrays from a `mkdtemp` project instead of interpolated shell strings and an in-repo temp directory
+- [x] 8.7 Register `--diff` in the completion command registry so shell completions offer it
+- [x] 8.8 Drop the stray `package-lock.json`; the repo is pnpm-only
+- [x] 8.9 Enumerate delta specs with the shared `discoverSpecFiles()` so nested capabilities (`specs/<area>/<id>/spec.md`) are diffed, with a regression test
+- [x] 8.10 Warn instead of rendering all-additions when a MODIFIED requirement's capability has no main spec — that combination is an authoring error archive will reject, not a new capability
+- [x] 8.11 Match requirement headers exactly first and fall back to the shared case/whitespace fold, reporting a folded match as inexact so the diff still shows but the mismatch is named
+- [x] 8.12 Preserve both `diff` and `warning` in JSON when a folded match provides both diagnostics
+- [x] 8.13 Propagate discovery, delta-read, and non-`ENOENT` main-read failures instead of returning partial output
+- [x] 8.14 Resolve chained renames back to the original main requirement
+- [x] 8.15 Distinguish a textually empty MODIFIED diff from a missing main block in text and JSON output
+- [x] 8.16 Document `--diff` in the canonical `docs-lab` CLI reference and leave the legacy CLI page unchanged

openspec/changes/suppress-telemetry-notice-in-json/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-07

openspec/changes/suppress-telemetry-notice-in-json/proposal.md

@@ -0,0 +1,44 @@
+# Suppress the first-run telemetry notice in --json mode
+
+## Why
+
+`openspec <cmd> --json` is meant to emit exactly one machine-readable JSON
+document on stdout so agents and automation can parse it. Spinner suppression
+and structured JSON errors already ship on main, but one stdout writer remains:
+the first-run telemetry disclosure notice.
+
+On a user's first-ever command, `maybeShowTelemetryNotice()` runs from the
+global `preAction` hook and `console.log`s the disclosure to **stdout** — before
+the command's JSON payload. A `--json` consumer parsing that first run gets
+invalid JSON. It is first-run-only (the notice sets `noticeSeen`), but that is
+exactly the run an automation is most likely to hit on a fresh machine or CI
+image.
+
+## What Changes
+
+- `maybeShowTelemetryNotice()` accepts a `silent` option. When silent, it prints
+  nothing **and** leaves `noticeSeen` unset, so the disclosure is deferred rather
+  than skipped.
+- The `preAction` hook passes `silent: true` when the executing command asked
+  for JSON, decided by `isJsonRun(command)`. `--json` reaches commands three
+  ways, so a single parsed option (`opts().json`) is not enough: on the leaf
+  (`status --json`), on a parent group read via `optsWithGlobals`
+  (`workset --json list`), and as a residual arg on permissive groups that never
+  declare the option (`openspec store --json`). `isJsonRun` checks
+  `optsWithGlobals().json` and `command.args`, covering all three.
+
+Net effect: any `--json` invocation never emits the notice on stdout; the user
+still sees the disclosure on their first later non-JSON run. Suppressing is
+always safe — worst case the disclosure defers one run. Telemetry remains opt-out
+and otherwise unchanged.
+
+Out of scope: a few commands write scriptable output to stdout without a `--json`
+flag (`completion generate`, `config get`, `config path`, the hidden `__complete`).
+Their first-run notice pollution is a separate, pre-existing issue not addressed
+here.
+
+## Impact
+
+- Affected specs: `telemetry` (MODIFIED: First-run telemetry notice)
+- Affected code: `src/telemetry/index.ts`, `src/cli/index.ts`
+- No change to non-JSON behavior; no new events or data collected.