@azure-id/orc 2.1.0 → 2.2.0

package/guides/configuration.md

@@ -0,0 +1,150 @@
+# Configuration
+
+Every setting is edited with the **`orc config` CLI**. That is deterministic
+terminal input and output, so editing settings costs **zero model tokens** —
+nothing is loaded into a Claude session.
+
+```bash
+orc config                    # interactive menu — each value, its default, and what it does
+orc config list               # print the effective config  (--json for a machine)
+orc config set max_scouts 5   # validate, then write one setting
+orc config reset max_scouts   # revert one key (omit the key to reset everything)
+orc config path               # where the override file lives
+orc config recommend          # read this repo and suggest ONE profile, with its reasons
+orc config profile <name>     # apply a coherent bundle: solo-fast | balanced | paranoid | token-lean
+```
+
+Your changes go into `.claude/orc.config.yaml`, which `orc update` and
+`orc upgrade` never touch. `skills/orc/config.md` holds the shipped defaults.
+Add `--global` to edit `~/.claude`.
+
+**Config does not merge.** `~/.claude/orc.config.yaml` and
+`<project>/.claude/orc.config.yaml` are separate files; the one that applies is
+the one belonging to the install that answered. `orc doctor` reports that
+conflict when both exist.
+
+`orc ui` ▸ Settings edits the same keys with the same validators — it shells
+this CLI for every write.
+
+---
+
+## Common keys
+
+| Key | Default | What it does |
+|---|---|---|
+| `max_wave_tasks` | `3` | Parallel tasks per wave (a hard cap). |
+| `batch_pause_every` | `2` | Waves between stop-and-continue pauses. It is a **gate**, not a hint. |
+| `rubric_bands` | `5` | How finely the scoring report is grouped (2–8). The score→model table does not change. |
+| `max_scouts` | `3` | Parallel read-only scouts in deep analysis. |
+| `default_analysis_depth` | `standard` | `standard` or `deep`. The run still confirms. |
+| `generate_tests` | `false` | Phase 6.5 writes test cases (files + `TEST-PLAN.md` + a curl bundle) into `test-generator/<slug>/`. It never runs them. |
+| `pattern_findings` | `ask` | On a code-pattern cache miss: `ask` prompts, `on` learns automatically, `off` stays language-agnostic. |
+| `gotchas` | `on` | Repair memory: record what went red→green, and inject the matching ones into later executor slices. Since v2.0.0 the reviewer card is always on: `off` turns off the executor block only, and `orc config set gotchas off` says so. |
+| `gotcha_card_budget` | `600` | The size of the reviewer card from `orc gotcha card`, in tokens (options 200 · 400 · 600 · 900). It is a size, never an off switch. The minimum is 200; a lower value is refused. An entry that does not fit is counted in the card header. |
+| `habits` | `off` | Whether ORC learns the answers you give to its questions (`off` · `observe` · `propose`). `off` reads nothing and changes nothing. `observe` shows your usual answers in `orc habit show` and proposes nothing. `propose` asks at most ONE question at the end of a run. Nothing is applied without your yes, and there is no automatic level (`auto` is refused). An accepted habit is the `learned` rank, below this file; `orc habit forget <id>` undoes it. See [habits and gotchas](habits-and-gotchas.md). |
+| `review_before_push` | `ask` | Whether a lane offers a code review before it pushes (`ask` · `on` · `off`). A habit can learn only `on`. |
+| `mini_tdd` | `ask` | Whether `/orc-mini` asks at intake for a test-driven loop (`ask` · `on` · `off`). A habit can learn only `on`. |
+| `quick_update_tests` | `ask` | Whether `/orc-quick` offers to update the tests after a code change (`ask` · `on`). There is no `off`. It changes only the offer after the work, never the dispatch gate. |
+| `notify` | `off` | `bell` rings the terminal bell once when a turn of an ORC run ends — only while a run is open in this session, and only when the run moved. `off` is silent. `orc update` always wires the session hook; the hook reads this key first. No OS notification and no network. |
+| `gotchas_max` | `40` | Live gotchas kept before the least useful are archived (never deleted). |
+| `code_graph` | `off` | `off` · `on` · `semi`. `semi` keeps the map current (preflight heal and the hook), but every lane read answers exit 3, as for `off`. Code lanes build and use a local map of the code (`orc graph`). The structure is free — the CLI parses it, no model. `orc graph map` ranks the repository, `orc graph ctx` prints one card, and `orc graph gain` says what the map put in and estimates what it kept out. `orc graph status` says `THIN` when most files hold no symbol, and `orc graph audit` lists those files by language, longest first — by hand, never from a lane. |
+| `code_graph_notes` | `off` | One-sentence notes on changed functions: `wave` (one batch per wave) or `end` (one batch per run). The only part of the graph that costs tokens. |
+| `security_review` | `off` | Opt-in Phase 5.5 security pass. Fires only when a task scored ≥ 70. |
+| `run_budget_dispatches` | `0` | Stop before wave 1 if the run is forecast to exceed this many subagents. `0` = off. |
+| `mock_example` | `ask` | After a green verify, offer a runnable mocked example in `mock-examples/<slug>/` (never committed). |
+| `tdd_loop_max` | `3` | Implement→test→repair rounds per task before an honest red report. |
+| `stacked_pr` | `ask` | Ship as a stack of PRs when the change trips the thresholds below. |
+| `stacked_pr_loc` | `1000` | LoC that trips the gate, and the per-layer ceiling. |
+| `stacked_pr_files` | `20` | Changed files that trip the gate, and the per-layer maximum. |
+| `stacked_pr_max_layers` | `6` | Soft cap on layers per stack. |
+| `opus5_only` | `false` | One model for every role, with effort as the cost dial. See [model selection](model-selection.md). |
+| `pact_gate` | `warn` | Inject a drifted promise into the planner as a constraint. There is no `block`. |
+| `pact_recheck_on_verify` | `true` | At verify, re-check only the promises this change touched. |
+| `boundary_gate` | `warn` | `block` lifts a REFUSED task out of its wave — **the wave still runs the rest**. |
+| `handoff_write` | `true` | Whether `/orc-handoff` may write a graded surface at all. |
+| `budget_min_samples` | `5` | Dispatches a band needs before a forecast is called confident. |
+| `budget_units` | `auto` | Which unit a forecast leads with: tokens, usd, quota, or all. |
+| `budget_plan` | `auto` | Your Claude plan, for the quota view. Asked once, then stored. |
+| `challenge_pass_severity` | `p1` | The severity at or above which an open `/orc-challenge` finding blocks a pass. Accepted exceptions are subtracted first, and the pass itself is computed by the CLI — never declared by the judge. |
+| `challenge_stall_after` | `3` | Iterations with no net reduction before a cycle is flagged `stalled`. A flag, never a cap: each turn is a person sitting down to work. |
+| `challenge_reader` | `on` | The cold read that measures whether a reader with no context can follow the artifact. `off` makes that dimension report `NOT-CHECKED` with that reason — never silently. |
+| `challenge_gate` | `warn` | One `/orc` preflight line when the document it is about to build from has an in-flight, failing review cycle. There is no `block`. |
+| `doc_max_lines_per_agent` | `400` | Write/read budget per dispatched `/orc-doc` agent, in lines. A section is never split to fit — one over the cap is reported as a planning smell and offered as a split instead. |
+| `doc_max_parallel` | `4` | Agents per `/orc-doc` wave. **Hard cap 4** — a larger value is clamped and the clamp is announced, because more parallel writers is more chances for the outline to drift. |
+| `doc_language` | `en` | Default output language, always confirmable per run. A non-English document is held to the same plain-language bar in that language. |
+| `doc_dir` | `orc/orc-doc` | Where `/orc-doc` folders live. Project root, not `.claude/` — a document is a deliverable a human opens. |
+
+## Fable 5 role override
+
+| Key | Default | What it does |
+|---|---|---|
+| `fable5_enabled` | `false` | Master switch. Nothing changes unless this is true. |
+| `fable5_effort` | `medium` | Effort for the Fable 5 agents. |
+| `fable5_roles` | *(empty)* | Which roles use it: `analyze`, `plan`, `advisor`, `judge`, `review`. |
+
+`opus5_only: true` outranks this whole block, and says so when you set it.
+
+## Advanced keys
+
+| Key | Default | What it does |
+|---|---|---|
+| `wiki_fresh_max` / `wiki_aging_max` | `10` / `30` | Wiki freshness edges, in commits. Computed on read, never stored. |
+| `wiki_scan_tier` | `ladder` | `ladder` sends a small no-new-surface delta to a lighter scanner (~40% cheaper). The resolved tier is always printed. |
+| `wiki_tier_deep_files` | `3` | Covered files touched at or above this send the refresh to the deep scanner. |
+| `wiki_refresh_budget` | `0` | Max scan-tasks per refresh. A planned stop, not an interrupt. `0` = no cap. |
+| `wiki_retire_after_runs` | `0` | Offer to retire a doc no run has used in this many runs. Retiring moves it, never deletes it. |
+| `wiki_delta_full_threshold` | `30` | Percent of touched docs above which a FULL refresh is recommended. |
+| `wiki_refresh_ask_tasks` / `wiki_refresh_ask_files` | `3` / `10` | When the post-ship "refresh the wiki?" question fires. |
+| `orc_wiki_pattern_findings` | `false` | Also learn code patterns during a wiki scan. |
+| `code_graph_notes_min` / `code_graph_notes_cap` | `5` / `40` | Fewest and most functions in one notes batch. Below the minimum nothing is dispatched; the functions wait. |
+| `code_graph_card_budget` | `1200` | Token budget for one `orc graph ctx` card (300–4000). A card never goes over it. |
+| `code_graph_auto_update` | `true` | A code lane's preflight updates a DRIFTED graph itself (free). `false` = hints only until you run `orc graph update`. |
+| `code_graph_heal_ms` | `1500` | How long a READ (`ctx`, `impact`, `coverage`, `changes`) may spend repairing a map that has moved. It never starts a repair it expects to overrun — the last update's own duration is the estimate. Over the cap, the answer comes from the old version and says so. `0` = never repair on a read. |
+| `code_graph_hooks` | `on` | Whether the installed `orc-graph-hook.js` acts. It updates the map when an ORC worker finishes, and hands a worker the anchors it would otherwise search for — for a Grep, a Glob and a shell search (`grep`, `rg`, `git grep`, `findstr`, `Select-String`, `ag`, `ack`). It never blocks a tool call and is silent outside an ORC run. `on,read` adds one more hint: a whole-file read of a file with many symbols gets one line naming its six most reached symbols and their ranges, so a LATER read can ask for a range. The read itself always runs. Under `on`, such a read is only COUNTED — `orc graph gain` prints it as `wide reads` — so you can see what `on,read` would name before you turn it on. `off` = the lane steps are the only update path. |
+| `code_graph_ignore` | *(empty)* | Extra paths the graph never indexes, as a comma-separated list of globs relative to the repository root (`vendor/**,generated/**,*.gen.ts`). The engine already skips `node_modules`, `vendor`, root `dist/` and `build/`, caches, bundles, `.d.ts` and generated files; this adds to that list. A skipped file is reported `excluded` by `orc graph coverage`, never in silence. |
+| `gotcha_sync_hours` | `6` | How old the last `orc gotcha sync` may be before the next review step runs it again (≥ 1). |
+| `sonar_url` / `sonar_project` / `sonar_org` | *(empty)* | The SonarQube or SonarCloud base URL, project key and organization for `orc gotcha import sonar`, so the import needs no flags. `sonar_org` stays empty for a self-hosted SonarQube. The token is NEVER a key: set `SONAR_TOKEN` in the environment. |
+| `rules_card_compact` | `on` | `on` (the default since 2.0.2) gives `/orc-mini` and `/orc-fast` the compact rules card too (`/orc-quick` always gets it): every rule id and the first line of each HARD rule, without the worked examples. Eval E4 showed no new unmet items, no new rule conflicts, and a smoke gate green on the first try at least as often. `off` is the full card. |
+| `crosslink_fresh_days` / `crosslink_aging_days` | `10` / `15` | Cross-repo snapshot age edges. Advisory; they never block. |
+| `aftermath_window_days` | `30` | How far back `/orc-aftermath` grades. |
+| `budget_price_table` | *(shipped)* | Your own dated price table. Older than 90 days prints a warning. |
+| `retro_repo` | `azure-id/orc` | Where `/orc-retro` files its report. |
+| `log_dir` | `.claude/orc/logs` | Behavior traces. Kept until you run `orc clear logs --apply`, or until the automatic sweep removes them (`log_retention_auto: on`, older than `log_retention_days`). |
+| `log_retention_days` | `90` | `30`, `60`, `90`, `120`, `240` or `360`. The age `orc clear logs` deletes at: finished traces and finished run folders (with their `refs/orc/runs/<slug>/pre` ref) whose last activity is older than this. It never deletes user data, a waiting run, the active trace, or a file younger than 6 hours. A trace with an `ASK` line stays for 180 days. The cutoff never goes below `aftermath_window_days`. `orc stats` keeps the counts of a pruned run in `.claude/orc/logs-rollup.json`. |
+| `log_retention_auto` | `off` | `on` = after a lane's `FINISH` packet, `orc trace write` runs `orc clear logs --apply`, at most once per 24 hours. It never blocks a run. `off` = nothing is deleted until you run the command (or press **Clear old logs** in `orc ui` ▸ Maintenance). |
+| `statusline_refresh` | *(not set)* | `off`, `1`, `2`, `3`, `5` or `10` seconds. The timer that redraws the status line while Claude Code is idle, so a moving part (a pet, a clock) moves. This key is not stored in `orc.config.yaml`: `orc config set statusline_refresh 3` writes `statusLine.refreshInterval` in `settings.json`, the same as `orc statusline refresh 3`, and `orc config list` reads it back from there. Claude Code does not accept less than 1 second, so `0.5` is refused and the message gives the nearest value (`1`). Since v2.1.0. |
+| `run_dir` | `.claude/orc/run` | Run state — deliberately outside the installer's reach. |
+| `analyzer_dir` / `planner_dir` / `report_out_dir` | — | Where artifacts are written. |
+| `orchestrator_model` | `claude-opus-4-8` | The main-session model ORC assumes. |
+
+**Behavior-trace logging is permanent.** Every run writes a `.txt` trace under
+`log_dir`: phases, every spawn, the model that actually answered, scores and
+outcomes. There is no on/off key — only `log_dir` moves it. Since v2.1.0,
+`orc clear logs` shows which old traces and run folders it can delete, and
+`orc clear logs --apply` deletes them. Nothing is deleted automatically unless you
+set `log_retention_auto: on`.
+
+---
+
+## Two separate config families
+
+These are **not** part of `orc config`:
+
+| Family | File | Guide |
+|---|---|---|
+| `orc diy …` | `.claude/orc-diy.config.yaml` | [ORC-DIY README](../templates/skills/orc-diy/README.md) |
+| `orc crosslink …` | `.claude/orc-crosslink.config.yaml` | [ORC-WIKI README](../templates/skills/orc-wiki/README.md) |
+
+## Profiles
+
+```bash
+$ orc config profile
+  solo-fast    One person moving fast, reads their own diffs. Fewer gates, bigger waves.
+  balanced     Today's defaults. Change nothing unless you know why.
+  paranoid     Shared codebase, real users. Every gate on, small waves, pause often.
+  token-lean   Big repo, tight budget. Narrow scans, shallow analysis.
+```
+
+`orc config recommend` reads your repo (tests? CI? contributors? a wiki?
+monorepo?) and suggests one, listing the reasons it decided from. It writes
+nothing.

package/guides/documents.md

@@ -0,0 +1,262 @@
+# Documents — `/orc-doc` in detail
+
+README overflow. The short version is in the README under *Documents that go
+somewhere*; this is everything that would have bloated it.
+
+---
+
+## The two contracts
+
+> **The orchestrator never reads the document body.** It knows the document only
+> through the CLI's derived section map and through what the agents it
+> dispatched report back.
+
+> **The context is gathered once and frozen.** A resumed session reads
+> `context.md` from disk; it never re-interviews you for what session 1 already
+> settled.
+
+Both are registered contract tokens. Everything below serves one of them.
+
+## Why it is built this way
+
+Writing a long document with an agent fails in three ways, and all three are
+context-window problems wearing a costume:
+
+1. **The orchestrator reads the document it is writing.** A 900-line TSD is
+   ~30,000 tokens. Read it three times across a session and the session is over.
+2. **Every edit re-reads and re-writes the whole file.** Changing one paragraph
+   in section 9 should not cost the other 14 sections.
+3. **The context dies with the session.** You come back on Monday, the model
+   knows nothing, and you paste the same brief for the fourth time.
+
+## The document is a folder (v0.49.0)
+
+> **`sections/` is the source of truth. `document.md` is a build artifact.**
+
+Each section lives in `sections/<NN>-<slug>.md` — a real, visible file you can
+open, edit and read in a pull request. `orc doc compile` rebuilds the document
+from those files, for **zero model tokens**, whenever you ask; `orc doc split`
+goes the other way and recovers the sections from a document a human reshaped by
+hand, byte for byte.
+
+That is a re-pointing, not a speed-up: compiling was **always** free. What the
+folder buys is early review, a resumable wave, no extract/splice round trip, and
+reads bounded to one file. A section too big for one file splits *underneath*
+into sub-parts (`sections/<id>/00-head.md` + `NN-<sub>.md`) that the reader never
+sees — the compiled document still has exactly one `## ` for it.
+
+The join key is the **filename**. There are no markers inside the files: an HTML
+comment is a lint error in this lane and mangles on import, and it would buy
+nothing the filename does not already give.
+
+## Who holds what
+
+| Holder | What it holds |
+|---|---|
+| the orchestrator | `context.md`, `outline.md`, the section map, the lint findings, each agent's ~30-line return |
+| each writer | ONE file under `sections/`, and nothing else |
+| each checker | ONE bounded part file, read from line 1 |
+| nobody | the whole document |
+
+**Line arithmetic is the CLI's job.** It is the one thing a language model is
+guaranteed to get wrong, and the entire saving depends on the numbers being
+right — so the map is computed by `bin/cli.js`, re-derived after every write, and
+**never stored**. A stored line number is a wrong line number one edit later.
+
+## The arithmetic, on a real document
+
+| | |
+|---|---|
+| Document | 10,000 lines, 40 sections |
+| `doc_max_lines_per_agent` | 400 |
+| `doc_max_parallel` | 2 (hard cap) |
+| Batches | 25 agent slices |
+| Waves | ⌈25 / 2⌉ = **13**, parallel within each |
+| In `partial` mode | **wave 1 is bought, then it STOPS.** The rest is paid for only if wave 1 was right |
+| Orchestrator context spent | 25 returns × ~30 lines ≈ **750 lines**, plus the map |
+| Reading it twice instead | **20,000+ lines** |
+
+On a re-check after an edit, only the sections whose hash changed are
+re-dispatched — typically 1 or 2 slices, not 25. **The hash is what turns a
+re-check from a full pass into a diff.**
+
+## The gates, in order
+
+| Gate | Question | If missing |
+|---|---|---|
+| **D1** | What do you want written, and about what? | **HARD STOP.** Nothing is created — no folder, no file |
+| **D2** | Paths to supporting documents? | "none" is a complete answer and is recorded |
+| **D3** | Do you have your own template? | Falls back to the shipped base template |
+| **D4** | Intent · audience · expectation · language · type · target · length | Re-ask once with a recommended default per field |
+| **D5** | The outline, confirmed before a word is written | — |
+
+Asking D2 and D3 is mandatory even though answering them is not. D4 must be
+answered, but *"yes, use your default"* is an answer.
+
+## The five templates
+
+| Type | Backbone |
+|---|---|
+| `prd` | cover → problem → goals → requirements → risks → rollout |
+| `tsd` | context → goals → design → **alternatives considered** → cross-cutting → rollout |
+| `collaboration` | parties → shared goal → **RACI** → interfaces → decision rights → decision log |
+| `report` | executive summary → **RAG status** → results → risks → **decisions needed from you** |
+| `workflow` | purpose → **when NOT to use this** → the procedure → **when it goes wrong** → escalation |
+
+Each ships as `templates/skills/orc-doc/references/templates/<type>.md`: a
+heading skeleton, a one-line purpose comment per section (stripped at compile,
+never reaching the deliverable), and a starter table where a table is the right
+shape.
+
+**A template is a floor, not a cage.** Your own template REPLACES the shipped one
+entirely — its headings become the outline, its body is instructions for the
+writer, and the two are never merged silently.
+
+## Where a Markdown file can go
+
+| Target | Imports `.md`? | Watch out for |
+|---|---|---|
+| **Notion** | native | **Only H1–H3 exist** — H4+ degrades to bold text. 5 MB/file free, 50 MB paid, 5 GB/ZIP. A hidden file in the ZIP fails the import |
+| **Obsidian** | native format | nothing |
+| **Google Docs** | native | tables convert, but complex ones flatten |
+| **Coda** | native | `/import` on the canvas |
+| **Craft** | yes | imports an Obsidian/Markdown folder with backlinks |
+| **Apple Notes** | native (macOS Tahoe / iOS 26+) | older versions have no support |
+| **GitHub / GitLab** | native | relative image paths must exist in the repo |
+| **Docusaurus / Hugo / Jekyll / MkDocs** | yes | these **want** YAML front matter |
+| **Confluence** | app required | a marketplace importer, or a converter script |
+| **OneNote** | **no** | convert to Word or PDF first |
+
+`orc doc targets` is the machine copy, and `orc doc lint --target <id>` enforces
+it. **A lint rule that came from a real product limit is worth ten invented
+ones.**
+
+## The portability rules
+
+| Rule | Why |
+|---|---|
+| ATX headings, exactly one H1, no skipped levels | every outline builder depends on it |
+| max depth H3 under `notion` and `generic` | Notion has three heading levels |
+| **one paragraph, one line** | a wrap at 80 columns becomes a line break inside a Notion paragraph — the single most common import-mangling bug |
+| no raw HTML, no HTML comments | some importers render them as literal text |
+| simple pipe tables only | everything else survives; these do not |
+| ` ``` ` fences with a language tag | `~~~` and indented blocks convert unreliably |
+| no wikilinks, footnotes or definition lists | Obsidian-only / Pandoc-only |
+| images: alt text **and** a one-line description | images do not travel; the description does |
+| front matter off by default, on for the static-site targets | visible junk in Notion, required by Hugo |
+| no emoji in headings | some importers slug headings and mangle anchors |
+
+## Writing a human can read
+
+Average ≤ 20 words a sentence, anything over 35 is a finding with its line
+number; common words over precise-sounding ones; every acronym expanded on first
+use; active voice; facts in tables; each section opens with its conclusion.
+
+**Never invent a fact — and never write the uncertainty into the document.**
+What is not in `context.md` or `context-sources.md` is **not written at all**. It
+comes back as a gap, is recorded with `orc doc log --kind gap`, lands in the
+derived `gaps.md`, and is raised with you.
+
+**The deliverable carries content only.** No `> **Open:**`, no
+`> **Assumption:**`, no note callout, no HTML comment — not in `document.md` and
+not in a section file. `orc doc lint`'s `annotation-in-body` is an ERROR, and it
+matches an exact, narrow set of ORC's own markers: a line of yours beginning
+"Note:" is content and is never flagged. `compile` REPORTS a match and never
+silently strips it, because we cannot tell whose line it is.
+
+Filler that reads like a fact is the worst possible output of this lane; one of
+ORC's markers left in the reader's document is the second worst.
+
+**The checker is `low` effort on purpose.** It reads a short range and answers a
+bounded question, and a harder-thinking checker reasons its way past a gap a real
+reader would trip on — the same reasoning that pins `/orc-challenge`'s cold
+reader at `low`. Nothing may upgrade it.
+
+## Editing safely
+
+```bash
+#   … a writer opens sections/04-goals-and-metrics.md and edits it IN PLACE …
+orc doc compile <slug>                      # rebuild, then re-map and re-lint
+```
+
+No extract, no splice, no monolith touched. For a section stored as sub-parts the
+writer opens the one ~150-line sub-part rather than all 900 lines.
+
+A section whose hash moved is `user-edited`, and **it is never rewritten without
+an instruction naming it**; a finding inside one is reported and the fix offered,
+never applied. `orc doc ship` **refuses on a `document.md` that is behind its own
+`sections/`**, and names what moved.
+
+## Resuming
+
+```
+/orc-doc resume                  lists every document
+/orc-doc resume prd-checkout     a prefix is enough
+```
+
+The new session runs `orc doc status` and `orc doc parts` — which works before a
+single compile has ever run — reads `context.md` and `outline.md` (**not the
+document**), names the sections you edited, and then **stops and asks what should
+change**. No change request → no work.
+
+`RESUME.md` is written by the lane itself, never by a dispatched agent — a
+dispatch inside a stop sequence lets a stop fail because a subagent did — and it
+lives in `.claude/orc/run/<slug>/`, the one place `orc resume` and `orc run list`
+actually look. **It is rewritten at the end of every WAVE**, not just every
+cycle: a usage-limit kill between waves has to leave something on disk that says
+where it stopped, and the section files already say what is done.
+
+## The CLI
+
+| Command | Exit codes |
+|---|---|
+| `orc doc list` | 0 |
+| `orc doc status <slug>` | **0 complete · 1 in progress · 2 unknown slug** |
+| `orc doc show <slug> [--section <id>]` | 0 · 2 unknown |
+| `orc doc map <slug>` | 0 · 2 no document |
+| `orc doc plan <slug> --role write\|check\|edit` | 0 work to do · 1 nothing to do |
+| `orc doc outline <slug> [--set <path>]` | 0 · 2 unknown |
+| `orc doc parts <slug> [--confirm <ids>]` | 0 all written · 1 something missing or unconfirmed |
+| `orc doc compile <slug> [--partial]` | 0 · **1 missing required section (named)** · 2 unknown |
+| `orc doc split <slug> [--section <id> --by-heading]` | 0 · 1 nothing to split · 2 unparseable |
+| `orc doc migrate <slug> [--clean]` | 0 migrated or already v2 · **1 refused (named)** |
+| `orc doc mode <slug> [--set partial|all]` | 0 · 2 unknown |
+| `orc doc extract <slug> --section <id>` | alias · 0 · 2 unknown section |
+| `orc doc splice <slug>` | alias · 0 · **1 hash conflict** |
+| `orc doc assemble <slug>` | alias → compile · 0 · 1 missing required section |
+| `orc doc lint <slug\|path> [--target <t>]` | **0 clean · 1 findings · 2 unreadable** |
+| `orc doc templates` · `orc doc targets` | 0 |
+| `orc doc init <slug> --type <t>` | 0 · 1 exists · 2 bad args |
+
+Every read speaks `--json`: one object on stdout, and the exit code the human
+path would use. An empty result is an ANSWER, so it still returns its object.
+
+## Config
+
+| Key | Default | What it does |
+|---|---|---|
+| `doc_max_lines_per_agent` | `400` | write/read budget per dispatched agent |
+| `doc_max_parallel` | `2` | agents per wave. **Hard cap 2**; larger is clamped and the clamp is announced |
+| `doc_write_mode` | `ask` | `partial` writes ONE wave and stops · `all` writes every wave · `ask` makes it a question, asked once per run and stored |
+| `doc_language` | `en` | the D4 default, always confirmable per run |
+| `doc_dir` | `orc/orc-doc` | where the folders live |
+
+`opus5_only` is a **no-op** here: both agents are already `claude-opus-5-5`. The
+lane is *unaffected*, not exempt.
+
+## Where it sits
+
+```
+/orc-brainstorm   →  which direction?
+/orc-grill        →  what exactly is it?
+      ↓  ("write this up")
+/orc-doc          →  write it down so other people can act on it
+      ↓
+/orc-challenge    →  is what I wrote actually good enough?   (a SEPARATE session)
+      ↓
+/orc-analyze → /orc-plan → /orc   build it
+```
+
+`/orc-wiki` and `/orc-learn` generate documents derived from the **code**.
+`/orc-doc` writes documents derived from **what you decided**, for people who may
+never open the repository. No overlap, no shared writer.