archik 0.20.0 → 0.21.0

package/dist/ui/index.html

@@ -14,7 +14,7 @@
         }
       } catch {}
     </script>
-    <script type="module" crossorigin src="/assets/index-Bn3qR7Cx.js"></script>
+    <script type="module" crossorigin src="/assets/index-B9OpuGHk.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DUgLHSFs.css">
   </head>
   <body>

package/docs/templates/CLAUDE.md

@@ -8,13 +8,20 @@
 
 I move from **brief → structural model → build plan → code**. Each step is a reviewable artifact, gated by a HITL accept before the next one is produced. If implementation invalidates the model, I stop coding and fix the model first.
 
-The **structural model** (archik diagram — nodes, nesting via `parentId` and sub-files, edges) says *what exists* and *which way dependencies flow*. `archik drift` and `archik smells` check it against the real code. Code is the last artifact, not the first.
+The **structural model** (archik diagram — nodes, nesting via `parentId` and sub-files, edges) says *what exists* and *which way dependencies flow*. **Decision records** in `.archik/decisions/` say *why* it is shaped that way — one per accepted change. `archik drift` and `archik smells` check it against the real code. Code is the last artifact, not the first.
 
 Two gate types:
 
 - **Canvas gate** — `/archik:accept` on the rendered diff. Used for the structural sidecar.
 - **Plan gate** — user replies "approve". Used for the build plan before any code edits.
 
+### Match gates to reversibility
+
+`archik suggest set` labels every change a **one-way door** (hard to undo) or a **two-way door** (easy to undo):
+
+- **One-way door** — adds a data store, queue/stream, external system, gateway/auth/cdn, cloud or LLM node, a new edge to an external system, a top-level module; or removes a built node or moves one to another parent. Two separate stops: canvas gate first, then the plan gate. If it adds data, an outside system or public traffic, the decision record must also say how it is **secured, observed and rolled back** (`crossCutting`) — `suggest set` refuses it otherwise.
+- **Two-way door** — everything else (an internal function, a new edge inside a module, a description, a lifecycle flip). One stop: stage the sidecar and show the build plan in the same message; `/archik:accept` approves both.
+
 ### Match ritual to scope
 
 Not every task needs the full loop. Skip the modeling phases and just edit when the change is:
@@ -30,8 +37,8 @@ Run the loop when the change introduces new behavior, a new structural shape, or
 **DISCOVER → DESIGN → DECIDE → BUILD → VERIFY**, with one critical back-edge: if BUILD reveals the model is wrong, stop coding and loop back to DESIGN.
 
 - **DISCOVER** — `npx archik q stats / list`, `npx archik smells`, `ls` source dirs. Read before write.
-- **DESIGN** — structural sidecar with rationale (boundaries, nesting, dependency direction).
-- **DECIDE** — `/archik:accept` on the structural sidecar.
+- **DESIGN** — structural sidecar plus its decision record (context, decision, alternatives, consequences).
+- **DECIDE** — `/archik:accept` on the structural sidecar. Accept writes the decision record.
 - **BUILD** — numbered plan → "approve" → execute in small commits. Tests-first when the behavior is clearly bounded.
 - **VERIFY** — validate, tests, lint, build, `archik drift`, `archik smells`, eyeball UI. Stage the `proposed → active` flip.
 
@@ -45,7 +52,7 @@ I'd run the loop like this:
 
 1. **DISCOVER** — `npx archik q list`, `npx archik q describe auth-service`, peek at `src/auth/`. Find that an `auth-service` node already handles login.
 
-2. **DESIGN** — `npx archik suggest set` adding two `proposed` nodes under the `auth` module: a `reset-handler` and an `email-sender` that talks to the email provider (modelled as `external`). Two new edges: `reset-handler → email-sender (calls)`, `reset-handler → auth-service (writes)`. Dependencies flow one way — nothing in `auth-service` imports the handler. Wait for **`/archik:accept`** on the canvas.
+2. **DESIGN** — `npx archik suggest set` adding two `proposed` nodes under the `auth` module: a `reset-handler` and an `email-sender` that talks to the email provider (modelled as `external`). Two new edges: `reset-handler → email-sender (calls)`, `reset-handler → auth-service (writes)`. Dependencies flow one way — nothing in `auth-service` imports the handler. The draft's decision record: *context* — users who lose their password open support tickets; *decision* — self-service reset by emailed one-time link; *alternatives* — admin-only reset, SMS codes; *consequences* — we now depend on an email provider and must expire tokens. It adds an external system, so `suggest set` calls it a **one-way door** and the record also needs *crossCutting*: tokens are single-use and expire in 15 minutes, the provider key lives in the secret store (security); reset requests and send failures are counted and alerted (observability); a feature flag turns the reset link off (rollback). Wait for **`/archik:accept`** on the canvas; accept writes `.archik/decisions/0004-password-reset-by-email.md`.
 
 3. **BUILD plan** — `src/auth/resetHandler.ts` (request + verify), `src/auth/emailSender.ts` (provider client), `tests/auth/reset.happy.spec.ts`, `tests/auth/reset.expired.spec.ts`. Each new edge maps to a real call. Out of scope: rate limiting (next milestone). Wait for "approve".
 
@@ -70,40 +77,42 @@ The recommended opener is **`/archik:bootstrap`** (with or without an inline bri
 
 3. **Surface genuine ambiguities** — usually 2–4 questions about scope, target users, hard constraints, or non-obvious tradeoffs. Skip questions whose answers are in the brief.
 
-4. **Stage the structural model** via `npx archik suggest set` — every node the finished system needs, marked `status: proposed`, parented to a top-level `module`. Wait for **`/archik:accept`** on the canvas (formal gate).
+4. **Stage the structural model** via `npx archik suggest set` — the **first milestone in detail** (every node and edge it needs, `status: proposed`), and the rest of the system as a few coarse `module` placeholders (one per later area, `status: proposed`, one-line description). Wait for **`/archik:accept`** on the canvas (formal gate).
 
-5. **The whole architecture lives on day one as `proposed`.** Milestones flip subsets from `proposed` to `active` (with `sourcePath`) as code lands. The set of nodes a milestone flips IS the milestone.
+5. **Detail grows with the work.** Don't model what you can't yet know. Each milestone first details its own area (a sidecar that replaces the placeholder's insides), then flips those nodes from `proposed` to `active` (with `sourcePath`) as code lands. The set of nodes a milestone flips IS the milestone.
 
 ## Per-milestone rhythm
 
-Every milestone follows the same shape. Two gate types apply — **canvas gate** (`/archik:accept`) and **plan gate** ("approve"):
+Every milestone follows the same shape. Two gate types apply — **canvas gate** (`/archik:accept`) and **plan gate** ("approve") — merged into one stop for two-way doors:
 
-1. **Structural sidecar** — `/archik:suggest <feature>`. Stages the proposed end-state for this milestone via `npx archik suggest set` under the hood. Rationale in 2–4 bullets.
+1. **Structural sidecar** — `/archik:suggest <feature>`. Stages the proposed end-state for this milestone via `npx archik suggest set` under the hood, with its decision record. Note whether `suggest set` called it a one-way or two-way door.
 2. **`/archik:accept` on the structural diagram** — formal canvas gate.
-3. **BUILD plan** — one-line goal, deps, files with paths and signatures, non-obvious bits, acceptance gate, out-of-scope items, the `proposed → active` flip this milestone will produce. Each new edge must map to a real call in the plan.
-4. **"approve" on the plan** — plan gate. Don't start editing files until approved.
+3. **BUILD plan** — one-line goal, deps, files with paths and signatures, non-obvious bits, acceptance gate, out-of-scope items, the `proposed → active` flip this milestone will produce. Each new edge must map to a real call in the plan. For a one-way door with `crossCutting`, the plan also lands what it promised: the security control, the signal you will watch, the rollback path.
+4. **"approve" on the plan** — plan gate. Don't start editing files until approved. *Two-way door:* steps 1–4 collapse — show the plan together with the sidecar, and `/archik:accept` approves both.
 5. **Execute** — small commits, narrate non-obvious decisions, declare back-edges to DESIGN openly when they happen.
-6. **Verify** — project tests → lint → build → `npx archik drift` → `npx archik smells` → aesthetic eyeball (if UI). No new folder loop should close the milestone.
-7. **Stage the `proposed → active` sidecar** — `/archik:suggest "flip <list> to active"`. Flips nodes/edges with their `sourcePath` now on disk.
+6. **Verify** — project tests → lint → build → `npx archik drift` → `npx archik smells` → aesthetic eyeball (if UI). No **new** folder loop or oversized file should close the milestone (with a committed baseline, `smells` marks them NEW). For a one-way door, check the `crossCutting` promises exist in the code before the flip to `active`.
+7. **Stage the `proposed → active` sidecar** — `/archik:suggest "flip <list> to active"`. Flips nodes/edges with their `sourcePath` now on disk. Its decision record is short: what landed, and that drift now checks it.
 8. **Hand off** — list what to eyeball; wait for `/archik:accept` and (if there's a deploy) confirm deploy is green.
 9. **Commit + push** — only after the user confirms.
 
 ## Hard rules
 
 1. **Structure → plan → code. In that order.** The accepted diagram defines what to build. Code lands last.
-2. **Two gate types.** The structural model gets a **canvas gate** (`/archik:accept`). The build plan gets an **approval gate** ("approve"). Don't conflate them — `/archik:accept` only works on structural sidecars.
+2. **Gates match reversibility.** One-way doors get two stops: a **canvas gate** (`/archik:accept`) on the model, then an **approval gate** ("approve") on the plan. Two-way doors get one stop: sidecar and plan shown together, one `/archik:accept`. Never skip review of a one-way door to save time.
 3. **Dependencies flow one way.** Sibling folders must not import each other. `npx archik smells` reports folder loops with the real imports as evidence — fix them, don't invent labels for them.
 4. **Stop at every milestone boundary.** Summarize what shipped, run verifications (`archik drift` and `archik smells`), ask for the visual ack before continuing.
 5. **Boring underneath.** No experimental framework features unless explicitly requested. Match the stack the brief specifies.
 6. **No scope creep.** Out-of-scope items go in `FUTURE.md`, not the current milestone.
 7. **Back-edge from BUILD lands on the model.** If implementation reveals the structural model is wrong, fix it with a fresh sidecar. Never paper over.
-8. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
+8. **Every structural change says why.** Each sidecar carries a decision record; accept writes it to `.archik/decisions/`. Records are never edited — to change course, a new record lists the old numbers in `supersedes`.
+9. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
 
 ## What each phase produces
 
 ### DISCOVER
 - `npx archik q stats` and `npx archik q list` to ground in the current diagram.
 - `npx archik smells` to see folder loops and oversized files in the code.
+- Past decision records in `.archik/decisions/` for the area you will touch — don't undo a choice without knowing why it was made.
 - `ls -F` of relevant source dirs.
 - A mental map of what exists vs what the request needs.
 - No code, no diagram changes yet.
@@ -112,6 +121,9 @@ Every milestone follows the same shape. Two gate types apply — **canvas gate**
 - One-line intent.
 - 1–3 clarifying questions only when there's genuine ambiguity.
 - A sidecar staged via `npx archik suggest set --note "..."` containing the **full proposed end-state**.
+- A decision record in the draft (`metadata.suggestion.decision`): **context** (the problem and forces, not the solution), **decision**, **alternatives** (at least one real option not chosen), **consequences** (what gets easier *and* harder). `suggest set` refuses a draft without it.
+- For changes that add data, an outside system or public traffic: `crossCutting` with **security** (who can reach it, secrets, data exposure), **observability** (how you will see it work or fail) and **rollback** (how to undo it safely).
+- Model only what this milestone needs in detail; later areas stay coarse placeholders.
 - New code-bearing nodes use `status: proposed` and may omit `sourcePath`.
 - Containers via `parentId`; a big subsystem gets its own sub-file via `archikFile`.
 - `description` on every node explains *what it does*, not *what kind it is*.
@@ -120,6 +132,7 @@ Every milestone follows the same shape. Two gate types apply — **canvas gate**
 
 ### DECIDE
 - The user runs `/archik:accept` (apply) or `/archik:reject` (with a reason).
+- On accept: the decision record lands in `.archik/decisions/NNNN-<slug>.md`, with the model change listed as evidence.
 - On reject: ask one specific question pinned to one axis — boundary / relationship / scope / naming / composition / lifecycle. Treat the answer as a hard constraint, re-stage. Never silently retry the same draft.
 
 ### BUILD
@@ -137,10 +150,11 @@ Every milestone follows the same shape. Two gate types apply — **canvas gate**
 3. Build / typecheck — clean.
 4. `npx archik validate` — schema + cross-file + constraint checks clean.
 5. `npx archik drift` — structural model matches disk.
-6. `npx archik smells` — no new folder loops or oversized files. `--fail-on-warn` for CI gates.
-7. Aesthetic eyeball when there's a UI — share a screenshot, ask before declaring done.
-8. Stage the `proposed → active` sidecar — flip nodes/edges with `sourcePath`.
-9. Commit (with a Co-Authored-By line) and push — only after user confirms.
+6. `npx archik smells` — no **new** folder loops or oversized files. On existing code, run `npx archik smells --update-baseline` once and commit `.archik/smells-baseline.json`; `--fail-on-warn` then fails CI only on new findings. Tighten the baseline when findings are fixed.
+7. For one-way doors: the record's `crossCutting` promises (security control, signal, rollback path) exist in the code.
+8. Aesthetic eyeball when there's a UI — share a screenshot, ask before declaring done.
+9. Stage the `proposed → active` sidecar — flip nodes/edges with `sourcePath`.
+10. Commit (with a Co-Authored-By line) and push — only after user confirms.
 
 ## Archik commands I use
 
@@ -154,7 +168,7 @@ Every milestone follows the same shape. Two gate types apply — **canvas gate**
 - `npx archik suggest set --note "<one-liner>" - <<'YAML' ... YAML` — stage a structural sidecar (full document).
 
 **Lifecycle:**
-- `npx archik suggest accept | reject | show` — structural sidecar lifecycle.
+- `npx archik suggest accept | reject | show` — structural sidecar lifecycle. Accept writes the decision record.
 - `npx archik validate` — schema + cross-file + constraint checks.
 
 **Verification & rendering:**
@@ -167,6 +181,8 @@ Every milestone follows the same shape. Two gate types apply — **canvas gate**
 - **Editing `.archik/main.archik.yaml` by hand** — forbidden; always go through `suggest set`.
 - **Writing prose-only summaries instead of staging a sidecar** — every structural change must produce a reviewable artifact.
 - **Skipping the BUILD-plan HITL** — diagram acceptance is not implicit code approval.
+- **A decision record with only upsides** — consequences must name what gets harder too; alternatives must be options you really weighed.
+- **Editing an old decision record** — records are history. Stage a new decision that `supersedes` it.
 - **Renaming an `id` mid-flow** — forbidden; remove the old and add a new one. Renames break diff and require manual re-link in code.
 - **Labelling a smell without evidence** — name a folder loop by the imports `archik smells` shows, not by a made-up category.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archik",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams with a live browser canvas, headless SVG render in CI, and an installable Claude skill so the model treats the diagram as the spec.",
   "keywords": [
     "architecture",

package/skills/archik/SKILL.md

@@ -9,6 +9,7 @@ description: Use whenever .archik/main.archik.yaml or architecture.archik.yaml e
 
 - **The YAML is the source of truth.** `.archik/main.archik.yaml` (and any `*.archik.yaml` sub-files) describe the system the user is building. The browser canvas is just a stateless projection of that file.
 - **The CLI is your only interface to it.** You never read, write, or edit archik files directly. Every read goes through `npx archik q ...`; every write goes through `npx archik suggest set` → user accepts via `/archik:accept`.
+- **Every change says why.** A draft carries a short decision record (context, decision, alternatives, consequences). Accept writes it to `.archik/decisions/NNNN-<slug>.md`. The diagram is the *what*; the records are the *why*. Read past records before you change a structure they explain — they are plain markdown, so reading them directly is fine (the "CLI only" rule is about the YAML model files).
 - **Two command surfaces:** the user types `/archik:*` slash commands; you run `npx archik ...` directly. They're not interchangeable — see the tables below.
 - **One change to ship, not the whole system.** When a user hands you a brief on a fresh project, never say "let me sketch your whole system." Propose the smallest structure that delivers the first piece of value. New code-bearing nodes start `status: proposed` (the code doesn't exist on disk yet) and flip to `status: active` when the code lands in BUILD. The project's commitments live in the YAML, not in the chat log.
 - **Read the learned overlay at session start.** If `.archik/evolution/learned.md` exists, read it (with the Read tool — it is docs, not an archik YAML) before your first archik action and treat every note as binding guidance. Each note is a lesson this project's evolution loop gathered from real usage and a human approved. After a suggestion of yours is rejected, run `npx archik evolution reflect` — repeated rejections become proposals the user can review.
@@ -49,6 +50,7 @@ These are the verbs you reach for during the loop. Default to `npx archik` (no g
 | Validate a file                   | `npx archik validate <path>`                  |
 | Spot over-complex files / hubs    | `npx archik complexity [--fail-on-warn]`      |
 | Find folder loops / oversized files | `npx archik smells [dir] [--json] [--fail-on-warn]` |
+| Accept today's smells as known debt | `npx archik smells --update-baseline` (commit `.archik/smells-baseline.json`) |
 | Stage a proposed change           | `npx archik suggest set --note '…' - <<'YAML' … YAML` |
 | Show / accept / reject pending    | `npx archik suggest show \| accept \| reject` |
 | Render an SVG                     | `npx archik render --out diagram.svg`         |
@@ -79,9 +81,9 @@ Every structural change runs the loop. Don't skip phases; don't silently retry o
   └─────┬──────┘  exists.
         │
   ┌─────▼──────┐  Frame intent in one line + 1–3 sharp clarifying Qs.
-  │   DESIGN   │  Stage sidecar (`suggest set`) with rationale:
-  │            │  bounded contexts, sync vs async, composition,
-  └─────┬──────┘  alternatives rejected.       ◄── reject + reason ──┐
+  │   DESIGN   │  Stage sidecar (`suggest set`) with its decision
+  │            │  record: context, decision, alternatives,
+  └─────┬──────┘  consequences.                ◄── reject + reason ──┐
         │                                                            │
   ┌─────▼──────┐  Canvas diff: accept | reject (why?) | revise.      │
   │   DECIDE   │ ───────────────────────────────────────────────────►┤
@@ -100,10 +102,10 @@ Every structural change runs the loop. Don't skip phases; don't silently retry o
 
 | Phase    | Driver        | Tool you reach for                                  |
 | -------- | ------------- | --------------------------------------------------- |
-| Discover | Claude        | `npx archik q ...` + `npx archik affected` + `npx archik smells` + `ls` |
-| Design   | Claude → User | sidecar via `suggest set`                           |
-| Decide   | User          | `/archik:accept` or `/archik:reject` (HITL gate)    |
-| Build    | Claude → User | numbered plan (HITL approval), then small commits   |
+| Discover | Claude        | `npx archik q ...` + `npx archik affected` + `npx archik smells` + `ls` + past records in `.archik/decisions/` |
+| Design   | Claude → User | sidecar via `suggest set`, with its decision record |
+| Decide   | User          | `/archik:accept` or `/archik:reject` (HITL gate) — one-way doors alone, two-way doors together with the plan |
+| Build    | Claude → User | numbered plan (own HITL approval for one-way doors), then small commits |
 | Verify   | Claude        | `npx archik validate` + tests + `drift` + `smells` + SVG regen |
 
 **Two non-obvious feedback edges:**
@@ -172,9 +174,37 @@ edges:
     from: payments-worker
     to: order-events
     relationship: subscribes
+metadata:
+  suggestion:
+    decision:
+      context: Orders-api charges Stripe inline, so a slow Stripe call blocks checkout and a Stripe outage fails orders.
+      decision: Move charging to a payments worker that subscribes to order.placed on the order-events stream.
+      alternatives:
+        - Keep the inline call with a shorter timeout and retries
+        - Call a payments service synchronously over HTTP
+      consequences: Checkout no longer waits on Stripe; payment becomes eventually consistent, so the UI must show a "payment pending" state.
+      crossCutting:
+        security: The worker alone holds the Stripe key (secret store); events carry order ids, not card data.
+        observability: Consumer lag and failed-charge count on the payments dashboard, alert on lag over 5 minutes.
+        rollback: A flag switches checkout back to the inline call; the stream is additive.
 YAML
 ```
 
+**The decision record is required** — `suggest set` refuses a draft without it, and accept writes it to `.archik/decisions/`. Write it for the reader who arrives in a year:
+
+- **context** — the problem and the forces (load, failure modes, team limits). Facts, not the solution.
+- **decision** — what you chose, in one or two sentences.
+- **alternatives** — real options you weighed and did not choose. At least one. "Do nothing" counts when it was a real option.
+- **consequences** — what gets easier AND what gets harder. A record with only upsides is not finished.
+- **crossCutting** — required when the change adds data, an outside system or public traffic (the CLI tells you). **security**: who can reach it, secrets, data exposure. **observability**: the signal that shows it working or failing. **rollback**: how to undo it safely. Real answers — the build plan must land them.
+- **supersedes** (optional) — record numbers this one replaces, e.g. `["0003"]`. Old records are never edited.
+
+**One-way vs two-way doors.** `suggest set` and `suggest show` label each change. A **one-way door** (hard to undo) adds a data store, queue/stream, external system, gateway/auth/cdn, cloud or LLM node, a new edge to an external system or a top-level module, or removes a built node, or moves one to another parent. Hand it off alone and say why it is hard to undo; the build plan gets its own approval after accept. A **two-way door** is everything else — show the build plan in the same hand-off, and one `/archik:accept` approves both. Never skip review of a one-way door to save time.
+
+**Model only what you know.** On a new project, model the first milestone in detail and the rest as coarse `proposed` module placeholders; detail each area when its milestone starts.
+
+For a mechanical change (flip `proposed → active` after code lands), keep it short: context = what landed, decision = mark it active, alternative = keep it proposed until deploy, consequence = drift now checks it.
+
 The CLI parses, schema-validates, checks cross-file references, stamps `metadata.suggestion`, and atomically writes the sidecar. If it exits non-zero, the error includes a hint pointing at the wrong field — fix the heredoc and re-run. **Never edit the sidecar by hand.**
 
 ```bash
@@ -190,6 +220,7 @@ npx archik validate .archik/main.archik.yaml   # schema + cross-file + constrain
 npx archik drift                                # diagram vs source tree
 npx archik affected --json                      # what did this change touch? who depends on it?
 npx archik smells                               # folder loops + oversized files, from the code
+                                                # (with a baseline, only NEW findings count)
 npx archik render --out docs/architecture.svg  # if the project commits an SVG
 ```
 
@@ -211,6 +242,9 @@ version: "1.0"
 name: Payments internals
 nodes: [ ... ]
 edges: [ ... ]
+metadata:
+  suggestion:
+    decision: { context: ..., decision: ..., alternatives: [...], consequences: ... }
 YAML
 npx archik suggest accept .archik/payments.archik.yaml
 
@@ -225,6 +259,9 @@ nodes:
   ... (every other node)
 edges:
   ... (every edge)
+metadata:
+  suggestion:
+    decision: { context: ..., decision: ..., alternatives: [...], consequences: ... }
 YAML
 ```
 
@@ -430,6 +467,9 @@ npx archik complexity [path] [--json]   # advisory report: over-large files, hub
                   [--max-nodes N] [--max-edges N] [--max-children N]
                   [--max-degree N] [--max-depth N]   # override the strict defaults
 npx archik smells [dir] [--json]        # folder loops + oversized files, read from TS/JS code
+                  [--fail-on-warn]      #   exit 1 on findings (only NEW ones if a baseline exists)
+                  [--update-baseline]   #   save today's findings to .archik/smells-baseline.json
+                  [--baseline <file>]   #   use another baseline file
                   [--max-file-lines N]  #   line limit per file (default 500)
                   [--fail-on-warn]      #   exit 1 if any smell (CI gate)
 npx archik render --out diagram.svg --theme light|dark
@@ -450,11 +490,16 @@ npx archik otel check --graph <deps.json> [--json]
 
 npx archik suggest show [--json]
               suggest set <draft|->     # validate + stage a sidecar
-                  --note '<text>'       # set metadata.suggestion.note
+                                        #   (draft needs metadata.suggestion.decision)
+                  --note '<text>'       # set metadata.suggestion.note (record title)
                   --main <path>         # override main file detection
                   --allow-orphan        # permit a sidecar with no main on disk
                   --json                # structured output
-              suggest accept | reject
+              suggest accept | reject   # accept writes .archik/decisions/NNNN-*.md
+
+npx archik migrate [--dry-run]          # bring this project's archik files up to the
+                                        #   installed version; if validate says a key
+                                        #   was "removed in archik 0.20", run this
 
 npx archik dev | start | stop | status  # canvas server lifecycle
 npx archik watch                        # re-render to SVG on save