Version Packages (#1953)

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,10 +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).
+#   1. pnpm `overrides` (pnpm-workspace.yaml, 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). They live in
+#      pnpm-workspace.yaml only, because Dependabot *does* rewrite a plain-name
+#      override (`postcss: ^8.5.26`) mirrored under package.json's `pnpm.overrides`
+#      — and that block replaces the workspace list rather than merging with it,
+#      so the mirror displaces the real pins. See #1812.
 #   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.
@@ -29,6 +33,10 @@ updates:
       - 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

.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: |
@@ -42,6 +42,10 @@ jobs:
               - 'pnpm-workspace.yaml'
               - 'scripts/update-flake.sh'
               - '.github/workflows/ci.yml'
+              # The Nix build runs `openspec completion generate`, so a change to
+              # the generator can break packaging without touching flake.nix.
+              - 'src/commands/completion.ts'
+              - 'src/core/completions/**'
 
   test_matrix:
     name: Test (${{ matrix.label }})
@@ -77,7 +81,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -132,7 +136,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -176,10 +180,35 @@ jobs:
           persist-credentials: false
 
       - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+        uses: DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23
 
       - name: Setup Nix cache
-        uses: DeterminateSystems/magic-nix-cache-action@908b263ff629f4cc17666315b7fd3ec127c6244d # v14
+        uses: DeterminateSystems/magic-nix-cache-action@84c0677f58dcedf3b91f8223ce36a9ea5b3c84b7 # v15
+
+      # Run the update script before `nix build`, not after. The script recomputes
+      # the pnpmDeps hash from pnpm-lock.yaml and rewrites flake.nix in place, so a
+      # stale hash is reported here as the exact value to paste. Built first, the
+      # same staleness surfaces as pnpm's ERR_PNPM_NO_OFFLINE_TARBALL — which names
+      # a missing tarball, not the hash — and the script never runs to say otherwise.
+      # Every root lockfile change needs this value, and Dependabot cannot produce it.
+      - name: Verify pnpmDeps hash matches the lockfile
+        run: |
+          bash scripts/update-flake.sh
+          if git diff --quiet flake.nix; then
+            echo "✅ flake.nix pnpmDeps hash is up to date"
+            exit 0
+          fi
+          # Scoped to the pnpmDeps block: a bare first-match would report some other
+          # FOD's hash if one is ever added above it.
+          HASH=$(sed -n '/pnpmDeps = /,/};/p' flake.nix \
+            | sed -nE 's/.*hash = "(sha256-[^"]+)".*/\1/p' | head -1)
+          git diff flake.nix
+          echo "::error file=flake.nix::Stale pnpmDeps hash. Set pnpmDeps.hash to $HASH and push."
+          exit 1
+
+      - name: Restore flake.nix
+        if: always()
+        run: git checkout -- flake.nix || true
 
       - name: Build with Nix
         run: nix build
@@ -194,6 +223,19 @@ jobs:
             echo "Error: openspec binary not found in build output"
             exit 1
           fi
+          for completion in \
+            "share/bash-completion/completions/openspec.bash" \
+            "share/fish/vendor_completions.d/openspec.fish" \
+            "share/zsh/site-functions/_openspec"; do
+            if [ ! -s "result/$completion" ]; then
+              echo "Error: completion script missing or empty: $completion"
+              exit 1
+            fi
+          done
+          if [ "$(head -1 result/share/zsh/site-functions/_openspec)" != "#compdef openspec" ]; then
+            echo "Error: zsh completion is not autoloadable (missing #compdef header)"
+            exit 1
+          fi
           echo "✅ Build output verified"
 
       - name: Test binary execution
@@ -206,25 +248,6 @@ jobs:
           fi
           echo "✅ Binary execution successful"
 
-      - name: Validate update script
-        run: |
-          echo "Testing update-flake.sh script..."
-          bash scripts/update-flake.sh
-          echo "✅ Update script executed successfully"
-
-      - name: Check flake.nix modifications
-        run: |
-          if git diff --quiet flake.nix; then
-            echo "ℹ️  flake.nix unchanged (hash already up-to-date)"
-          else
-            echo "✅ flake.nix was updated by script"
-            git diff flake.nix
-          fi
-
-      - name: Restore flake.nix
-        if: always()
-        run: git checkout -- flake.nix || true
-
   validate-changesets:
     name: Validate Release Tracking
     runs-on: ubuntu-latest
@@ -242,10 +265,14 @@ jobs:
           changed_changesets="$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD -- '.changeset/*.md' ':!.changeset/README.md')"
           if [[ -n "$changed_changesets" ]]; then
             echo "has_changesets=true" >> "$GITHUB_OUTPUT"
+            # Run-unique delimiter: the value is a list of PR-authored paths, so a
+            # fixed "EOF" would let a crafted path close the block early and append
+            # its own key=value outputs.
+            delim="EOF_$(openssl rand -hex 16)"
             {
-              echo "files<<EOF"
+              echo "files<<$delim"
               echo "$changed_changesets"
-              echo "EOF"
+              echo "$delim"
             } >> "$GITHUB_OUTPUT"
           else
             echo "has_changesets=false" >> "$GITHUB_OUTPUT"
@@ -254,13 +281,13 @@ jobs:
 
       - name: Setup pnpm
         if: steps.changed-changesets.outputs.has_changesets == 'true'
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - 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

@@ -40,7 +40,7 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app-token.outputs.token }}
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -53,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@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2.1.2
         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)
@@ -80,7 +84,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:

.github/workflows/security.yml

@@ -51,7 +51,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       # No dependency cache: `pnpm audit` reads the lockfile, nothing is installed,
       # so a cache-save step would fail on the missing store path.
@@ -109,7 +109,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

CHANGELOG.md

@@ -1,5 +1,253 @@
 # @fission-ai/openspec
 
+## 1.13.2
+
+### Patch Changes
+
+- [#1940](https://github.com/Fission-AI/OpenSpec/pull/1940) [`0b5ce44`](https://github.com/Fission-AI/OpenSpec/commit/0b5ce44b55e0d793a312290ba5a41170a78e47c6) Thanks [@clay-good](https://github.com/clay-good)! - Keep fast-forward clarification guidance and onboarding task approval consistent across generated skills and commands. Fast-forward now asks only when context is critically unclear, while onboarding asks users to approve the task breakdown before saving it and separately asks whether to begin implementation.
+
+- [#1926](https://github.com/Fission-AI/OpenSpec/pull/1926) [`f2812f6`](https://github.com/Fission-AI/OpenSpec/commit/f2812f6d185f47cb577055f2fe243f12000d6cd2) Thanks [@kevin9327](https://github.com/kevin9327)! - ### Bug Fixes
+  
+  - **Archive** — When Windows `EPERM` blocks renaming a change directory that still has children, copy from the original source instead of requiring a staging rename that fails the same way. That lets archive finish instead of rolling back the spec write and leaving an empty capability directory git cannot see. A staging failure that is not `EPERM`/`EXDEV` still leaves the source untouched.
+  
+    The source of that unstaged copy is still the live change directory, which the archive claim does not cover, so cleanup removes only the entries it copied and verified rather than whatever is present when it runs. A file written in that window is left alone and the complete destination is retained for recovery, instead of being deleted without ever reaching the archive.
+  
+    An edit to a file that was already verified is covered too. Cleanup claims each entry with an atomic rename before reading it, then compares what it claimed against the copy. A rewrite that lands first is caught by that comparison and the file is put back; one that lands after creates a new file at the original path, which is never deleted. Either way the newer bytes stay on disk and archive reports the move as incomplete rather than succeeding with the older copy.
+  
+    Rollback of a newly created spec now also prunes the capability directory it created — and only that one. An empty capability directory that was already there is left in place with its own permissions.
+
+- [#1795](https://github.com/Fission-AI/OpenSpec/pull/1795) [`fb1b876`](https://github.com/Fission-AI/OpenSpec/commit/fb1b87613b7cdbe8d74e8147833904f46f0468c6) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Archive workflows now use schema-aware task progress from `openspec list --json`, so custom task files and globs still trigger incomplete-task warnings.
+
+- [#1885](https://github.com/Fission-AI/OpenSpec/pull/1885) [`fd56e12`](https://github.com/Fission-AI/OpenSpec/commit/fd56e12c9e7fdbbfdc2dcd0a5ef3fab04840909d) Thanks [@philo-x](https://github.com/philo-x)! - Fix artifact output resolution to recognize brace expansion and extglob patterns while preserving literal output filenames and confining brace-expanded paths to the change directory.
+
+- [#1964](https://github.com/Fission-AI/OpenSpec/pull/1964) [`7ac58dc`](https://github.com/Fission-AI/OpenSpec/commit/7ac58dc7905a4eeaaad7eff2b2b64cf971fd6ec7) Thanks [@clay-good](https://github.com/clay-good)! - Continue commands now open with an instruction to follow the active OpenSpec workflow directly, so local models no longer try to call a tool named after it ([#1944](https://github.com/Fission-AI/OpenSpec/issues/1944)).
+
+- [#1964](https://github.com/Fission-AI/OpenSpec/pull/1964) [`7ac58dc`](https://github.com/Fission-AI/OpenSpec/commit/7ac58dc7905a4eeaaad7eff2b2b64cf971fd6ec7) Thanks [@clay-good](https://github.com/clay-good)! - Generate Kilo Code commands in `.kilo/command/`, the directory Kilo Code reads, instead of `.kilocode/workflows/` ([#1938](https://github.com/Fission-AI/OpenSpec/issues/1938)). `openspec init` and legacy cleanup remove the workflow files OpenSpec generated there, matched by their known file names (including copies you edited), and leave files with other names in place.
+
+- [#1958](https://github.com/Fission-AI/OpenSpec/pull/1958) [`1d35e90`](https://github.com/Fission-AI/OpenSpec/commit/1d35e908804dbb3c4a1851516759c5de190aa4d5) Thanks [@clay-good](https://github.com/clay-good)! - Preserve a file's existing line endings when rewriting it, so Windows users no longer get whole-file diffs. Applying a delta to a CRLF spec (the default on a Windows checkout with `core.autocrlf=true`) rewrote the file to LF, turning a one-requirement change into a diff that touched every line. `openspec archive` now writes the spec back with the convention it already used; a spec that does not exist yet is still written with LF.
+  
+  The same fix covers marker-managed files: installing or updating shell completions in a CRLF `.bashrc` or `.zshrc` no longer leaves the file with mixed endings, which `bash` reports as `$'\r': command not found`.
+  
+  Removing a managed block is fixed the same way: the blank-line collapse in `removeMarkerBlock` rebuilt its separator as a bare LF, so cleaning up legacy artifacts left a lone LF inside an otherwise-CRLF `CLAUDE.md` or rc file. Both write paths now read the file the same way, by dominant ending, so one stray CRLF in an otherwise-LF file no longer pulls the whole rewrite to CRLF.
+  
+  `scripts/pack-version-check.mjs` now spawns `npm` through `cross-spawn`, so the release guard can run on Windows, where `npm` is `npm.cmd` and cannot be resolved by `execFile`.
+
+- [#1912](https://github.com/Fission-AI/OpenSpec/pull/1912) [`8826c0c`](https://github.com/Fission-AI/OpenSpec/commit/8826c0c4a17d3511947b7c5e0934257f153f0ed2) Thanks [@Tyagiquamar](https://github.com/Tyagiquamar)! - Fix `validate --strict` reporting `PURPOSE_IS_PLACEHOLDER` for a Purpose that opens with the ordinary word "Todo" followed by prose, as in Spanish ("Todo el…") and Portuguese ("Todo o…") specs ([#1897](https://github.com/Fission-AI/OpenSpec/issues/1897)).
+  
+  - Case now separates the marker from the word. `TBD`/`TODO` in capitals is still a placeholder marker whatever follows it, so `TODO write this later` is still reported.
+  - In any other case it counts as a marker only when followed by the end of the Purpose, a line break, or marker punctuation (`todo -`, `tbd.`), so an authored Spanish or Portuguese sentence is not reported.
+
+- [#1744](https://github.com/Fission-AI/OpenSpec/pull/1744) [`5b55263`](https://github.com/Fission-AI/OpenSpec/commit/5b5526377506c2f0179674a869c1ac64ca9ab72d) Thanks [@javigomez](https://github.com/javigomez)! - Clarify the Codex setup hint for CLI, IDE, and desktop app users.
+
+- [#1809](https://github.com/Fission-AI/OpenSpec/pull/1809) [`a5ceea3`](https://github.com/Fission-AI/OpenSpec/commit/a5ceea32cf110b6d8bbfea0bf1c65fe55abb133b) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Say what a `MODIFIED` block adds when the scenario-loss guard fires ([#1809](https://github.com/Fission-AI/OpenSpec/pull/1809)). `openspec validate` and `openspec archive` already named the scenarios a block omits. They now also print how many scenarios each side has and which ones the block introduces, capped at three names, so a rename and a truncation read differently without opening either file. The guard catches exactly what it did before, and no exit code changes.
+
+- [#1731](https://github.com/Fission-AI/OpenSpec/pull/1731) [`d6bdef6`](https://github.com/Fission-AI/OpenSpec/commit/d6bdef6577a077614382ef47b64100852182d6a6) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Stop workflows from displaying schema names that `openspec list --json` does not return. Update and continue no longer fabricate a `spec-driven` picker label, while bulk archive and explore describe only the change fields the list command actually provides.
+
+- [#1955](https://github.com/Fission-AI/OpenSpec/pull/1955) [`ed5d386`](https://github.com/Fission-AI/OpenSpec/commit/ed5d386a559c0215af1182d479d7f99b309fdcd2) Thanks [@clay-good](https://github.com/clay-good)! - Task guidance now requires each task group to land its own tests and documentation updates instead of deferring them to a trailing group. The onboarding walkthrough teaches the same rule, and the published schema reference no longer quotes stale instruction text.
+
+- [#1939](https://github.com/Fission-AI/OpenSpec/pull/1939) [`a64303f`](https://github.com/Fission-AI/OpenSpec/commit/a64303fe1e24f08dbf44f78032fadbeac3a6f7fa) Thanks [@clay-good](https://github.com/clay-good)! - Return a nonzero exit status when `openspec update --force` cannot replace a legacy-only Codex installation.
+
+- [#1733](https://github.com/Fission-AI/OpenSpec/pull/1733) [`72fbe4c`](https://github.com/Fission-AI/OpenSpec/commit/72fbe4c904707396151921a20b506d081a9dc024) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Let `/opsx:update` fill a missing file under an already-satisfied glob artifact. A glob artifact is complete once one file matches it, and `/opsx:continue` only picks up `ready` artifacts, so the previous "point the user to `/opsx:continue`" handoff was unreachable and the missing file could never be created through the documented flow.
+
+- [#1962](https://github.com/Fission-AI/OpenSpec/pull/1962) [`3364146`](https://github.com/Fission-AI/OpenSpec/commit/336414665f3f987ae424177ab1b6891a4304baeb) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Stop `/opsx:verify` from reporting a correctly removed requirement as missing. Verify now reads which delta section each requirement sits under: ADDED and MODIFIED requirements are checked for an implementation as before, a REMOVED requirement passes once its behavior is gone and is flagged only while it is still present, and the old name of a RENAMED requirement is no longer reported as missing.
+
+- [#1732](https://github.com/Fission-AI/OpenSpec/pull/1732) [`072de6b`](https://github.com/Fission-AI/OpenSpec/commit/072de6bc39b1c47b9aacf4d484be16345ca4f38e) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Stop `/opsx:verify` from reporting skipped checks as passing. Task completion now uses the schema-aware `tasks` and `progress` fields returned by apply instructions, while absent spec or design inputs are mapped to every check they prevent. Apply instructions aggregate every file matched by the configured task path or glob, regardless of the tracked artifact ID. Verification stays advisory and does not require optional or intentionally omitted artifacts. The scorecard identifies each skipped check, and the final assessment does not claim archive readiness when any check did not run.
+
+- [#1769](https://github.com/Fission-AI/OpenSpec/pull/1769) [`d3d7707`](https://github.com/Fission-AI/OpenSpec/commit/d3d770736fc01bb246b4f12a7cef7e3572ec1fb6) Thanks [@kikeprzn](https://github.com/kikeprzn)! - Fix `openspec archive` leaving `.openspec-archive.lock` behind on Windows. Node can report `dev: 0n` from a path stat while the open file handle reports the real volume id, so the claim-ownership check never matched and the stale lock blocked every later archive. The check now treats an absent device id as unavailable while still requiring the inode and the claim's contents to match before unlinking.
+
+## 1.13.1
+
+### Patch Changes
+
+- [#1864](https://github.com/Fission-AI/OpenSpec/pull/1864) [`767d63c`](https://github.com/Fission-AI/OpenSpec/commit/767d63c926ab1996170f2d101acac0bac6da0287) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archive adding a second copy of an existing requirement under a name that differs only in case or spacing. ADDED and the RENAMED target compared requirement names exactly, while REMOVED and the RENAMED source already treated a case or whitespace variant as a mistyped header, so an ADDED `late fees` beside an existing `Late Fees`, or a rename to `LATE FEES`, archived cleanly and left two contradicting requirements in the main spec, which `validate` then accepted. Both now refuse with an error naming the existing requirement, in the same form REMOVED already used. The exact-duplicate error is unchanged, a case-only rename of a requirement to its own name still works, and a variant of a requirement the same delta removes or renames away is still allowed, because ADDED is checked against the spec as it stands after the earlier operations, as the exact check already was.
+
+- [#1872](https://github.com/Fission-AI/OpenSpec/pull/1872) [`72bf760`](https://github.com/Fission-AI/OpenSpec/commit/72bf7600a5f7bdf74d6387e163577086fb4c68e0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Make `openspec completion uninstall bash` hand `.bashrc` back exactly as `completion install bash` found it. Install adds the OpenSpec block at the top of the file followed by a blank separator line; uninstall removed the block but kept that blank line at the top, then stripped every trailing blank line and wrote the file back without its final newline. The byte count happened to come out unchanged, but the next tool to append to `.bashrc` with `>>` (the nvm, conda and rustup installers all do) merged its first line into the user's last line and broke both. Uninstall now also drops the separator line install added when the block sits at the top of the file, and leaves the rest untouched: the final newline, trailing blank lines and CRLF line endings all survive the round trip. A block the user moved elsewhere in the file is still removed, and the zsh, fish and PowerShell installers are unchanged.
+
+- [#1829](https://github.com/Fission-AI/OpenSpec/pull/1829) [`e67ac47`](https://github.com/Fission-AI/OpenSpec/commit/e67ac47f3a164cf6d87ddcd9f50272b88f39ee0c) Thanks [@choi138](https://github.com/choi138)! - Fix bulk archive nesting a change inside an existing archive target. The workflow now checks every archive target before it writes any main spec, the same order `openspec archive` uses. A change whose target already exists, or that shares a target with another selected change, is reported as failed and is never synced or moved, while the rest of the batch continues. The check runs again just before each move.
+
+- [#1878](https://github.com/Fission-AI/OpenSpec/pull/1878) [`2ef6fbd`](https://github.com/Fission-AI/OpenSpec/commit/2ef6fbde3da95f6e471bcb504d13711308091be0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Let `openspec config edit` run an `EDITOR` or `VISUAL` that carries arguments. The whole value was passed to `spawn` as the program name, so common settings such as `code --wait`, `subl -w` or `emacsclient -t` failed with `spawn code --wait ENOENT`, and because that error was never caught the command died with a raw Node stack trace. The value is now split into a program and its arguments, honoring quoted paths with spaces, and the config path is appended as its own argument. No shell is involved, so shell metacharacters in the value are passed through literally. On Windows, `.cmd` shims such as `code.cmd` are found. A value that is itself the absolute path of an existing file is still run as-is, so an unquoted editor path containing spaces keeps working. An editor that cannot be started, exits non-zero or is killed is now reported as a one-line error naming the editor, with an install hint when the program was not found, and the command exits 1 instead of throwing. `EDITOR` still takes precedence over `VISUAL`, and the file is still validated after the editor closes.
+
+- [#1773](https://github.com/Fission-AI/OpenSpec/pull/1773) [`11a9691`](https://github.com/Fission-AI/OpenSpec/commit/11a9691524bad84a575854bf6dc5124f630479ba) Thanks [@clay-good](https://github.com/clay-good)! - Stop dropping checkbox lines whose marker the task parser does not recognise. A `tasks.md` whose remaining work used a marker other than `[ ]`/`[x]`/`[X]`, for example `- [~] 1.2 Deferred`, reported `✓ Complete` in `openspec list`/`status` and archived with no incomplete-task warning, because unmatched lines counted toward neither the numerator nor the denominator. An empty `[]` and a padded `[ x]` were lost the same way. Only a box holding `x` or `X` means done (spacing inside the brackets is ignored, so `[ x]` is done), and every other marker now reads as unfinished, across progress, the apply task list, archive's gate and validate's task-numbering check. The archive, bulk-archive and verify workflows now tell agents the same rule, so a hand-counted tally cannot disagree with the CLI, and the `tasks` instruction in the `spec-driven` schema states it where agents author the file. Markdown link bullets stay out of the count: `- [Some doc](./doc.md)` and the one-character `- [A](https://example.com)` are not tasks.
+
+- [#1701](https://github.com/Fission-AI/OpenSpec/pull/1701) [`92fb72d`](https://github.com/Fission-AI/OpenSpec/commit/92fb72d1dcd5fa6e43802c5b2f74b5e78416e545) Thanks [@clay-good](https://github.com/clay-good)! - Agent-driven archive and sync workflows now create a missing main spec from `ADDED` requirements instead of treating it as already synced. They block sync rather than inventing `MODIFIED` or `RENAMED` requirements or writing an empty spec for a `REMOVED`-only delta, while preserving the user's explicit choice to archive without syncing. A REMOVED-only delta with `retire_capabilities: true` remains already synced when its main spec is gone. Fixes [#1222](https://github.com/Fission-AI/OpenSpec/issues/1222) and [#1264](https://github.com/Fission-AI/OpenSpec/issues/1264).
+
+- [#1804](https://github.com/Fission-AI/OpenSpec/pull/1804) [`a5bf5c6`](https://github.com/Fission-AI/OpenSpec/commit/a5bf5c68447f03e4f99206e49e00b5d9111301a4) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Say so when a requirement in a delta sits outside every delta section. A well-formed `### Requirement:` block written under `## Notes`, under a misspelled header such as `## Add Requirements`, or above the first `## ` header was dropped with no diagnostic: `openspec validate` reported the change valid and `openspec archive` exited 0 without applying it. `openspec validate` now reports each one as a WARNING naming the section and line, and archive prints the same warning. Nothing else changes: the block is still not applied, the verdict stays valid outside `--strict`, and requirements shown inside a code fence are not reported. Fixes [#1803](https://github.com/Fission-AI/OpenSpec/issues/1803).
+
+- [#1832](https://github.com/Fission-AI/OpenSpec/pull/1832) [`4c369e0`](https://github.com/Fission-AI/OpenSpec/commit/4c369e022b1d397842d2b85675e34da6287f5801) Thanks [@clay-good](https://github.com/clay-good)! - Resolve the contradiction that left explore mode's capture branch without a governing rule. Explore states twice that the agent must ask a direct yes/no question and wait for confirmation in a separate user message before its first write-capable action, naming `openspec new change` as an example, while the capture branch tells the agent to transition "seamlessly" into running `openspec new change` and creating artifacts with no confirmation step. Both readings were defensible from the text, so the same "capture this as a change" request either wrote `.openspec.yaml` plus several artifacts immediately or stopped and asked, depending on which passage the agent weighed, which made the [#1715](https://github.com/Fission-AI/OpenSpec/issues/1715) guarantee unenforceable in the one explore path that writes files. An explicit capture request is now stated to be that confirmation, covering the change and the artifacts the request names and nothing else. The guardrail keeps its teeth for the case [#1715](https://github.com/Fission-AI/OpenSpec/issues/1715) actually reported: when the agent is the one proposing the capture, or when the work would go beyond the requested scope, it still asks first, and answers to design or clarifying questions are still never consent to write. Both explore delivery surfaces and the committed skill carry the same wording. Fixes [#1828](https://github.com/Fission-AI/OpenSpec/issues/1828).
+
+- [#1788](https://github.com/Fission-AI/OpenSpec/pull/1788) [`62106f4`](https://github.com/Fission-AI/OpenSpec/commit/62106f40e3b7b7364529a2f928717e23e37282eb) Thanks [@clay-good](https://github.com/clay-good)! - Name the workflow where explore hands off. Explore mode refuses to implement, but every place it said what to do instead described the next step as prose ("create a change proposal") without naming the workflow that does it: the refusal itself, the "flow into a proposal" ending, the closing summary, and the do-not-implement guardrail. Its seamless capture path was worse: it scaffolded a change, wrote artifacts, and then said nothing at all about what came next. With no named exit, agents finished the discovery questions and started writing code, which is the failure reported through GitHub Copilot in [#869](https://github.com/Fission-AI/OpenSpec/issues/869), and which the docs already promised would not happen ("when the picture is clear, it hands off to `/opsx:propose`").
+  
+  The explore skill and command now name `/opsx:propose` at all four prose handoffs, and the capture path ends by naming `/opsx:propose` for the remaining planning artifacts and `/opsx:apply` for implementation, with an explicit note that capturing artifacts is not permission to implement them. The references are written in the canonical `/opsx:<id>` form so each tool renders the invocation it actually registers (`/openspec-propose` for skills-only delivery, `/opsx-propose`, `/opsx:propose`, or `@opsx-propose` for command surfaces). The handoffs follow the installed workflow set: a custom profile without `propose` or `apply` gets explore's own capture path and the `openspec instructions apply` CLI instead of a command it never installed. Fixes [#869](https://github.com/Fission-AI/OpenSpec/issues/869).
+
+- [#1787](https://github.com/Fission-AI/OpenSpec/pull/1787) [`9827762`](https://github.com/Fission-AI/OpenSpec/commit/9827762d2d18d8076acf90be79d64894255099ea) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - Generated skills and commands no longer adopt a project that never ran `openspec init`. Every workflow now checks `root` from `openspec list --json` before its first write, and `"root": null` means the project is not set up. What happens next depends on how the workflow was reached. A skill the agent picked on its own drops OpenSpec and answers the request normally, without asking about setup. A workflow the user asked for by name, or ran as a slash command, stops and asks whether to initialize the project, target a store, or handle the request without OpenSpec. A project whose `openspec/config.yaml` names a store this machine cannot resolve (not registered, or a malformed `store:` line) is not mistaken for an uninitialized one: the workflow stops and shows the store error. Neither path lets `openspec new change` create `openspec/` in the current directory as a side effect. Skill descriptions now name OpenSpec so hosts stop offering these workflows in unrelated repositories. `openspec new change` also says when it had to create the root itself, so a directory that was never set up no longer picks up an `openspec/` directory in silence (human output only; `--json` is unchanged).
+
+- [#1902](https://github.com/Fission-AI/OpenSpec/pull/1902) [`eb03b9e`](https://github.com/Fission-AI/OpenSpec/commit/eb03b9e93320cf74a0df9043577d8023116cb1aa) Thanks [@clay-good](https://github.com/clay-good)! - Harden the CLI against repositories you have cloned but not yet read ([#1835](https://github.com/Fission-AI/OpenSpec/pull/1835)).
+  
+  - A `config.yaml` value can no longer close the project context block and inject its own directives into the instructions an agent receives.
+  - A crafted delta or skill file no longer stalls `openspec update` or `openspec archive` with catastrophic regex backtracking.
+  - A repository's `.npmrc` can no longer point the update check at a cleartext or attacker-controlled registry; a rejected registry now disables the check instead of falling back.
+  - `openspec update` now notices a generated `SKILL.md` that was edited by hand and restores it, instead of reporting every tool as up to date.
+  - `DO_NOT_TRACK=true` and other common spellings of an opt-out now turn telemetry off, and nothing is sent until the first-run notice has been shown.
+  - Shell-completion installs quote directory paths safely, git probes run with bounded time and output, and dependencies are cleared of known advisories.
+
+- [#1874](https://github.com/Fission-AI/OpenSpec/pull/1874) [`388d344`](https://github.com/Fission-AI/OpenSpec/commit/388d34473a40529320b2b7b9c5bb6723d18322b0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop legacy cleanup deleting the user's own files. The six pre-skills tools that kept their commands in a `<tool>/commands/openspec/` folder (Claude Code, CodeBuddy, Qoder, Lingma, Crush and Gemini CLI) had that whole folder removed recursively whenever it existed, so a command the user kept there, such as a team review checklist, was deleted along with OpenSpec's files, and the summary named only the folder. Because `openspec init` cleans up automatically when there is no TTY, an agent or CI running plain `openspec init` did this without `--force` and without a prompt, and `openspec update --force` did the same. Cleanup now deletes only the files OpenSpec wrote there: `proposal`, `apply` and `archive` files that still carry the OpenSpec markers every legacy command was generated with, so a same-named file the user wrote is kept. It never follows a symlinked command folder, removes the folder only once nothing else is left in it, and lists each thing it kept. A folder holding nothing OpenSpec wrote is no longer reported as legacy at all. A folder holding only OpenSpec's files, or nothing, is still removed exactly as before, with the same summary line.
+
+- [#1866](https://github.com/Fission-AI/OpenSpec/pull/1866) [`8146be5`](https://github.com/Fission-AI/OpenSpec/commit/8146be5546918cdffce860f1e327d929c5a49bd3) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop one unresolvable file from breaking `openspec list`. To sort changes by recency, `list` stats every file inside each change, and any entry it could not stat failed the whole command: a dangling symlink, such as the `.#tasks.md` lock Emacs keeps beside every file with unsaved edits, or a symlink loop made `list` exit 1 and `list --json` report `"changes": []`, so agents discovering work through it saw no changes at all. An entry that no longer resolves (removed mid-walk, a dangling symlink, or a loop) is now skipped when computing a change's last-modified time. Valid symlinks are dated as before, and any other error, such as a permission failure, still fails the listing.
+
+- [#1849](https://github.com/Fission-AI/OpenSpec/pull/1849) [`09a999b`](https://github.com/Fission-AI/OpenSpec/commit/09a999bbb258c2ad6d7cdc33436c698c15d4eebe) Thanks [@clay-good](https://github.com/clay-good)! - Report a change directory nested in a namespace folder instead of silently listing the folder around it as a change. Specs can be nested by domain (`specs/mobile/tutorial-videos/spec.md`), so it looks reasonable to lay changes out the same way, but a change is only ever a directory directly under `changes/`: `changes/mobile/refresh-token/` left the real change invisible while `mobile` was reported as a task-less change everywhere. `openspec archive mobile` then moved the unfinished change into the archive under the namespace's name and applied none of its deltas. `openspec list` now marks the folder `not a change` and names the nested directories and a flat alternative, `openspec show`, `openspec status --change` and `openspec status --all` say the same instead of reporting a missing proposal or a full artifact plan, `openspec validate` reports it instead of "must have at least one delta", `openspec list --json` carries a `warnings` entry, and `openspec archive` refuses the folder outright. Detection looks up to three directory levels below `changes/`, which covers every namespace layout seen in practice; a change buried deeper than that behaves as it did before. Fixes [#1846](https://github.com/Fission-AI/OpenSpec/issues/1846).
+
+- [#1902](https://github.com/Fission-AI/OpenSpec/pull/1902) [`eb03b9e`](https://github.com/Fission-AI/OpenSpec/commit/eb03b9e93320cf74a0df9043577d8023116cb1aa) Thanks [@clay-good](https://github.com/clay-good)! - Install shell completions with the Nix flake package ([#1785](https://github.com/Fission-AI/OpenSpec/pull/1785)). The package now ships bash, zsh and fish completions in their standard `share/` locations, so Nix users get tab completion without running `openspec completion install` against their home directory.
+
+- [#1775](https://github.com/Fission-AI/OpenSpec/pull/1775) [`626269e`](https://github.com/Fission-AI/OpenSpec/commit/626269ed732250492d8bd220a83df23dd756ee5d) Thanks [@clay-good](https://github.com/clay-good)! - Generated skills and commands no longer point at workflows the active profile does not install. On the default `core` profile, the update workflow told agents to hand off to `/opsx:continue` for missing artifacts and to `/opsx:new` for a change of intent, neither of which `core` generates. Every cross-workflow handoff is now decided at generation time against the installed workflow set, and renders a concrete CLI fallback (`openspec status`, `openspec instructions`, `openspec archive`) when the workflow it would name is absent, rather than relying on a runtime availability check the agent had to perform. The onboarding tutorial's command tables are likewise built from the workflows you actually have.
+  
+  Also folds in [#1735](https://github.com/Fission-AI/OpenSpec/issues/1735), which fixed the same issue ([#1734](https://github.com/Fission-AI/OpenSpec/issues/1734)) by removing the optional handoffs outright. The CLI's own runtime instructions no longer name the `openspec-continue-change` skill either, since those strings are chosen at run time and cannot be resolved against a profile; and the blocked-state fallback now carries the full CLI recovery (select the next `ready` artifact from `openspec status`, read its rules with `openspec instructions`, keep the selected `--store`) rather than a one-line pointer.
+
+- [#1870](https://github.com/Fission-AI/OpenSpec/pull/1870) [`e01ed07`](https://github.com/Fission-AI/OpenSpec/commit/e01ed070f18e15529f82563d4c5af35d8124bad3) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archiving a change whose delta was written somewhere `archive` never reads. `validate` and `archive` read a change's deltas only from `specs/<capability-path>/spec.md`, but the spec-driven artifact graph counts any markdown file under `specs/` as the specs being written, so a delta at `specs/user-auth.md`, or in a second file beside a capability's `spec.md`, was reported done by `status` and ready by `instructions apply` with no warning, rejected by `validate` only as "no deltas found", and then archived with exit 0 and nothing merged into `openspec/specs/`. A markdown file that carries delta sections but is not a capability's `spec.md` is now a validation error naming the file and the `spec.md` its requirements belong in; `archive` runs that validation and refuses the change instead of archiving it unmerged, and `instructions apply` lists each such file in its `warnings`. `--no-validate` still archives as before, a change with no spec files still archives, and notes without delta sections under `specs/` are not affected.
+
+- [#1806](https://github.com/Fission-AI/OpenSpec/pull/1806) [`6e62b1d`](https://github.com/Fission-AI/OpenSpec/commit/6e62b1d522cfadb4b9836b63d5afa127bc950743) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Refuse a `## RENAMED Requirements` section whose `FROM:` and `TO:` lines do not pair up, instead of guessing. The reader kept one pending pair and dropped whatever did not fit: a `TO:` before its `FROM:`, a `FROM:` displaced by a second `FROM:`, or a trailing `FROM:` vanished with no diagnostic. Listing the old names and then the new ones paired the second `FROM:` with the first `TO:`, so `openspec archive` renamed a requirement the delta never named, under a name written for a different one, and exited 0. `openspec validate` now reports each unpaired line as an ERROR with its line number, and archive refuses the change until the pairing is fixed. Well-formed renames, including several consecutive pairs, are unchanged. A change that used to archive with a malformed RENAMED section is now rejected. Fixes [#1805](https://github.com/Fission-AI/OpenSpec/issues/1805).
+
+- [#1860](https://github.com/Fission-AI/OpenSpec/pull/1860) [`4b5c07a`](https://github.com/Fission-AI/OpenSpec/commit/4b5c07a0c2e5a4a1dcb3ed9f3a040f826eb7d457) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Read a requirement heading written with a CommonMark closing sequence, such as `### Requirement: Late Fees ###`, as the requirement it renders as. The trailing `#` run stayed in the name, so a REMOVED written that way looked for "Late Fees ###", missed the requirement, and archive exited 0 with a false "treating it as already removed" warning while the requirement stayed in the spec; a closed MODIFIED or RENAMED heading failed as "not found", and a closed and an open heading of one requirement were not reported as duplicates. Requirement names now drop the closing run wherever they are read, exactly as scenario names already did: only a run preceded by a space or tab counts, so a name such as `C#` keeps its `#`. Headings without a closing run are unaffected.
+
+- [#1868](https://github.com/Fission-AI/OpenSpec/pull/1868) [`7090e16`](https://github.com/Fission-AI/OpenSpec/commit/7090e16d74dfe588dad72bc4fda9bf124e71b0af) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Reject a schema whose `apply.requires` names an artifact that does not exist. `parseSchema` checked every artifact's `requires` but never `apply.requires`, so `openspec schema validate` passed a one-character typo there, and apply then skipped the unknown id: `apply.requires: [desgin]` turned the apply gate off and told the agent "Proceed with implementation" with only a proposal written. That is now a schema error, raised wherever the schema is loaded, exactly like an unknown artifact `requires`, and it names the bad id and the artifacts the schema declares. `openspec schema validate` also warns, without failing, when `apply.tracks` isn't exactly equal to some artifact's `generates` value, because OpenSpec finds the tracked artifact by comparing those two strings and can otherwise not tell which artifact's progress the file belongs to. That covers a typo such as `task.md` and also `tracks: tasks/main.md` against `generates: tasks/*.md`, where the glob does produce the file but the strings still differ. Apply reads that path as written either way, so schemas that track a hand-written file keep loading and working. Every built-in schema parses as before.
+
+- [#1856](https://github.com/Fission-AI/OpenSpec/pull/1856) [`46ff91f`](https://github.com/Fission-AI/OpenSpec/commit/46ff91f2d626ef2c3f9f55ff345aa23cd44a6e95) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Make `openspec show --json --deltas-only` report the deltas archive applies. `ChangeParser`, which backs `show --json`, the `change list` delta counts and archive's proposal warnings, read delta specs with its own section lookup instead of `parseDeltaSpec`, the reader archive uses, and the two disagreed. A REMOVED written in the bullet form (`` - `### Requirement: X` ``) was invisible to it, so it fell back to the proposal's "What Changes" prose and reported an invented MODIFIED while archive deleted the requirement; a repeated section header was read only once; and a RENAMED line written with `*` or `+` was dropped. The inspection command OpenSpec's own error text recommends therefore misreported a deletion. `ChangeParser` now derives every operation from `parseDeltaSpec`, and a change whose delta spec files carry a delta section is described by them alone, so proposal prose is never reported in place of what archive applies. Requirement text and scenarios are read exactly as before, header-form deltas produce the same output, and a change with no delta spec files, or a legacy change whose spec files carry no delta section, still falls back to the "What Changes" bullets.
+
+- [#1786](https://github.com/Fission-AI/OpenSpec/pull/1786) [`8b99c07`](https://github.com/Fission-AI/OpenSpec/commit/8b99c07bd0d455f72e746d3950f03e52a025d655) Thanks [@clay-good](https://github.com/clay-good)! - `openspec status` now names the command that moves the change forward.
+  
+  The text output reported state and stopped there, so picking a change back up (after a lost session, or on a change you did not start) meant already knowing which command came next. The JSON surface had carried that command all along in `nextSteps`; the text surface never printed it.
+  
+  Status now ends with a `Next:` line: the next ready artifact's `openspec instructions` command while planning is unfinished, and `openspec instructions apply` once every planning artifact exists. It carries `--store <id>` when the resolved root is a store, and it is built from the same source as the JSON `nextSteps` sentence, so the two surfaces cannot name different commands.
+
+- [#1882](https://github.com/Fission-AI/OpenSpec/pull/1882) [`208b5b5`](https://github.com/Fission-AI/OpenSpec/commit/208b5b55106fbeda2ed9f099671b8ce85a01cbaa) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop a store named `specs` or `changes` from taking over root selection. Stores are placed at `~/openspec/<id>`, so a store with one of those ids is itself `~/openspec/specs` or `~/openspec/changes`, and that made `$HOME` look like a planning root. Every command run anywhere under the home directory then resolved `$HOME` as the nearest root: the global `defaultStore` was never consulted, and `new change` wrote into `~/openspec/changes`, outside any store. A `specs/` or `changes/` directory that carries store metadata no longer counts as planning content of the directory above it, so these stores resolve like any other. A real project's `openspec/specs/` and `openspec/changes/` are unaffected.
+
+- [#1880](https://github.com/Fission-AI/OpenSpec/pull/1880) [`9f8dec5`](https://github.com/Fission-AI/OpenSpec/commit/9f8dec5dd937da78bbdaeff5e5dfd041bb43cf5c) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `openspec store remove` deleting a store the user did not name. Remove deletes the target's folder recursively, but it checked only the target's own metadata, so any other registered store living inside that folder was deleted with it, uncommitted planning work included, while its registry entry was left pointing at a path that no longer existed. The natural way to get there is a shared store vendored into another as a git submodule, a layout `store register` accepts. Remove now refuses when another registration points inside the folder, checked under the same registry lock that commits the removal, and the error names each nested store with the `openspec store unregister` command to run first. Removing a store whose other registrations are siblings is unchanged, and `store register` still accepts nested checkouts.
+
+- [#1884](https://github.com/Fission-AI/OpenSpec/pull/1884) [`5d22145`](https://github.com/Fission-AI/OpenSpec/commit/5d221456e57feb9277de40482fade427201b9bdb) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Let `openspec store setup --no-init-git` create a store inside an existing Git repository. Setup refuses a path inside another repository because initializing the store there would nest one repository in another, but it ran that check even with `--no-init-git`, which creates no repository at all. Users who keep their home directory as a dotfiles repository therefore could not set up a store at the recommended `~/openspec/<id>` path with any flag. With `--no-init-git` the check is now skipped, and the store never records the enclosing repository's remote. The default setup and an explicit `--init-git` still refuse a path inside another repository.
+
+- [#1862](https://github.com/Fission-AI/OpenSpec/pull/1862) [`8fc65b7`](https://github.com/Fission-AI/OpenSpec/commit/8fc65b7f70c4bd730a1dbe500cbe165d156f3c58) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Count task checkboxes under every CommonMark list marker. The task counter shared by `list`, `status`, `view`, `instructions apply`, `validate --archived` and archive's incomplete-task check recognized only `-` and `*` bullets, so a task written as an ordered item (`1. [ ]`, `1) [ ]`) or under a `+` bullet was invisible to all of them: a change with unfinished ordered tasks reported "✓ Complete", and `openspec archive` archived it without its incomplete-task warning. Task lines under `+` and ordered markers (`.` or `)`, up to nine digits, as CommonMark allows) now count exactly like `-` and `*` ones, including nested sub-tasks, CRLF files and the existing tolerance of a missing space after the marker, and task-numbering checks now see them too. Ordered and `+` items without a checkbox are still ignored, and `-` and `*` tasks count as before.
+
+- [#1777](https://github.com/Fission-AI/OpenSpec/pull/1777) [`3312af4`](https://github.com/Fission-AI/OpenSpec/commit/3312af4799eb162d3ddb7804d643ace5282c22cb) Thanks [@clay-good](https://github.com/clay-good)! - Start generated proposal, spec, design, and tasks files with a top-level heading, so artifacts are complete markdown documents instead of files whose first line is a section header. Editors that run markdownlint no longer flag every OpenSpec artifact with MD041. `openspec schema init` scaffolds custom templates the same way.
+  
+  `openspec show --json` and `openspec change list --json` keep naming a change by its id when its proposal opens with the template's bare `# Proposal` title.
+
+- [#1778](https://github.com/Fission-AI/OpenSpec/pull/1778) [`7de2404`](https://github.com/Fission-AI/OpenSpec/commit/7de24044ef4c635f634b78fa6bc4b5905967bfd8) Thanks [@clay-good](https://github.com/clay-good)! - Make the vendor-neutral tool target findable when your assistant is not on the list. `openspec init` now shows it as "Other / Universal (shared .agents skills)"; the picker's search box matches it on `universal`, `other`, `generic`, `custom`, `proprietary`, `unlisted`, `unsupported`, `vendor-neutral` and `agents.md`; a search that matches nothing points at it instead of ending at "No matches"; and `--tools <unknown>` names it in the error. The search box also accepts punctuation, so `.agents` and `amazon-q` filter instead of silently dropping their `.` and `-`.
+
+- [#1876](https://github.com/Fission-AI/OpenSpec/pull/1876) [`605d9e7`](https://github.com/Fission-AI/OpenSpec/commit/605d9e7a2bb5c1bab90268933f9b84ff1eb8807c) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop OpenSpec rewriting a global config file it cannot parse. After a hand edit left a typo such as a trailing comma in `config.json`, the next command of any kind, including read-only ones like `openspec list`, read the fallback defaults as telemetry consent, minted a new anonymous ID and wrote it back, replacing the whole file: a `telemetry.enabled false` opt-out, the chosen profile and the workflow list were all lost, and usage events were sent. A config file that exists but does not hold a JSON object, whether it failed to parse or its root is something else such as `null`, an array or a string, is now never written implicitly, and telemetry and the update check treat it as opted out. `config set`, `config unset` and `config profile` refuse with an error that names the file and points to `openspec config edit`, and `openspec config reset --all` still replaces it. The existing "Invalid JSON" warning is unchanged, and valid or missing config files behave exactly as before.
+
+- [#1840](https://github.com/Fission-AI/OpenSpec/pull/1840) [`fede536`](https://github.com/Fission-AI/OpenSpec/commit/fede536c27e03c1aaa3c17caffa837f483d9e9b9) Thanks [@clay-good](https://github.com/clay-good)! - Resolve the contradiction that left `/opsx:update`'s only write path without a governing rule. Step 4 told the agent to "Apply the requested edit", while step 5 and the guardrails told it to write only after the user confirms each revision, so the same `/opsx:update "the design now uses X"` either wrote immediately or stopped and showed the proposed revision first, depending on which passage the agent weighed. Step 4 now drafts the edit in the conversation and step 5 owns every artifact write, matching the workflow's own specified behavior: propose each revision and apply it only after user confirmation. Fixes [#1836](https://github.com/Fission-AI/OpenSpec/issues/1836).
+
+- [#1858](https://github.com/Fission-AI/OpenSpec/pull/1858) [`db560ae`](https://github.com/Fission-AI/OpenSpec/commit/db560ae33f565b76ebbc040782ec7007295e8133) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `validate` accepting a requirement whose only scenario is a bare header. The delta scenario counter counted every `####` header, while the spec path that archive uses to validate the rebuilt spec keeps a scenario only when its body has content, so `validate` called such a change valid and `archive` then refused it with a generic "Requirement must have at least one scenario" that did not name the requirement. Both paths now share one rule, `hasScenarioBody`, and read a scenario's body up to the same boundary, so `validate` rejects exactly what archive rejects, naming the requirement and saying that a header with no body under it does not count. A scenario whose body is only a fenced block or a deeper header still counts, a requirement with one real scenario is still accepted even when another is empty, and main-spec validation is unchanged.
+
+- [#1774](https://github.com/Fission-AI/OpenSpec/pull/1774) [`09984b8`](https://github.com/Fission-AI/OpenSpec/commit/09984b824254f9e35bcdf628fdb052a689a57f37) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **Task lists without checkboxes are now caught**: a `tasks.md` written as plain bullets or a numbered list counts as zero tasks, so `openspec list` and `openspec status` reported "No tasks" and `openspec archive` had no unfinished work to warn about. `openspec validate` now warns when a change's tracked task files contain list items but no checkbox at all, and points at the first offending line.
+
+- [#1852](https://github.com/Fission-AI/OpenSpec/pull/1852) [`5f5914e`](https://github.com/Fission-AI/OpenSpec/commit/5f5914e7f7a817262c7564ac92694db833564978) Thanks [@clay-good](https://github.com/clay-good)! - Match the natural "openspec <verb>" phrasing to the workflow it names. Users and agents say "openspec propose" or "do an openspec apply", but no workflow skill's description contained that phrasing (and a skill's description is what an agent matches on), so the phrase read as an invitation to hand-build the artifacts with the CLI instead of running the workflow. Every workflow skill's description now names the phrasings a user actually types ("openspec propose", "opsx apply", and so on). Run `openspec update` to pick it up. `openspec update` itself is deliberately left unclaimed: it is a real CLI command that refreshes generated files, unrelated to the update-change workflow, which claims "openspec update change" instead. Commands-only installs write no skills and are unchanged. Fixes [#1221](https://github.com/Fission-AI/OpenSpec/issues/1221).
+
+## 1.13.0
+
+### Minor Changes
+
+- [#1783](https://github.com/Fission-AI/OpenSpec/pull/1783) [`8ba4ac1`](https://github.com/Fission-AI/OpenSpec/commit/8ba4ac1b16a33830a766f0c03d224d516b6a90ce) Thanks [@clay-good](https://github.com/clay-good)! - Apply now says when a change has no delta specs. Apply gates on the schema's `apply.requires` alone, so a change whose `tasks.md` was written ahead of its specs read as ready to implement even though it had no spec deltas at all — the state `openspec validate` rejects. `openspec instructions apply` now reports that gap as a warning (text and `--json`), naming both ways out: write the specs, or declare `skip_specs: true`. Changes that have specs, declare `skip_specs`, or are still blocked on their own required artifacts are unaffected.
+  
+  A blocked apply also names the whole chain now, not just the first hop: a change holding only a proposal reported `Missing artifacts: tasks` while the specs that `tasks` depends on were missing too, which reads as an instruction to write the tracking file straight from the proposal. The full build order is reported as `missingPrerequisites` in `--json`. The remedies these messages give are CLI commands (`openspec instructions <artifact> --change <name>`) rather than the `openspec-continue-change` skill, which the `core` profile never installs.
+
+### Patch Changes
+
+- [#1798](https://github.com/Fission-AI/OpenSpec/pull/1798) [`aedf4d0`](https://github.com/Fission-AI/OpenSpec/commit/aedf4d0c64c4bdde2e21f199aee93fa0d598c33e) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archive rewriting the inside of fenced code blocks. The final assembly in `buildUpdatedSpec` collapsed runs of blank lines across the whole rebuilt document to tidy the seams between the slices it rejoins, but the pass was not fence-aware, so a requirement documenting a sample with two or more consecutive blank lines had that sample silently edited on archive, and edited again on every later archive. That matters wherever whitespace carries meaning: YAML block scalars, Python, expected-output fixtures, Markdown inside Markdown. Blank runs are now collapsed only outside fenced blocks, using the same `buildCodeFenceMask` every other structural pass in the module already used. Behavior outside fences is unchanged, including that only a truly empty line counts as blank, so a line of spaces is still never a collapse boundary. Fixes [#1797](https://github.com/Fission-AI/OpenSpec/issues/1797).
+
+- [#1800](https://github.com/Fission-AI/OpenSpec/pull/1800) [`fadac3e`](https://github.com/Fission-AI/OpenSpec/commit/fadac3e1c927bf5180ce82c806435c61db5d5adb) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Read a removal or rename written with `*` or `+` as the operation it is. CommonMark opens a bullet list with `-`, `*` or `+`, but the bullet form of `## REMOVED Requirements` and the `FROM:`/`TO:` lines of `## RENAMED Requirements` both hardcoded `-`, so either other marker matched nothing at all. The operation then silently never happened: `openspec validate` reported the change valid, `openspec archive` exited 0 with "Specs updated successfully", and the requirement that was supposed to be deleted or renamed stayed exactly as it was. The change archived as complete, leaving the spec quietly disagreeing with the delta that was meant to update it. Both forms now accept `[-*+]`, the `FROM:`/`TO:` bullet stays optional, and the plain `### Requirement:` header form is unchanged. Fixes [#1799](https://github.com/Fission-AI/OpenSpec/issues/1799).
+
+- [#1802](https://github.com/Fission-AI/OpenSpec/pull/1802) [`8251763`](https://github.com/Fission-AI/OpenSpec/commit/8251763ecdc349a0a1484f09da85f7e5c33f4836) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Apply every delta section, not just one copy of each. A delta file that wrote the same header twice, two `## ADDED Requirements` sections say, silently kept one of them: sections were collected into a record keyed by title, so a repeated title overwrote the earlier body, and the case-insensitive lookup returned only the first entry that folded to the target, so `## ADDED Requirements` beside `## Added Requirements` left the second unread. Every requirement under the discarded copy was gone before validation or the merge could see it, so `openspec validate` reported zero issues and `openspec archive` exited 0 having applied less than the author wrote, then moved the change to the archive with the live spec quietly diverging from what was reviewed. Sections are now kept as a list and every body whose title matches is read, each keeping its own line numbers so diagnostics still point at the right copy. Rename pairs are read per section, so a `FROM:` in one copy of the header can never pair with a `TO:` in another. An author does not have to repeat a header on purpose to hit this: a delta documenting OpenSpec's own syntax inside a fenced example produces the duplicate on its own. Fixes [#1801](https://github.com/Fission-AI/OpenSpec/issues/1801).
+
+- [#1657](https://github.com/Fission-AI/OpenSpec/pull/1657) [`6d2dbe6`](https://github.com/Fission-AI/OpenSpec/commit/6d2dbe62d3386ac0df576136759775678102acf2) Thanks [@clay-good](https://github.com/clay-good)! - Load project context before proposal planning, using the selected project or store root and honoring config precedence and validation limits. When no root exists, stop without writing files and offer initialization instead of creating an implicit root.
+
+- [#1700](https://github.com/Fission-AI/OpenSpec/pull/1700) [`3915db7`](https://github.com/Fission-AI/OpenSpec/commit/3915db763ad5394b29cdd895c87a91c837313ae8) Thanks [@clay-good](https://github.com/clay-good)! - Teach the generated guidance how to find and read a project's specs. `openspec list --specs` appeared in no generated skill, command, or artifact instruction, while `openspec list --json` (the in-flight *change* list) appeared throughout, so an agent asked to read the existing specs first enumerated changes instead and reported the step complete against the wrong object. The explore skill and command now list the spec inventory alongside the change list and say which is which, and the spec-driven `proposal` and `specs` instructions name the command where they ask for existing capabilities to be researched and for a delta's path to match an existing one. Both steps carry `--store "<id>"`, and capabilities are read with `openspec show "<spec-id>" --type spec --json --no-scenarios` so the read resolves against the same root the listing came from. Fixes [#1689](https://github.com/Fission-AI/OpenSpec/issues/1689).
+  
+  The filtered read is only an overview. Agents read relevant specs in full, including scenarios, before deciding what is already covered or what should change.
+
+- [#1779](https://github.com/Fission-AI/OpenSpec/pull/1779) [`3c6d318`](https://github.com/Fission-AI/OpenSpec/commit/3c6d318b837f443d1aabf969ce368e78ae12e891) Thanks [@clay-good](https://github.com/clay-good)! - `openspec init` and `openspec update` now name the workflows your profile left out and how to add them, so a command that was never installed no longer reads as a broken setup.
+
+- [#1808](https://github.com/Fission-AI/OpenSpec/pull/1808) [`d9e1a28`](https://github.com/Fission-AI/OpenSpec/commit/d9e1a28c38927e6d649781976cd1a753e28973af) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `openspec update` reporting a tool up to date while a damaged command file sits on disk. The check read the `generatedBy` version marker in a tool's skill files alone, which proves only that the skill files came from this CLI and says nothing about the command files written beside them, so a hand-edited or truncated command file left update printing "All 1 tool(s) up to date" and repairing nothing; the file could be restored only by knowing to pass `--force`. A deleted command file was already detected, so the claim was false only for a damaged one. Update now also compares command-file content, using the comparison that already existed and was simply never consulted once a skill file supplied a version. Scoped to tools configured for both skills and commands, so the commands-only path is unchanged, and skipped when the delivery mode generates no commands for the tool. Fixes [#1807](https://github.com/Fission-AI/OpenSpec/issues/1807).
+
+- [#1782](https://github.com/Fission-AI/OpenSpec/pull/1782) [`c170dc7`](https://github.com/Fission-AI/OpenSpec/commit/c170dc77adbe868ce731e07df2806a7ca8fcb4ec) Thanks [@clay-good](https://github.com/clay-good)! - Fix `retire_capabilities` refusing any spec whose scenario bullets wrap onto a second line. The continuation line was counted as content the merge could not account for, which blocked the retirement and suppressed the hint that names the marker ([#1780](https://github.com/Fission-AI/OpenSpec/issues/1780)). A spec bulleted with `+` is covered too: naming only `-` and `*` as list markers reported every one of its scenario bullets as unaccounted content, so that capability could not be retired at all either.
+
+## 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

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Thanks for helping improve OpenSpec.
+
+## 1. Open a discussion or an issue first
+
+Every change starts here, including small ones.
+
+- [Start a discussion](https://github.com/Fission-AI/OpenSpec/discussions) if it affects OpenSpec's core design.
+- [Open an issue](https://github.com/Fission-AI/OpenSpec/issues) for bugs and everything else.
+
+This is so we can agree on the approach before you spend time building. PRs without a linked issue or a prior discussion may be closed.
+
+## 2. Decide whether it needs a change proposal
+
+A bug fix, a typo, or a small improvement goes straight to a PR.
+
+A new feature, a significant refactor, or anything that changes OpenSpec's architecture needs an OpenSpec change proposal first, so we can align on intent and goals before implementation begins. Open it as a PR containing only `openspec/changes/<name>/` and wait for it to be approved before you write the code.
+
+When writing a proposal, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
+
+If you are not sure which side of the line your change falls on, ask in the discussion or issue from step 1.
+
+## 3. Make your change
+
+You need Node 20.19+ and pnpm.
+
+```bash
+pnpm install
+pnpm build              # tests run against the build output
+pnpm test
+pnpm exec tsc --noEmit
+pnpm lint
+```
+
+Those four commands are what CI runs, so a green local run means a green CI run.
+
+Run `pnpm changeset` if your change affects users, and commit the file it generates.
+
+## 4. Open the PR
+
+- Branch off `main` in your fork.
+- Title it as a conventional commit: `type(scope): subject`, for example `fix(archive): keep authored Purpose`.
+- Link what you opened in step 1: `Closes #123` for an issue, or a link to the discussion when there is no issue.
+- If a coding agent wrote the code, say which agent and model, and confirm you tested it. AI-generated code is welcome when it has been verified.
+
+Maintainers are listed in [MAINTAINERS.md](MAINTAINERS.md).

README.md

@@ -122,7 +122,7 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.**
+**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
 
 Install OpenSpec globally:
 
@@ -130,6 +130,12 @@ Install OpenSpec globally:
 npm install -g @fission-ai/openspec@latest
 ```
 
+Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+
+```bash
+brew install openspec
+```
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -137,11 +143,11 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 Now talk to your AI:
 
-- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Explore guide](docs/explore.md))
 - **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
 
 Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
@@ -151,7 +157,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
 >
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
 
 ## Docs
 
@@ -172,6 +178,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
 
 
@@ -207,6 +214,12 @@ AI coding assistants are powerful but unpredictable when requirements live only
 npm install -g @fission-ai/openspec@latest
 ```
 
+If you installed OpenSpec with Homebrew:
+
+```bash
+brew upgrade openspec
+```
+
 **Refresh agent instructions**
 
 Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
@@ -223,21 +236,9 @@ openspec update
 
 ## Contributing
 
-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+Open a discussion (for core design changes) or an issue before you open a PR, and link the issue or discussion from the PR. New features, significant refactors, and architectural changes need an OpenSpec change proposal first.
 
-**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
-
-When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
-
-**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
-
-### Development
-
-- Install dependencies: `pnpm install`
-- Build: `pnpm run build`
-- Test: `pnpm test`
-- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
-- Conventional commits (one-line): `type(scope): subject`
+→ **[CONTRIBUTING.md](CONTRIBUTING.md)**: the full process, from first issue to merged PR
 
 ## Other
 

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 in a new or existing project, 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,122 @@
+# 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.
+
+## 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. Keep the `#` title on the first line: the artifact inherits it, so every generated file opens as a titled document.
+- **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,24 @@
+# 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 **Other / Universal** (`--tools agents`), covered by the support
+matrix's Other / Universal section. 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. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
+
+### 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.
+
+### 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.
+
+## 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,97 @@
+# 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` | map: tool id → settings | No | The tools worksets open in, and how each is launched |
+| `telemetry` | map | No | Telemetry opt-out, anonymous id, and notice-seen state |
+
+### 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, keyed by tool id. Edit `openers` in the global `config.json` with `openspec config edit` in your terminal.
+
+| Field | Contract |
+| --- | --- |
+| `style` | `workspace-file` or `attach-dirs`. Required for a new tool; optional for a built-in. |
+| `label` | Non-empty string shown in the tool picker. Defaults to the id for a new tool. |
+| `command` | Non-empty executable name or path. Defaults to the id for a new tool. Put arguments in `args`, not in this string. |
+| `args` | Array of strings passed before the workspace file or attach flags. Defaults to `[]` for a new tool. |
+| `attach_flag` | Non-empty string paired with each member path for `attach-dirs`. Defaults to `--add-dir` for a new tool. Ignored for `workspace-file`. |
+
+**Built-in overrides:** `code`, `cursor`, `claude`, and `codex` retain any fields you omit. Setting `args` replaces the entire argument list; `[]` clears it.
+
+**Launch styles:** `workspace-file` passes the generated `.code-workspace` path to the executable. `attach-dirs` passes one flag/path pair per member, including the primary member.
+
+**Availability:** `attach-dirs` openers, including Claude Code and Codex, are disabled by default. You cannot select or save them with `--tool`, and OpenSpec refuses to open a workset that already names one. Configuration overrides do not enable the `attach-dirs` launch style.
+
+**Validation:** unknown fields, invalid types, and a new tool without `style` fail when a workset command reads the opener table.
+
+This example adds VS Code Insiders and passes `--new-window` whenever the built-in VS Code opener launches:
+
+```json
+{
+  "openers": {
+    "code-insiders": {
+      "style": "workspace-file",
+      "label": "VS Code Insiders"
+    },
+    "code": {
+      "args": ["--new-window"]
+    }
+  }
+}
+```
+
+The corresponding `code-insiders` or `code` executable must be installed and available on `PATH`.
+
+### telemetry
+
+The CLI stores your anonymous id and whether the first-run notice was shown. Set `telemetry.enabled` to `false` to disable telemetry. You can also opt out with `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` in your environment.
+
+## 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. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
+
+### 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 | 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. The last column links to more detail where available.
+
+| Term | Definition | More |
+|---|---|---|
+| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](skills.md#openspec-apply-change) |
+| **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. | [Artifacts](schemas/spec-driven/index.md#artifacts) |
+| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Capabilities](schemas/spec-driven/index.md#proposalmd) |
+| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Propose](../start/quickstart.md#step-2-propose) |
+| **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](skills.md#openspec-explore) |
+| **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. |  |
+| **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. A capability with no spec yet gets one from its `ADDED` requirements. | [Archive](../start/quickstart.md#step-5-archive) |
+| **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:`). |  |
+| **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`. | [Archive](../start/quickstart.md#step-5-archive) |
+| **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. | [Update a change](skills.md#openspec-update-change), [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,228 @@
+# 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 recognizes these glob forms in `generates`:
+
+- **Wildcards and character classes**: values containing `*`, `?`, or `[`, such as `specs/**/*.md` and `review-[ab].md`.
+- **Brace expansions**: alternatives such as `review-{api,ui}.md` and ranges such as `file-{1..3}.md`.
+- **Extglobs**: patterns such as `@(proposal|design).md`, `+(proposal|design).md`, and `!(proposal|design).md`.
+
+**Literal filenames**: a leading `!` alone does not make a glob. Use `generates: '!review.md'` to name that file. Plain parentheses such as `(proposal|design).md` and single-element braces such as `review-{api}.md` also remain literal.
+
+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 or glob for Markdown task files 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
+```
+
+A glob such as `tracks: "**/tasks.md"` reads every matching file, such as `backend/tasks.md` and `frontend/tasks.md`. OpenSpec combines their tasks and progress. Use the same value for an artifact's `generates` field so status and list track the same files.
+
+Apply stays blocked if no file matches or the matched files contain no checkbox with task text. OpenSpec counts these checkbox forms:
+
+```markdown
+- [ ] Pending task
+- [x] Completed task
+* [X] Completed task
++ [ ] Pending task
+1. [ ] Pending task
+2) [x] Completed task
+```
+
+Any Markdown list marker works: `-`, `*`, `+`, or a number of up to nine digits followed by `.` or `)`. 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 files drive the apply state:
+
+- **`blocked`**: no file matches, or no readable file has a checkbox with task text.
+- **`ready`**: at least one task is pending, or a matched file could not be read while another provides tasks.
+- **`all_done`**: every tracked task is checked and every matched file was read.
+
+If a matched file cannot be read, apply keeps the tasks and progress from readable files but does not mark the change `all_done`. [Apply JSON output](../cli.md#openspec-instructions) identifies each unavailable file and the reason.
+
+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
+- `apply.requires` IDs: each must be an artifact in the schema
+- Template files
+
+A schema with an unknown `apply.requires` ID doesn't load, so every command that uses it reports the error.
+
+Validation warns, without failing, when `apply.tracks` isn't exactly equal to some artifact's `generates` value. OpenSpec finds the tracked artifact by comparing those two strings, so anything else leaves it unable to tell which artifact's progress the file belongs to. That includes a typo like `task.md`, and also `tracks: tasks/main.md` against `generates: tasks/*.md`, where the glob does produce the file but the strings still differ. Apply keeps reading the file either way, but `openspec list` and `openspec status` count `tasks.md` instead.
+
+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. |
+| `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,476 @@
+# 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
+# Proposal
+
+## 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:
+run `openspec list --specs` for the project's capability inventory, then
+`openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+look related - that returns a capability's purpose and requirement texts
+without pulling whole spec files into context. Append `--store "<id>"` to
+both commands only for a registered standalone store, and keep `--type
+spec`: a change and a spec sharing a name is otherwise an ambiguous-item
+error. `openspec list` without `--specs` lists in-flight changes, not
+specs - it never shows what the project already covers. Reuse an existing
+capability's exact path instead of introducing a near-duplicate name.
+The filtered read is only an overview. Before deciding what is already
+covered or what should change, read each relevant spec in full, including
+scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
+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.
+
+Each delta spec is the `spec.md` inside its capability folder. `openspec validate` and `openspec archive` reject delta sections written in any other file under `specs/`, such as `specs/user-auth.md`, because archive never merges them.
+
+### 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
+# Spec Delta
+
+## 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`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. 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: the delta spec's first section is `## Purpose` -
+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 `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
+directly. `planningHome.root` comes from the `openspec instructions ...
+--json` response. Always use it rather than a repo-relative path: it
+resolves to the store whenever the change lives in one - whether that
+came from `--store`, a project `store:` pointer, or a global default
+store - and to the current repository otherwise. Do not try to work out
+which case applies; the field already has.
+
+MODIFIED requirements workflow:
+1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
+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 its first section is `## Purpose`):
+```
+# Spec Delta
+
+## 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
+# Design
+
+## 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
+# Tasks
+
+## 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. A box holding only `x` counts as done,
+upper or lower case and with any spacing, so `- [ x]` is done too. Every
+other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
+unfinished. A line with no checkbox is not tracked at all.
+
+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?)
+- Each task MUST state how to verify completion (a test, command,
+  observable behavior, or delivered artifact). Put the verification in
+  that task's checkbox description. Use a separate verification task only
+  when it checks broader integration or system behavior that spans
+  multiple implementation tasks.
+- Each task group MUST land the tests and documentation its own work
+  calls for. Do NOT collect testing or documentation into a final group -
+  when a late group first exercises work from an early one, the failures
+  cascade back through every group in between and force rework. A group
+  whose work calls for neither, such as scaffolding or dependency setup,
+  carries neither. A final group is for integration checks only, not for
+  the tests and docs an earlier group owed.
+
+Example:
+```
+# Tasks
+
+## 1. Setup
+
+- [ ] 1.1 Create new module structure and verify expected files are present
+- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
+
+## 2. Core Implementation
+
+- [ ] 2.1 Implement data export function and verify the export test passes
+- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+- [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
+```
+
+Reference specs for what needs to be built, design for how to build it.
+````
+
+## 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,185 @@
+# 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).
+
+Every skill expects a project that already uses OpenSpec. Before its first step that writes anything, a skill checks for a resolved root. What happens when there is none depends on how the skill was reached:
+
+- **Auto-selected**: your agent picked the skill on its own, without you naming OpenSpec. It drops OpenSpec and answers your request normally, the way it would with OpenSpec not installed.
+- **Explicit OpenSpec request**: you named OpenSpec, named the skill, or ran its command. It stops before writing and asks how to proceed: run `openspec init` here, target a store with `--store <id>`, or continue without OpenSpec. It waits for your answer.
+
+Commands are always the second case. A project whose `openspec/config.yaml` names a store this machine cannot resolve (not registered, or a malformed `store:` line) is not treated as uninitialized: the skill stops and shows the store error with its fix. No skill creates an `openspec/` directory on its own in either case. The entries below describe what each skill does once a root is in place.
+
+| 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 |
+
+Each entry below names the skill that owns the next step. When your profile leaves that skill out, the installed files never name it: the handoff becomes the equivalent `openspec` command, or a plain request to you, and a line that exists only to point at a missing skill is not written at all. So the skills you have always hand off to skills you have. Which set you get is [Profiles](../customize/profiles.md).
+
+## 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`, or to `openspec status` and `openspec instructions` when that skill is not installed (the core profile leaves it out). 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** | Edits artifact files that already exist. One exception: for an artifact written as a glob, such as `specs/**/*.md`, that already has at least one file, it can add a missing companion file once you confirm the path. An artifact with no files yet is `openspec-continue-change`'s job. Without that skill (the core profile leaves it out), it points to `openspec status` and `openspec instructions` instead. 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,144 @@
+# 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` | `.kilo/command/` | `/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` |
+| Other / Universal | `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
+
+- **CLI and IDE extension**: mention `$openspec-propose` with your idea, or run
+  `/skills` to select the skill. Codex does not recognize `/openspec-propose`
+  ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **Desktop app**: open Skills in the sidebar and select `openspec-propose`.
+  [OpenAI's skills documentation](https://learn.chatgpt.com/docs/build-skills)
+  describes both interfaces.
+- **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
+
+- **IDE extensions (command delivery)**: VS Code, JetBrains, and Visual Studio load
+  `.github/prompts/opsx-<id>.prompt.md` as `/opsx-<id>`. If a command disappears
+  while its file still exists, restart the IDE.
+- **Copilot CLI (skill delivery)**: the CLI ignores `.github/prompts/` and loads
+  `.github/skills/openspec-*/SKILL.md` instead. Invoke a skill as
+  `/openspec-<skill>`. If a skill disappears while its file still exists, run
+  `/skills reload`, then `/skills info openspec-propose` to confirm discovery.
+
+### 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.
+
+### Other / Universal (shared `.agents` skills)
+
+- **When it fits**: any tool that reads the shared `.agents/skills/` folder,
+  including tools with no row in the matrix. It is the entry to pick when your
+  assistant is not listed. The init picker's search box finds it by `universal`,
+  `other`, `generic`, `custom`, `proprietary`, `unlisted`, `unsupported`,
+  `vendor-neutral`, or `agents.md`.
+- **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,168 @@
+# Installation
+
+> Install the `openspec` CLI on your machine, update it, and uninstall it.
+
+
+## Prerequisites
+
+OpenSpec runs on Node.js 20.19.0 or newer. Homebrew installs Node.js as a
+dependency, and the Nix package includes the runtime. Check your installed version
+before using another install method.
+
+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). You can skip this check when you install with Homebrew or Nix.
+
+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
+```
+
+### Homebrew
+
+Homebrew installs OpenSpec and its Node.js dependency on macOS or Linux. In your terminal:
+
+```bash
+brew install openspec
+```
+
+The formula is published in [homebrew-core](https://formulae.brew.sh/formula/openspec), so you don't need to add a tap.
+
+### 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.
+
+The Nix package ships the Bash, Fish, and Zsh completion scripts at the standard
+locations (`share/bash-completion/completions`, `share/fish/vendor_completions.d`,
+`share/zsh/site-functions`), so they load with the package and there is no need to run
+`openspec completion install`.
+
+### 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 Homebrew, run `brew upgrade openspec`. 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 Homebrew: `brew uninstall 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,174 @@
+# Quickstart
+
+> Your first change, from idea to archived, in a new or existing project.
+
+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)).
+
+## Start from an empty project
+
+You can start without a chosen stack or a complete architecture. Initialize OpenSpec in your project folder, then ask your agent to explore the options with you. In your AI chat:
+
+```text
+Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.
+```
+
+Decide what the first change needs and leave later architecture choices open. Ask your agent to propose that one change, then follow the steps below. You can revisit the architecture as the project grows.
+
+## 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. The examples use plain language so they work across tools. You can also invoke a skill directly; the syntax varies by tool ([supported tools](../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
+Help me 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 never writes code. It writes nothing else unless you ask it to capture what you decided, or say yes when it offers. The output is a sharper idea.
+
+Stay here as long as the problem needs. When the shape feels right, hand it off:
+
+```text
+Propose the change we just discussed.
+```
+
+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
+Propose a change to 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
+Apply the add-rate-limiting change.
+```
+
+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
+Archive the add-rate-limiting change.
+```
+
+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.
+
+## Going further
+
+- [Delta specs](../reference/schemas/spec-driven/index.md#delta-specs-specmd): how to write the behavior changes in a delta spec.
+- [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,137 @@
+# 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. 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
+```
+
+[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.
+
+#### Claude Code doesn't show the workflows
+
+Claude Code loads OpenSpec workflows from one or both of these project paths, based on your delivery setting:
+
+- **Skills**: `.claude/skills/openspec-*/SKILL.md`
+- **Commands**: `.claude/commands/opsx/<id>.md`
+
+If the files are missing, refresh the project. In your terminal:
+
+```bash
+openspec update
+```
+
+If the command files exist but `/opsx:` shows no OpenSpec commands, update Claude Code and restart it. If commands still don't load, enable skills too. In your terminal:
+
+```bash
+openspec config set delivery both
+openspec update
+```
+
+Restart Claude Code, then run `/openspec-propose` in its chat. If only some workflows are missing, [change your profile](../customize/profiles.md#expanding-the-set-optional-workflows).
+
+Setup is done. The [Quickstart](quickstart.md) takes your first change from here.

docs/README.md

@@ -11,7 +11,7 @@ If you read nothing else, read these two pages:
 
 That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
 
-> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
+> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any code gets written. The [Explore First](explore.md) guide makes the case.
 
 ## Pick your path
 
@@ -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

@@ -47,7 +47,9 @@ deliberately remains the compatibility bare array documented in §4.13:
 ## 4. Command JSON shapes
 
 ### 4.1 `list --json`
-`{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput }` — note the per-change `status` is a string enum here. `--specs`: `{ "specs": [ { "id", "requirementCount" } ], "root" }`.
+`{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress", "nested"?: ["<area>/<name>", ...] } ], "warnings"?: [ { "code", "name", "nested", "message" } ], "root": RootOutput }` — note the per-change `status` is a string enum here. `--specs`: `{ "specs": [ { "id", "requirementCount" } ], "root" }`.
+
+`warnings` (omitted when empty) reports directories under `changes/` that are not changes. Today the only code is `nested_change_directory`: a namespace folder wrapping change directories, which OpenSpec cannot address because a change is always a directory directly under `changes/`. The same entry carries `nested` on the listed change, whose `status` is then meaningless. Do not treat such an entry as a change; report the message and leave the directories alone.
 
 ### 4.2 `show <item> --json`
 Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }`.
@@ -58,13 +60,15 @@ Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id
 ### 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" }, "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.
 
 `ReferenceIndexEntry`: `{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] }` — resolved entries carry root/specs/fetch; unresolved carry store_id + warning status. Index capped at 50KB (`reference_index_truncated`).
 
 ### 4.6 `instructions apply --json`
-`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }`. Both optional fields are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
+`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "missingPrerequisites"?, "warnings"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }`. `missingArtifacts` is what apply blocks on (the schema's `apply.requires`); `missingPrerequisites` is everything still to build before apply can run, in build order - the transitive closure of those requires, so it can be the longer list. `warnings` lists non-blocking problems with the change itself - today, a change that is ready to implement with no delta specs and no `skip_specs: true`, the state `openspec validate` rejects. Both optional root fields (`context`, `operationGuidance`) are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
 
 ### 4.7 `instructions archive --json`
 `{ "changeName", "context"?, "operationGuidance"?, "root" }`. Requires a valid `--change` in the resolved repo/store root and uses the same required-context/advisory-guidance semantics as apply. This is a read-only runtime-input surface: it does not return the static archive workflow, inspect or merge delta specs, write main specs, or move the change.
@@ -108,7 +112,7 @@ setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, regis
 `invalid_store_id`, `invalid_store_registry`, `invalid_store_metadata`, `store_registry_busy`, `store_not_found`, `no_store_registry`, `store_registry_changed`, `store_metadata_missing`, `store_metadata_id_mismatch`, `store_metadata_invalid`, `store_id_conflict`, `store_path_conflict`, `store_already_registered` (info).
 
 ### Store setup/register/remove
-`store_setup_id_required`, `store_setup_path_required`, `store_setup_path_not_directory`, `store_setup_inside_git_repo`, `store_setup_non_empty_directory`, `store_setup_cancelled`, `store_path_required`, `store_path_missing`, `store_path_not_directory`, `store_root_pointer_declared`, `store_register_root_unhealthy`, `store_register_identity_confirmation_required`, `store_register_cancelled`, `store_remote_empty`, `store_remote_requires_hand_edit`, `store_remove_confirmation_required`, `store_remove_cancelled`, `store_remove_path_not_directory`, `store_remove_metadata_missing`, `store_root_missing` (warning in remove, error in doctor), `store_root_not_directory`.
+`store_setup_id_required`, `store_setup_path_required`, `store_setup_path_not_directory`, `store_setup_inside_git_repo`, `store_setup_non_empty_directory`, `store_setup_cancelled`, `store_path_required`, `store_path_missing`, `store_path_not_directory`, `store_root_pointer_declared`, `store_register_root_unhealthy`, `store_register_identity_confirmation_required`, `store_register_cancelled`, `store_remote_empty`, `store_remote_requires_hand_edit`, `store_remove_confirmation_required`, `store_remove_cancelled`, `store_remove_path_not_directory`, `store_remove_metadata_missing`, `store_remove_contains_registered_store`, `store_root_missing` (warning in remove, error in doctor), `store_root_not_directory`.
 
 ### Store git
 `store_git_init_failed`, `store_git_identity_missing`, `store_git_commit_failed`, `store_git_no_commits` (warning), `store_clone_fragile_directories` (warning), `store_remote_divergence` (info, doctor), `store_checkout_drift` (info, doctor).

docs/cli.md

@@ -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,6 +103,7 @@ 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 |
@@ -109,7 +114,7 @@ openspec init [path] [options]
 
 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`, `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`, `trae`, `zcode`, `agents`
+**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.
 
@@ -659,6 +664,25 @@ openspec archive add-dark-mode --yes
 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`)
@@ -1204,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.
 
@@ -1250,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
@@ -1278,6 +1328,7 @@ openspec completion uninstall
 | `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

@@ -78,7 +78,7 @@ AI:  Created openspec/changes/add-dark-mode/
 
 ### `/opsx:explore`
 
-> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
+> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any code gets written. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
 
 Think through ideas, investigate problems, and clarify requirements before committing to a change.
 
@@ -97,6 +97,7 @@ Think through ideas, investigate problems, and clarify requirements before commi
 - Investigates the codebase to answer questions
 - Compares options and approaches
 - Creates visual diagrams to clarify thinking
+- Captures the exploration when you ask, or when you say yes to its offer: scaffolds a change with `openspec new change` and writes the planning artifacts you name, or updates an existing change's artifacts
 - Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
 
 **Example:**
@@ -119,14 +120,20 @@ AI:  Let me investigate your current auth setup...
 
      Your API already has CORS configured. Which direction interests you?
 
-You: Let's go with JWT. Can we start a change for that?
+You: Let's go with JWT.
 
-AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
+AI:  That's a decision worth keeping. Want me to start a change called
+     add-jwt-auth? Just the change folder, nothing else yet.
+
+You: Yes.
+
+AI:  Started openspec/changes/add-jwt-auth/. Say the word and I'll
+     write the proposal, specs, and tasks from what we just worked out.
 ```
 
 **Tips:**
 - Use when requirements are unclear or you need to investigate
-- No artifacts are created during exploration
+- It never writes code, and writes nothing else unless you ask, or say yes when it offers
 - Good for comparing multiple approaches before deciding
 - Can read files and search the codebase
 
@@ -345,7 +352,13 @@ Revise a change's existing planning artifacts and keep them coherent with one an
 - Applies your requested revision, or reviews the artifacts for contradictions if you didn't name one
 - Reconciles the other existing artifacts in any direction (a design edit may ripple back to the proposal)
 - Confirms every edit with you before writing, one artifact at a time
-- Ends by recommending the next step: `/opsx:continue` (artifacts missing), `/opsx:apply` (carry a revised plan into code), or `/opsx:archive` (all done)
+- Ends by recommending the next step: `/opsx:continue` (unstarted artifacts), `/opsx:apply` (carry a revised plan into code), or `/opsx:archive` (all done)
+
+**Missing files:**
+
+- For a glob artifact such as `specs/**/*.md` with at least one existing file, update can propose a missing companion file. It uses the schema's instructions and asks you to confirm the concrete path before creating it.
+- Artifacts with no files yet remain with `/opsx:continue`. Intentionally skipped artifacts stay untouched.
+- New files must stay inside the change directory. If a file appears at the confirmed path before creation, update stops instead of overwriting it.
 
 **Example:**
 
@@ -366,7 +379,7 @@ AI:  Reading add-dark-mode artifacts...
 
 **Tips:**
 
-- It won't create missing artifacts - that's `/opsx:continue`
+- It won't start an artifact with no existing files. Enable `/opsx:continue` for that, or use `openspec status` and `openspec instructions` if that optional workflow isn't installed.
 - If the change was already implemented, follow up with `/opsx:apply` so the code matches the revised plan
 - If your revision changes the *intent* of the change, start fresh with a new change instead (see [When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh))
 
@@ -673,7 +686,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, MiniMax Code, Mistral Vibe, shared `.agents` |
+| 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,20 @@
+# 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 Workbench](https://github.com/VeryComplexAndLongName/OpenSpec-UI)**: Running and supervising agents on OpenSpec changes.
+- **[openspec-guard](https://github.com/guillaume-flambard/spec-guard)**: CLI and GitHub Action that reports which OpenSpec scenarios are covered by a Vitest or Jest test, without running the tests.
+
+## 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

@@ -341,6 +341,8 @@ Tasks are the **implementation checklist** — concrete steps with checkboxes.
 - Group related tasks under headings
 - Use hierarchical numbering (1.1, 1.2, etc.)
 - Keep tasks small enough to complete in one session
+- State how each task is verified (a test, command, or observable result)
+- Land the tests and documentation each group's work calls for inside that group, not in a final catch-up group
 - Check tasks off as you complete them
 
 ## Delta Specs

docs/examples.md

@@ -68,7 +68,7 @@ Tip: for a fix, a good scenario is the regression test in prose. "GIVEN a logged
 
 **When to use it:** you have a problem but not yet a plan. You're not sure what to build, or which approach is right.
 
-Start with `/opsx:explore`. It's a thinking partner with no structure and no artifacts created. It reads your codebase and helps you decide.
+Start with `/opsx:explore`. It's a thinking partner with no structure. It never writes code, and writes nothing else unless you ask it to capture what you decided, or say yes when it offers. It reads your codebase and helps you decide.
 
 ```text
 You: /opsx:explore

docs/explore.md

@@ -1,6 +1,6 @@
 # Explore First
 
-**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a single artifact or line of code is created. When the picture is clear, it hands off to `/opsx:propose`.
+**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a line of code is written. When the picture is clear, it hands off to `/opsx:propose`.
 
 If you take one habit from these docs, take this one: **when you're not sure, explore before you propose.**
 
@@ -27,14 +27,16 @@ Explore is a **conversation**, not a generator.
 - Compare options and name the tradeoffs of each.
 - Draw diagrams to make a design legible.
 - Help you narrow a vague idea into a concrete, buildable scope.
+- Capture the exploration when you ask, or when you accept its offer: it scaffolds the change with `openspec new change` and writes the planning artifacts you named, or updates an existing change's artifacts.
 - Transition to `/opsx:propose` when you're ready.
 
 **It does not:**
-- Create a change folder.
-- Write any artifacts (no proposal, specs, design, or tasks).
-- Write or modify code.
+- Write or modify code. Explore never writes code, on any path, capture included.
+- Design or edit your schemas or templates. Shaping those is a change, not thinking.
+- Start a change or write an artifact on its own. It writes nothing unless you ask, or say yes when it offers, and then only what you agreed to, plus the setup files starting a change needs (see below).
+- Push you toward capturing. It offers when the thinking crystallizes; you decide.
 
-That's the point. Exploring costs you nothing and commits you to nothing. You can explore three dead ends, learn something from each, and only then propose the path that survived.
+That's the point. Exploring costs you nothing and commits you to nothing until you say so. You can explore three dead ends, learn something from each, and only then propose the path that survived.
 
 ## It's already installed
 
@@ -95,6 +97,10 @@ explore  ──►  propose  ──►  apply  ──►  archive
 
 You can say it in plain language ("let's turn this into a change") or run `/opsx:propose <name>` directly. Either way, the exploration you just did becomes the foundation of the proposal, not throwaway chat.
 
+You can also ask explore to capture the change itself, without leaving the conversation: "start a change for this" scaffolds the folder, and "write the proposal too" writes exactly the artifacts you named. Scaffolding also lays down the change's own metadata, and fills in anything your project is missing at the top level (`openspec/specs/`, `openspec/changes/archive/`, a `config.yaml`).
+
+That's the same destination as handing off, with one difference: propose writes the whole set your schema requires to reach implementation, while capture writes only the artifacts you named.
+
 If you use the expanded command set, explore can hand off to `/opsx:new` instead, for step-by-step artifact creation. See [Workflows](workflows.md).
 
 ## Tips for a good exploration
@@ -107,7 +113,7 @@ If you use the expanded command set, explore can hand off to `/opsx:new` instead
 
 ## The honest tradeoffs
 
-**What you gain:** explore catches wrong turns at the cheapest possible moment, before any artifact exists. It's especially powerful in unfamiliar code, where the AI's ability to read and summarize the system saves you an afternoon of spelunking.
+**What you gain:** explore catches wrong turns at the cheapest possible moment, before you've committed to anything. It's especially powerful in unfamiliar code, where the AI's ability to read and summarize the system saves you an afternoon of spelunking.
 
 **What it costs:** a little patience. Explore is a conversation, so it's slower than firing off `/opsx:propose` and hoping. For work you genuinely understand already, that extra step is pure overhead, and you should skip it.
 

docs/faq.md

@@ -50,7 +50,7 @@ Both are files OpenSpec writes so your assistant can run the workflow. Skills (`
 
 ### Where should I start if I'm not sure what to build?
 
-With `/opsx:explore`. It's a no-stakes thinking partner that reads your codebase, lays out options, and turns a fuzzy problem into a concrete plan, all before any change or code exists. It's in the default profile, so it's always available. When the plan is clear, it hands off to `/opsx:propose`. This is the single best habit to form, because it stops an eager AI from confidently building the wrong thing. See [Explore First](explore.md).
+With `/opsx:explore`. It's a no-stakes thinking partner that reads your codebase, lays out options, and turns a fuzzy problem into a concrete plan, all before any code gets written. It's in the default profile, so it's always available. When the plan is clear, it hands off to `/opsx:propose`. This is the single best habit to form, because it stops an eager AI from confidently building the wrong thing. See [Explore First](explore.md).
 
 ### What's the simplest possible flow?
 

docs/getting-started.md

@@ -26,7 +26,7 @@ Two terminal steps to set up, then you live in chat. The rest of this guide unpa
 
 **Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created.
 
-> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md).
+> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any code gets written. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md).
 
 ## How It Works
 

docs/glossary.md

@@ -46,7 +46,7 @@ Terms are grouped by topic, then alphabetized within each group.
 
 **Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md).
 
-**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan, creating no artifacts and writing no code. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md).
+**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan. It never writes code, and writes nothing else unless you ask it to capture the exploration as a change, or say yes when it offers. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md).
 
 **CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md).
 

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, shared `.agents` |
+| 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 |
 
@@ -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, or the shared `.agents` target) `/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/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

@@ -213,7 +213,9 @@ Works through tasks, checking them off as you go. If you're juggling multiple ch
 ```
 /opsx:update add-dark-mode - we're storing the theme in a cookie now
 ```
-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).
+Revises the change's existing planning artifacts and keeps them coherent in any direction (a design edit may ripple back to the proposal). It never edits code. Every edit is confirmed with you first. See [the update reference](commands.md#opsxupdate) for how it handles missing files without starting a new artifact.
+
+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

docs/overview.md

@@ -56,7 +56,7 @@ In the default setup, your day looks like this. Optionally think it through firs
 /opsx:archive                   →  specs updated, change archived
 ```
 
-**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any artifact exists. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md).
+**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any code gets written. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md).
 
 Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion.
 

docs/supported-tools.md

@@ -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, MiniMax Code, Mistral Vibe, shared `.agents` |
+| 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)) |
 
@@ -86,7 +86,7 @@ to read the hint.
 | Hermes Agent (`hermes`) | `.hermes/skills/openspec-*/SKILL.md`\*\*\* | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-<id>.md` |
 | Junie (`junie`) | `.junie/skills/openspec-*/SKILL.md` | `.junie/commands/opsx-<id>.md` |
-| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-<id>.md` |
+| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilo/command/opsx-<id>.md` |
 | 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` |
@@ -95,11 +95,13 @@ to read the hint.
 | 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) |
 
@@ -109,6 +111,10 @@ to read the hint.
 
 \*\*\*\* 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
@@ -145,8 +151,8 @@ shared root many agent tools read, instead of a tool-specific directory.
 | 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 is the exception because it uses the same canonical `.agents`
-root. If both `codex` and `agents` are selected, OpenSpec keeps one
+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.
@@ -168,10 +174,17 @@ Two things to know:
   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).
 
-Because `.agents/skills/` is shared, it is worth knowing what OpenSpec claims there:
+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
-or the vendor-neutral target rendered that shared tree. Anything else in that
+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.
@@ -206,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`, `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`, `trae`, `zcode`, `agents`
+**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, Mistral Vibe 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).
+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
 

docs/workflows.md

@@ -94,7 +94,7 @@ sequenceDiagram
     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
+    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
@@ -140,7 +140,7 @@ You: Yes.
 You: /opsx:propose rebuild-search-index-on-write
 ```
 
-Explore creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md).
+Explore never writes code, and writes nothing else unless you ask, or say yes when it offers. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md).
 
 ### Expanded/Full Workflow (custom selection)
 
@@ -493,7 +493,7 @@ AI:  Let me investigate your current setup and options...
      Your current stack suggests #1 or #2. What's your scale?
 ```
 
-Exploration clarifies thinking before you create artifacts.
+Exploration clarifies thinking before any code gets written.
 
 ### Verify Before Archiving
 

docs/writing-specs.md

@@ -56,7 +56,7 @@ 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 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. 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.
+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-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.
 

flake.nix

@@ -50,16 +50,17 @@
 
             pnpmDeps = pkgs.fetchPnpmDeps {
               inherit (finalAttrs) pname version src;
-              pnpm = pkgs.pnpm_9;
+              pnpm = pkgs.pnpm_10;
               fetcherVersion = 3;
-              hash = "sha256-LerQoKH3MX5mWZ2Sk9p9Q3kUNwckfA1RnP7Z3FueAXU=";
+              hash = "sha256-ifgjl6/g7wpvcF4Ly/p+rxUbNEKiXF2u69CmpUM0olg=";
             };
 
             nativeBuildInputs = with pkgs; [
+              installShellFiles
               nodejs_22
               npmHooks.npmInstallHook
               pnpmConfigHook
-              pnpm_9
+              pnpm_10
             ];
 
             buildPhase = ''
@@ -72,6 +73,21 @@
 
             dontNpmPrune = true;
 
+            # `openspec completion generate` renders a static command registry, so it
+            # needs no project and no network. Opting out of telemetry also disables
+            # the update check, keeping the build offline.
+            postInstall = lib.optionalString (pkgs.stdenv.buildPlatform.canExecute pkgs.stdenv.hostPlatform) ''
+              export OPENSPEC_TELEMETRY=0
+              completions=$(mktemp -d)
+              for shell in bash fish zsh; do
+                $out/bin/openspec completion generate "$shell" > "$completions/openspec.$shell"
+              done
+              installShellCompletion --cmd openspec \
+                --bash "$completions/openspec.bash" \
+                --fish "$completions/openspec.fish" \
+                --zsh "$completions/openspec.zsh"
+            '';
+
             meta = with pkgs.lib; {
               description = "AI-native system for spec-driven development";
               homepage = "https://github.com/Fission-AI/OpenSpec";
@@ -99,7 +115,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-status-next-step/.openspec.yaml

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

openspec/changes/add-status-next-step/proposal.md

@@ -0,0 +1,44 @@
+# Name the command that resumes a change
+
+## Why
+
+`openspec status` reported where a change stood and stopped there. The command
+that moves it forward was already computed: `buildNextSteps` derives it and
+`--json` publishes it as `nextSteps`. But the text surface never rendered it.
+
+So the surface a person actually reads ended on a checklist. `openspec new
+change` hands off with `Next: openspec status --change <name>`, and that next
+command then had no verb of its own. Picking a change back up after a lost
+session, or opening one somebody else started, meant already knowing which
+command came next (#906).
+
+The completion case was the worst of it. Once every planning artifact existed,
+status printed a lone green "All planning artifacts complete!", which reads as
+*you are done* even while `tasks.md` sits half-checked. That is what #906
+reports: every artifact showed `done` rather than `ready`, so the conclusion was
+that nothing was left to run.
+
+## What Changes
+
+- `openspec status` ends with a `Next:` line naming one command: the next ready
+  artifact's `openspec instructions` call while planning is unfinished, and
+  `openspec instructions apply` once every planning artifact exists.
+- The line carries `--store <id>` whenever the resolved root is a store. A
+  command without the flag would resolve against the pointer repo instead of the
+  store the status was read from.
+- `--all` gives every change in the sweep its own line, and gives none to an
+  entry that failed to load, since a failed entry has no artifact statuses to reason
+  about.
+- The line is built from the same resolution as the JSON `nextSteps` sentence,
+  so the two surfaces cannot name different commands. `nextSteps` itself is
+  unchanged, character for character.
+
+No new command, no new flag, no new JSON field. This renders a value the agent
+contract already publishes.
+
+## Impact
+
+- Affected specs: `cli-artifact-workflow` (MODIFIED: Next Artifact Discovery)
+- Affected code: `src/commands/workflow/status.ts`,
+  `src/core/change-status-policy.ts`
+- Affected docs: `docs/cli.md` (the status text output example)

openspec/changes/add-status-next-step/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,37 @@
+## MODIFIED Requirements
+
+### Requirement: Next Artifact Discovery
+
+The workflow SHALL use `openspec status` output to determine what can be created next, rather than a separate next-command surface.
+
+#### Scenario: Discover next artifacts from status output
+
+- **WHEN** a user needs to know which artifact to create next
+- **THEN** `openspec status --change <id>` identifies ready artifacts with `[ ]`
+- **AND** the first `[ ]` entry is the schema's recommended next artifact
+- **AND** no dedicated "next command" is required to continue the workflow
+
+#### Scenario: Status names the command that moves the change forward
+
+- **WHEN** a user runs `openspec status --change <id>` in text mode and a next step resolves
+- **THEN** the output ends with a `Next:` line naming exactly one command to run
+- **AND** that command is `openspec instructions <artifact> --change "<id>" --json` for the first ready artifact while any planning artifact is still ready
+- **AND** it is `openspec instructions apply --change "<id>" --json` once every planning artifact exists, printed after the completion line rather than in place of it, because that line alone reads as "you are done" while implementation tasks remain
+- **AND** the named artifact is never one the change skipped, which satisfies its dependents but must not be created
+- **AND** the artifact id comes from the resolved schema, so a project whose schema declares neither of the default artifact names still gets a usable command
+
+#### Scenario: The named command carries the store selection
+
+- **WHEN** the resolved root is a store
+- **THEN** the `Next:` command includes `--store <id>`, so it resolves against the same root the status was read from rather than the pointer repo
+
+#### Scenario: Both surfaces name the same command
+
+- **WHEN** a next step resolves
+- **THEN** the command printed on the `Next:` line and the command inside the JSON `nextSteps` sentence are derived from one resolution, so the two surfaces cannot name different commands
+- **AND** the `Next:` line never appears in `--json` output, which stays parseable
+
+#### Scenario: No next step resolves
+
+- **WHEN** no artifact is ready and planning is not complete, or a change in an `--all` sweep failed to load
+- **THEN** no `Next:` line is printed for it, rather than a guessed or shared command

openspec/changes/add-status-next-step/tasks.md

@@ -0,0 +1,17 @@
+# Tasks
+
+## 1. Resolve the next step once
+- [x] 1.1 Extract `resolveNextStep` returning the command and the sentence, leaving `buildNextSteps` returning exactly that sentence so the JSON contract is unchanged
+- [x] 1.2 Pin the published sentences verbatim in a unit test, so splitting command from sentence cannot reword the contract
+
+## 2. Render it on the text surface
+- [x] 2.1 Print a `Next:` line from the resolved command, after the completion line rather than in place of it
+- [x] 2.2 Thread the store selection into the renderer so the command carries `--store`
+- [x] 2.3 Give every change in an `--all` sweep its own line, and a failed entry none
+
+## 3. Cover the behavior
+- [x] 3.1 Assert the ready, planning-complete, skipped, and custom-schema cases end to end
+- [x] 3.2 Assert the printed command appears verbatim inside the JSON sentence, and that the line never leaks into `--json`
+
+## 4. Record it
+- [x] 4.1 Update the `cli-artifact-workflow` spec delta and the `docs/cli.md` status output example

openspec/changes/add-update-workflow/design.md

@@ -105,6 +105,12 @@ Review feedback flagged that "update" alone is generic — could it apply to any
 ### 6. Next-step guidance, especially for already-implemented changes
 A change can be revised after it was built — tasks checked off, `/opsx:apply` already run. The update itself behaves identically (planning artifacts only), but stopping silently would strand the user: the code and the revised plan now disagree. So the skill ends by reporting where the change stands (from the status JSON and the tasks checklist) and recommending the next command — `/opsx:continue` if artifacts are missing, `/opsx:apply` to carry a revised plan into code, `/opsx:archive` when everything is done. Guidance only: the skill never implements, mirroring the "All artifacts created! You can now implement this change with `/opsx:apply`" hand-off that `continue-change.ts` already uses.
 
+### 7. Companion-file correction (#1733)
+
+The original glob-file deferral was unreachable: one matching file marks an artifact `done`, while continue selects only `ready` artifacts. Update can therefore propose a missing companion file within an already populated glob. This corrects the unarchived spec's former blanket deferral without changing the graph's completion rule or starting another artifact.
+
+The exception uses existing status and instructions output, requires current dependency context and user confirmation, and preserves the change-only planning scope. Immediately before creation, it rechecks scope and the concrete path and uses an operation that refuses an existing target. Delegated creators must obey the same limits. No new CLI command, metadata, graph state, or automatic artifact writer is introduced.
+
 ## Risks / Trade-offs
 
 - **No deterministic staleness signal.** With no digest/ledger, the skill relies on the agent reading the artifacts to spot incoherence. Trade-off accepted: an agent that rewrites prose must read it anyway, and a content-blind signal earns its cost only for use cases this change excludes (Decision 3).

openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md

@@ -19,7 +19,7 @@ The system SHALL provide a `/opsx:update` workflow skill that revises a change's
 
 #### Scenario: Missing artifacts are deferred to continue
 
-- **WHEN** keeping the change coherent would require an artifact that has not been created yet
+- **WHEN** keeping the change coherent would require an artifact with no existing output files and status `ready` or `blocked`
 - **THEN** the skill revises only the artifacts that currently exist
 - **AND** it notes the not-yet-created artifacts and points the user to `/opsx:continue` to create them
 
@@ -53,7 +53,7 @@ The `/opsx:update` skill SHALL learn which artifacts exist and where they live b
 
 #### Scenario: Resolve artifact paths cross-platform
 
-- **WHEN** the skill reads or writes an artifact on macOS, Linux, or Windows
+- **WHEN** the skill reads or revises an existing artifact file on macOS, Linux, or Windows
 - **THEN** it uses the `existingOutputPaths` provided by the CLI status output
 - **AND** it does not assume forward-slash separators
 
@@ -63,11 +63,30 @@ The `/opsx:update` skill SHALL learn which artifacts exist and where they live b
 - **THEN** the skill edits the concrete files reported in that artifact's `existingOutputPaths`
 - **AND** it does not write to `resolvedOutputPath`, which for a glob artifact remains the glob pattern rather than a real file
 
-#### Scenario: A new file under a glob artifact is deferred to continue
+#### Scenario: A missing companion file under a populated glob artifact
 
-- **WHEN** keeping the change coherent would require a new file under a glob artifact that does not exist yet (for example a spec for a not-yet-captured capability)
-- **THEN** the skill revises only the files already present in `existingOutputPaths`
-- **AND** it points the user to `/opsx:continue`/`/opsx:propose` to create the new file rather than inventing a path from the glob
+- **WHEN** reconciliation identifies a missing companion file for a glob artifact with non-empty `existingOutputPaths`
+- **THEN** the skill MAY propose creating that file using the artifact's instructions, template, project context, rules, and current dependency files
+- **AND** it selects an unused concrete path matching the artifact's `outputPath` inside `changeRoot`, including after resolving linked parent directories
+- **AND** it creates the file only after user confirmation, refreshing status, instructions, and path checks immediately before creation
+- **AND** creation SHALL fail rather than overwrite a file that appeared in the meantime
+- **AND** it SHALL NOT start another artifact, write main specs, or edit implementation code
+
+#### Scenario: Required inputs are no longer available
+
+- **WHEN** a populated glob artifact remains `done` but a required non-skipped dependency is missing
+- **THEN** the skill SHALL stop new companion creation and ask the user to restore the dependency first
+
+#### Scenario: Schema delegates companion creation
+
+- **WHEN** the artifact instruction delegates creation to another skill or command
+- **THEN** the skill SHALL invoke it only if it can honor the confirmed concrete path and the update guardrails
+- **AND** otherwise it SHALL stop rather than invoke broader generation
+
+#### Scenario: Intentionally skipped artifact
+
+- **WHEN** status or instructions mark an artifact as skipped
+- **THEN** the skill SHALL leave it untouched and SHALL NOT treat its empty outputs as missing or send it to continue
 
 ### Requirement: Bidirectional Coherence Review
 
@@ -109,7 +128,7 @@ After applying confirmed revisions (or finding none needed), the `/opsx:update`
 
 #### Scenario: Next step when artifacts are incomplete
 
-- **WHEN** the update finishes and the change still has not-yet-created artifacts
+- **WHEN** the update finishes and the change still has artifacts with no outputs and status `ready` or `blocked`
 - **THEN** the skill recommends `/opsx:continue` to create them
 
 #### Scenario: Next step when the change is fully done

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-windows-archive-claim-release/.openspec.yaml

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

openspec/changes/fix-windows-archive-claim-release/proposal.md

@@ -0,0 +1,28 @@
+# Release archive claims on Windows
+
+## Why
+
+`openspec archive` creates `.openspec-archive.lock` before moving a change into
+the archive. On Windows, a successful archive can leave that lock behind because
+the cleanup check compares the device id returned by the open file handle with
+the one returned by `fs.lstat()`. Node reports a real device id from the handle
+and `0n` from the path stat on the affected Windows/NTFS setup, so the ownership
+check never passes.
+
+The archive itself succeeds, but the next archive is blocked by the stale claim
+and the user has to delete `.openspec-archive.lock` by hand.
+
+## What Changes
+
+- Treat an inode match plus matching claim contents as sufficient when either
+  side reports `dev: 0n`, while still requiring the two path stats around the
+  read to match.
+- Keep the existing protection against deleting a claim that was replaced by
+  another process.
+- Add a regression test that simulates the Windows path-stat device id behavior.
+
+## Impact
+
+- Affected spec: `cli-archive`
+- Affected code: `src/core/archive.ts`
+- Affected tests: `test/core/archive.test.ts`

openspec/changes/fix-windows-archive-claim-release/specs/cli-archive/spec.md

@@ -0,0 +1,36 @@
+## MODIFIED Requirements
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date, keeping the name as-is when it already starts with a `YYYY-MM-DD-` prefix
+  3. Claim the target and verify that it does not already exist
+  4. Prepare and validate spec updates from the active change's delta specs
+  5. Apply the spec updates as a rollback-capable transaction
+  6. Move the entire change directory to the archive location
+  7. If a spec mutation or final move fails before a complete archive is secured, restore the spec transaction and leave or return the change at its active path
+  8. If a verified fallback copy completes but staged-source cleanup fails, retain the complete archive and committed spec state for recovery instead of risking the only complete copy
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs
+
+#### Scenario: Successful archive releases its own claim
+
+- **WHEN** an archive run successfully moves a change to its archive destination
+- **THEN** remove the temporary archive claim it created
+- **AND** do so on supported platforms even when a path stat does not report a device id
+- **AND** never remove a claim whose path identity or contents changed before cleanup

openspec/changes/fix-windows-archive-claim-release/tasks.md

@@ -0,0 +1,12 @@
+# Tasks
+
+## 1. Release owned claims cross-platform
+- [x] 1.1 Compare archive claim files by inode and tolerate a missing device id from either stat result
+- [x] 1.2 Preserve the content and repeated-path-stat checks before unlinking
+
+## 2. Verify behavior
+- [x] 2.1 Add regression coverage for the Windows `dev: 0n` path-stat case
+- [x] 2.2 Run the focused archive regression test
+
+## 3. Record behavior
+- [x] 3.1 Add a `cli-archive` spec delta for successful claim cleanup

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