@wairon/cli 5.1.1-dev.11 → 5.1.1-dev.110

package/CONTRIBUTING.md

@@ -0,0 +1,193 @@
+# Contributing to wairon
+
+The conventions for making a delegated change — never hand-edit `.wai/`, read
+every write back, the lock is the human's, measure before repairing, prove a
+behaviour by revert without `git checkout` — are **not** in this file. They ship
+with the tool, as the **Working conventions** section of the `sdd-implement`
+skill (`src/templates/skills/sdd-implement.md`, installed as
+`.agents/skills/sdd-implement/SKILL.md` and its siblings). Read them there: they
+are true of any wairon project, and the brief-writing half is in `sdd-delegate`.
+
+This file is only what is true of **this repository** and would be wrong to ship
+to a wairon user.
+
+---
+
+## Line endings: CRLF in the working tree, LF in the index
+
+Git stores LF and checks out CRLF here. `.gitattributes` pins only `*.sh` to LF
+(a CRLF shebang breaks `#!/usr/bin/env bash` on the Linux CI runners).
+
+Most tools that write files emit LF, which turns a three-line change into a
+whole-file diff. After any scripted or tool-driven write, normalise the file back
+and confirm `git diff --stat` shows only the lines you meant.
+
+**The rule is preserve what the file has, not "make it CRLF".** The heading above
+describes the common case, not a uniform one: measured across `src/**/*.ts`, 212
+files are CRLF, 52 are LF and 3 are mixed. `install.ps1`, `src/commands/aliases.ts`
+and several tests are LF. Because `core.autocrlf` is true, git normalises on the way
+in and `git status` reads clean either way, so the difference is invisible until a
+scripted edit built for the wrong ending fails to match its anchor — or silently
+rewrites the whole file. Detect each file's endings before editing it and write back
+what was there.
+
+Most obvious ways to check for carriage returns lie, including one that wraps the correct check:
+
+| Command | What it actually does |
+|---|---|
+| `grep '\r' f` | In a basic regular expression `\r` is the letter `r`. It matches every line containing an `r`, so an LF-only file "has carriage returns". |
+| `grep $'\r' f` | Passes a real CR byte — but grep opens the file in text mode here and strips CR before matching, so it reports **0** on a genuinely CRLF file. |
+| `grep -Uc $'\r' f` | Correct. `-U` suppresses the text conversion, so the CR survives to the match. |
+| `file f` | Correct. Says `with CRLF line terminators`, or says nothing about them. |
+| `x=$(grep -Uc $'\r' f)` | Lies, even though the command inside it is the correct one. Capturing it collapses the lone-CR argument to an empty pattern, which matches every line, so what comes back is the file's **line count** whatever its endings are. Run the check unwrapped, or put the CR in a variable first (`CR=$'\r'; grep -Uc "$CR" f`). |
+
+Two traps for scripted edits specifically:
+
+- **Never let a normaliser touch text that itself contains `\r` or `\n` escapes.**
+  A script that rewrites every line ending to CRLF will also rewrite the escape
+  sequence you meant to insert, putting a real carriage return inside a string
+  literal — which is an unterminated-string parse error, found at build time
+  rather than at write time. Build such text with `String.fromCharCode(13)`.
+- **A quoted heredoc still loses doubled backslashes here.** `<<'EOF'` keeps a lone
+  backslash but collapses `\\` to `\`, so `p.replace(/\\/g, "/")` arrives as
+  `p.replace(/\/g, "/")` — an unterminated character class, and a syntax error at run
+  time. **It does not always fail loudly.** The same collapse inside an anchor string turns
+  `\\n` into a real newline, so the text simply does not match and the edit is skipped
+  with no error at all — which is how it was found the second time. Write the script with
+  the file-writing tool, or avoid doubled backslashes, and check the edit applied.
+
+Byte counts show it too: a CRLF file loses exactly one byte per line when it is
+flattened, so `wc -c` before and after a rewrite is evidence.
+
+**Four generated files are deliberately LF — do not "fix" them:**
+
+```
+.wai/context/domains.md
+.wai/context/wairon-guide.md
+.wai/docs/topology.md
+.wai/rules/topology.yaml
+```
+
+---
+
+## Run wairon from this checkout, not the global install
+
+```
+npm run build
+node dist/cli/index.js <command>
+```
+
+A globally installed `wairon` can lag this working tree — including its
+validator, so it can pass a tree the code here rejects, or lock one under an
+older rule set. The MCP server also runs `dist/`, so build *before* reconnecting
+it.
+
+---
+
+## The gates, and today's baseline
+
+| Gate | Baseline |
+|---|---|
+| `npx tsc --noEmit` | clean |
+| `npx vitest run` | 289 files / 4755 tests |
+| `npx vitest run --config vitest.e2e.config.ts` | 7 files / 33 tests |
+| `npm run build` | clean |
+| `npm run build:web` | clean (typechecks the SPA) |
+| `node dist/cli/index.js validate` | 0 errors, 0 warnings, 0 notices; register 303 findings / 406 units |
+| `node dist/cli/index.js validate --ci` | passes |
+
+The counts are a floor, not a target — they move as the suite grows, so update
+this table when they do. `validate` also prints the **conformance debt register**
+(findings carried under `rules.conformance.carried`); it is informational and
+does not fail the gate, but a number that moved is a result worth reporting.
+
+Some tests assert on the text of the shipped skill and agent templates
+(`tests/core/template-vocabulary.test.ts`, `tests/core/skill-composition.test.ts`).
+Changing that text is *supposed* to fail them — that is the assertion doing its
+job. Fix it to match the new text; loosening it to match anything removes the one
+thing keeping the templates and the validator's vocabulary in step.
+
+A rule's `summary` is spec data, not a code string. `tests/core/rule-catalog.test.ts`
+proves the registry's codes and the L3 `findings[].summary` values on
+`iheuristic_rules.yaml` (and its siblings) are ONE list, so changing a summary in
+the rule file alone fails the suite. Change it through the authoring tools first and
+let the code string follow. This catches every contributor who touches a rule's
+codes, and the suite is currently the only place that says so.
+
+---
+
+## A stale MCP server
+
+When the build on disk changed after the server started — which is exactly what
+`npm run build` does mid-session — every `sdd_*` answer carries
+`staleServer: true` and a `⚠ STALE SERVER` banner, and `sdd_get_status` leads
+with it. What happens to a write depends on what the rebuild changed:
+
+- **The spec or tool schemas changed** (the server compares its own schema
+  fingerprint with the one the build on disk computes): every spec write, dry
+  runs included, is REFUSED and writes nothing, and the answers carry
+  `writesRefused: true`. A stale process with old schemas silently drops the
+  fields a newer schema introduced, and has — three times.
+- **Only the build changed:** writes still go through, under the warning.
+
+Either way the cure is the human reconnecting the server
+(`/mcp reconnect wairon`). So author specs *before* a rebuild that changes a
+schema. For a server old enough not to carry the flag, the tell is the shape of
+the answer: a current `sdd_update_spec` returns a structured change report
+naming what moved, an old one a single sentence.
+
+---
+
+## Narrative jumps: use labels, not hand-counted step numbers
+
+Inserting a step into an L5 narrative renumbers every later step, and
+`sdd_update_spec` relocates the jump fields with it. That relocation has gone
+wrong before, and the failure is quiet: a branch keeps a plausible number that
+now points one step past where it meant to land, and nothing but a careful
+re-read catches it.
+
+Only STORED jumps relocate. A jump the delta itself writes — on a step it
+inserts, appends or edits — is read in the numbering the whole delta leaves
+behind, after all of its inserts and deletes, so write it as the final
+narrative will number it.
+
+Every jump-by-number field has a symbolic twin resolved at write time —
+`label` on the step, and `onTrueLabel` / `onFalseLabel` / `toLabel` / `endLabel`
+on the jump. A labelled jump survives an insert because it never named a number.
+Prefer labels whenever a narrative is likely to grow.
+
+When a numeric jump is edited anyway, verify the flow afterwards rather than
+trusting the change report:
+
+```
+awk '/^  - name: METHOD/{f=1} f&&/^  - name: /&&!/METHOD/{exit} f' <impl>.yaml \
+  | grep -E 'stepNumber|type:|onTrueStep|onFalseStep|toStep|outcome'
+```
+
+That prints the control flow on its own, which is short enough to read in one
+pass and is where a mis-relocated target is obvious.
+
+---
+
+## Untracked paths are somebody else's work in flight
+
+Run `git status` before you start. This repo regularly carries an uncommitted
+design folder under `docs/design/` while an investigation is open (at the time of
+writing, `docs/design/chained-subsystems/`). Do not touch, commit, stash, or
+clean anything untracked that your task did not name.
+
+---
+
+## Where repo-local guidance lives — and where it cannot
+
+`CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md` at the repo root
+are rewritten wholesale by `wairon generate` (`writeRootGuideDelegator`), and
+`.claude/` is gitignored entirely. Neither survives, so neither is a home for
+anything a future contributor or agent should inherit. That home is **this file**
+— and a brief points at it by name rather than paraphrasing it.
+
+---
+
+## Bugs and questions
+
+Actively developed. Open an issue.

package/README.md

@@ -3,22 +3,25 @@
 **Waffle AIron** — an AI-Driven Development (AIDD) support tool built around
 **Spec-Driven Development (SDD)**.
 
-> **Status:** stable, actively developed — the SDD spec tree, the conformance gate (a 40-plus-rule
-> registry with narrative control-flow validation, technology
-> boundaries, and per-spec `lint.allow`), spec-derived agent topology,
-> skills, the MCP server, diagrams (Mermaid, interactive canvas + ERD,
-> draw.io/Excalidraw), extension packs (injectable profiles, language
-> tables, and rules), and a self-hostable HTTP **hosting server**
-> (`wairon serve` — HTTP MCP for many isolated projects) are working. See the
-> [roadmap](docs/roadmap.md) for what's next.
+> **Status:** stable, actively developed — the SDD spec tree, the conformance gate (a
+> documented rule registry — `wairon rules list` — with narrative control-flow
+> validation, code↔spec conformance, technology boundaries, and per-spec
+> `lint.allow`), human approval (`wairon lock`) with a CI merge gate
+> (`wairon lock-check`), members and cross-project references, live agent
+> briefs and skills, the MCP server, the design export, diagrams (Mermaid,
+> interactive canvas + ERD, draw.io/Excalidraw), extension packs (injectable
+> profiles, language tables, and rules), and a self-hostable HTTP **hosting
+> server** (`wairon serve` — HTTP MCP for many isolated projects, with a web UI)
+> are working. See the [roadmap](docs/roadmap.md) for what's next.
 
 ---
 
 ## What is it?
 
 `wairon` turns a validated **spec tree** into (a) an enforced architecture
-**conformance gate** and (b) a ready-made **agent topology + skills** that any AI
-coding tool (Claude Code, Gemini CLI, …) consumes to do the work itself.
+**conformance gate**, (b) a recorded **approval** that CI can check, and (c) a
+ready-made **agent topology + skills** that any AI coding tool (Claude Code,
+Gemini CLI, …) consumes to do the work itself.
 
 It is optional and additive: if a project has a `.wai/specs/` tree the workflow
 is active; otherwise you ignore wairon and work normally. wairon does **not** run
@@ -27,17 +30,22 @@ or orchestrate AI sessions — it *equips* the session you already use.
 ```
 .wai/specs/  (the SDD spec tree — source of truth)
    │
-   ├── wairon validate ──▶ architecture-conformance gate
-   │                       (stereotype dependency rules, contract↔impl
-   │                        symmetry, reference integrity, cycle detection)
+   ├── wairon validate ────▶ architecture-conformance gate
+   │                          (stereotype dependency rules, contract↔impl
+   │                           symmetry, reference integrity, cycle detection)
    │
-   └── wairon generate ──▶ .claude/agents/  .gemini/agents/  (derived subagents)
-                           + SDD skills installed into each tool
-                           + wairon MCP server (sdd_* tools)
+   ├── wairon lock ────────▶ .wai/lock.json  (the human approval, committed)
+   │     └ wairon lock-check ▶ CI merge gate: is this the approved design?
+   │
+   └── wairon MCP server ──▶ sdd_* tools + live agent briefs (sdd_get_agent_brief)
+                              + SDD skills installed into each tool
 ```
 
-The host AI tool spawns the generated agents as its **own native subagents**,
-guided by the SDD skills and the `sdd_*` MCP tools.
+The host AI tool spawns subagents of its own from the **live briefs** — each
+composed from the current spec tree on every call — guided by the SDD skills
+and the `sdd_*` MCP tools. Agent files on disk (`.claude/agents/`,
+`.gemini/agents/`) are an optional materialized view of the same topology:
+off by default, on with `rules.materializeAgentFiles: true`.
 
 ---
 
@@ -49,7 +57,7 @@ A complete system is specified top-down across six levels:
 |-------|------|-----------------|
 | **L0 System** | `.wai/specs/.index.yaml` | Vision, boundaries, global requirements, target language |
 | **L1 Subsystem** | `.wai/specs/<sub>/.index.yaml` | An isolated software service, its public interfaces, and trusted links |
-| **L2 Component** | `…/<component>/.index.yaml` | A building block (Portal, Orchestrator, Supervisor, Actor, Store, Index, Registry, Adapter, Observer, Specialist) or pattern (Repository, Gateway) + `owns`/`dependsOn` |
+| **L2 Component** | `…/<component>/.index.yaml` | A building block (Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer, and View for UIs) or pattern (Repository; FeatureComponent and RouterComponent for UIs) + `owns`/`dependsOn`. A gateway is a Portal with the `gateway` variant; logic is an Orchestrator whose `dependencyClass` bounds what it may depend on |
 | **L3 Interface** | `…/<component>/.interface.yaml` | Method signatures & structured params (+ optional wire endpoint bindings) |
 | **L4 Implementation** | `…/<component>/.implementation.yaml` | Concrete implementation of a contract: narrative detail level, bound `technologies` (the swap seam for vendors/engines), optional source path |
 | **L5 Narrative** | (within L4) | Step-by-step method logic as a flat numbered list — `call` steps resolve to real dependency methods, and flow steps (`branch`/`switch`/`loop`/`try`/`jump`/`return`/`throw`) jump by step number |
@@ -69,6 +77,49 @@ tables, and rules — see [Extending wairon](docs/extending-wairon.md).
 
 ---
 
+## Reachability: what reaches each verb
+
+Every Portal verb must be **reached**: either a modelled caller in the design
+calls it (a `call` step along a `dependsOn` edge, or `alias::portal.verb` across
+projects), or the verb is declared an **entry** — callers outside the design
+reach it. Nothing else counts, so a Portal nobody calls and nobody enters is
+reported (`UNUSED_COMPONENT` / `UNUSED_METHOD`), with both remedies named.
+
+- **Transports.** A Portal states its `transport`, one vocabulary with its
+  endpoints: network (`HTTP`, `gRPC`, `GraphQL`, `MessageBus`, `Custom`), local
+  (`CLI`, `IPC`, `NamedPipe`, `JSONRPC` for stdio JSON-RPC such as a language
+  server or stdio MCP) or `InProcess` (a library, which binds no endpoint).
+- **Entries.** `invokedBy: { kind: entry, caller: "…" }` on the Portal (every
+  verb inherits it) or on one verb. Declare one only where the callers really are
+  outside the design: browsers, a CLI user, an AI tool over stdio, the
+  applications that link a library. Never invent one to silence a finding —
+  model the caller instead.
+- **Networks.** A project may declare `network: true` (or `{ description }`) in
+  `.wai/project.yaml`: it and its members form an isolated network. An entry's
+  `scope` is relative — `outside` (the default) or `network` (sibling services
+  inside the innermost network). Inside a network only a `gateway` Portal takes
+  entries from outside, and a modelled call crossing in must land on one. The
+  family run at the root proves every `network` entry has a modelled caller
+  (`ENTRY_UNPROVEN`). A project with no network never sees any of this.
+- **Libraries are called directly.** Another project's `InProcess` Portal is
+  called from any component — no client Adapter needed. Pure and read logic may
+  only call library verbs whose `effect` allows it (`LIBRARY_CALL_IMPURE`), and a
+  native library called from another language needs an `abi` (`c` or `wasm`)
+  (`LANGUAGE_BRIDGE_MISSING`). Wrapping a volatile third-party API in an Adapter
+  stays a good habit, never a rule.
+- **Extension points.** A producer exports a contract consumers implement with
+  `role: implement`; the consumer's interface declares `implements: alias::name`.
+- **Networking is derived.** `wairon network flows | policy | diagram | check |
+  why` turns the modelled reach into an allowed-flows matrix, Kubernetes
+  `NetworkPolicy`, a trust-boundary diagram and live-flow checks — the specs
+  never hold an address. See [Derived networking](docs/network.md).
+
+Upgrading a tree written before this model: `wairon doctor --fix` migrates the
+retired forms (`portalType`, listener `mounts`, the old `invokedBy` kinds), then
+declare the entries it will not invent.
+
+---
+
 ## Domains & agents
 
 Agents are **derived from the spec tree** — you never hand-maintain an agent
@@ -76,7 +127,13 @@ registry:
 
 - a **`system-architect`** from L0,
 - a **`<subsystem>-owner`** per subsystem,
-- a **`<component>-implementer`** per component.
+- a **`<component>-implementer`** per component, when
+  `rules.generateComponentImplementers` is on.
+
+Each agent is served as a **live brief** (`sdd_get_agent_brief`, or
+`wairon agent brief <id>`), composed from the current tree whenever it is
+asked for, so it is never stale. Writing them to disk as agent files is opt-in
+(`rules.materializeAgentFiles: true`).
 
 A **domain** is a unit of ownership. Subsystems yield spec-backed domains
 automatically; you can also declare **free-standing domains** (docs, infra,
@@ -102,8 +159,19 @@ irm https://raw.githubusercontent.com/SYW-Apps/Waffle-AIron/main/install.ps1 | i
 curl -fsSL https://raw.githubusercontent.com/SYW-Apps/Waffle-AIron/main/install.sh | sh
 ```
 
-Both `wairon` and `wai` are registered as commands. (wairon is distributed
-as standalone binaries — it is not published to npm.)
+Both `wairon` and `wai` are registered as commands.
+
+### npm
+
+wairon is also published to npm as `@wairon/cli` (Node 18+):
+
+```sh
+npm install --save-dev @wairon/cli    # per project; run it with npx wairon
+npm install --global @wairon/cli      # or machine-wide
+```
+
+The dist-tags are the release channels: `latest` (stable), `beta`, `preview`
+and `dev`, e.g. `npm install -D @wairon/cli@dev`.
 
 ### Local development
 
@@ -138,15 +206,41 @@ merge to `dev`. Installing from npm, the channels are the dist-tags:
 
 ```sh
 cd my-project
-wairon init                 # bootstrap .wai/ (spec tree, context, skills, MCP-ready)
-
-# Design the system with the SDD architect skill (in your AI tool), or via the
-# sdd_* MCP tools. Then:
-
-wairon status               # spec-tree completeness dashboard
-wairon validate             # architecture-conformance gate
-wairon generate             # regenerate agent files + (re)install skills
-wairon list                 # agents resolved from the spec tree
+wairon init                 # bootstrap .wai/ (spec tree, context, skills, MCP registration)
+
+# 1. Design: in your AI tool, use the sdd-architect skill, which authors the
+#    spec tree through the sdd_* MCP tools.
+
+wairon status               # the tree, its authoring readiness, and its approval state
+wairon validate             # architecture-conformance gate (--ci in CI)
+
+# 2. Approve: once it validates, a human approves the design.
+wairon lock                 # records the approval in .wai/lock.json
+git add .wai && git commit -m "Approve the design"
+
+# 3. Gate: in CI, check that what merges is the approved design
+#    (or use the reusable workflow with strict: true — see docs/cli.md).
+#    --strict also fails when .wai/lock.json is missing or a member project was
+#    never approved; plain lock-check only fails an approval that no longer matches.
+wairon lock-check --strict
+npm ci                      # TS/JS project with code: install the project's dependencies first
+                            # (pnpm install --frozen-lockfile / yarn install --immutable), so the
+                            # gate reads your code with YOUR TypeScript (5 or 6); without one —
+                            # or on TypeScript 7 — it reads with the copy wairon ships. The
+                            # reusable workflow does this for you.
+wairon validate --ci        # the conformance gate, run at the FAMILY ROOT (the project that
+                            # declares the members): there it is the family run, which judges
+                            # the network proofs; externals are judged against their pins
+# Optional: gate on the LIVE producers of your externals as well
+# (exit 1 when one is incompatible, 2 when one could not be compared).
+wairon externals status
+
+# 4. Implement: your AI tool delegates each component with the sdd-delegate
+#    skill, from its live brief (sdd_get_agent_brief).
+
+# Optional
+wairon export --out design.json   # the whole resolved design as JSON
+wairon diagram                    # interactive canvas in .wai/docs/diagrams/
 ```
 
 ---
@@ -165,19 +259,30 @@ See [docs/cli.md](docs/cli.md). Summary:
 | Command | Description |
 |---------|-------------|
 | `wairon init` | Bootstrap `.wai/` and the SDD spec tree |
-| `wairon status` | Spec-tree completeness dashboard |
-| `wairon validate [--ci]` | Architecture-conformance gate |
-| `wairon generate [--target] [--domain] [--dry-run]` | Regenerate agent files + install skills |
-| `wairon list` / `wairon show <id>` | Inspect agents resolved from the spec tree |
+| `wairon status` | The spec tree, its authoring readiness, and its approval state |
+| `wairon validate [--ci] [--all]` | Architecture-conformance gate (the family run at a project with members) |
+| `wairon doctor [--fix]` | Health check and upgrade repairs |
+| `wairon generate [--target] [--domain] [--dry-run]` | Reconcile guides, skills and context; agent files only when `rules.materializeAgentFiles` is on |
+| `wairon list` / `wairon show <id>` / `wairon agent brief <id>` | Inspect agents resolved from the spec tree; print one's live brief |
+| `wairon export [--out <file>]` | The whole design, resolved, as one JSON document ([format](docs/design-export.md)) |
 | `wairon diagram [--all] [--canvas] [--drawio] [--excalidraw] [--sequence <comp:method>]` | Mermaid, interactive canvas, and editable draw.io/Excalidraw exports |
+| `wairon network flows \| policy \| diagram \| check \| why` | Networking derived from the design: allowed flows, Kubernetes `NetworkPolicy`, a trust-boundary diagram, live-flow checks ([details](docs/network.md)) |
 | `wairon rules list` | The conformance rule registry (the architecture linter) |
-| `wairon packs add \| list \| remove [--global]` | Extension packs: injected profiles, language tables, and rules |
+| `wairon pack init \| build \| install \| use \| unuse \| impact \| sync \| bundle \| which <name> \| list \| add \| remove` | Extension packs: injected profiles, language tables, and rules |
+| `wairon member …` / `wairon subsystem externalize` / `wairon project rename` | Members (parts and projects) and the family migrations |
+| `wairon externals add \| pin \| status \| list \| remove \| use \| consumers [--search <dirs>]` | Declare, pin and check the externals a project consumes (`status` is the opt-in live gate); from a producer, `consumers --search ..` finds who consumes it, sibling checkouts included |
+| `wairon surface export \| import \| list \| diff [--against <ref\|file>]` | Exchange a public surface (native snapshot or OpenAPI, one document per portal); `diff` is the public-surface changelog since the last committed approval |
+| `wairon method rename <component> <method> <new-name> [--dry-run] [--search <dirs...>] [--no-pin-symbol]` | Rename a contract method and retarget every reference; `--dry-run` names every consumer it breaks (`--search` scans sibling checkouts too), `--no-pin-symbol` lets the implementation follow the new name |
+| `wairon method rename-param` / `wairon type rename-field` | Rename a contract parameter or a type field and respell every reference; the old name joins the rename trace |
 | `wairon domains list \| scan \| add \| remove` | Domains (subsystem-derived + free-standing) |
 | `wairon skills list \| install` | Manage the SDD skills installed into your tools |
-| `wairon lock [-y]` | Validate the tree as-complete and freeze it (generates the implementer agents) |
+| `wairon lock [-y]` | Validate the design as complete and record its approval in `.wai/lock.json`, code findings beside it; no spec file is rewritten |
+| `wairon lock-check [--strict]` | Merge gate: is the design in this tree the design that was approved? Importable as a [reusable workflow](https://github.com/SYW-Apps/Waffle-AIron/blob/dev/.github/workflows/lock-check.yml) (on `dev` and the dev tags until 6.0.0 ships it on `main`; pin a tag — see [docs/cli.md](docs/cli.md#using-it-in-github-actions)) |
 | `wairon mcp serve \| install \| status` | The wairon MCP server (`sdd_*` tools) |
 | `wairon serve [--port] [--data-dir] [--no-auth]` | Self-host: HTTP MCP for many isolated projects + admin plane |
-| `wairon host project \| key \| lock \| promote` | Administer the hosting server (projects, keys, state-scoped lock/promote) |
+| `wairon host unit \| project \| permission \| key \| lock \| doctor \| packs \| git \| producer \| secret \| demo` | Administer the hosting server (units, projects, permissions, keys, the state-scoped lock) |
+| `wairon login` / `wairon remote` / `wairon mcp install --hosted` | Connect a checkout or an AI tool to a hosted instance |
+| `wairon dev` | Local single-project web UI over the current project |
 | `wairon update` / `wairon aliases` | Self-update / command aliases |
 
 ---
@@ -188,13 +293,15 @@ See [docs/cli.md](docs/cli.md). Summary:
 - [Requirements](docs/requirements.md) — goals, non-goals, scope
 - [Roadmap](docs/roadmap.md) — what's done and what's next
 - [Vision](docs/vision.md) — long-term direction
-- [CLI Reference](docs/cli.md) — all commands
-- [Hosted server](docs/design/hosted-mcp-server.md) — self-host wairon over HTTP (Docker, auth, sizing)
+- [CLI Reference](docs/cli.md) — all commands and MCP tools
+- [Design export](docs/design-export.md) — the `wairon export` JSON format for generators and translators
+- [Supervisor doctrine](docs/design/supervisor-doctrine.md) — how Supervisors and Actors may depend on data and effects
+- [Hosted server](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md) — self-host wairon over HTTP (Docker, auth, sizing)
 - [Pack scoping](docs/design/pack-scoping.md) — the pack store, per-project selection, and reproducibility (design)
 - [Connecting-agent entrypoint](docs/design/connecting-agent-entrypoint.md) — MCP `instructions`, prompts, and skill composition
 - [Execution budgets](docs/design/execution-budgets.md) — what each agent's work costs to do, derived alongside what it owns (design)
 - [Approval baselines](docs/design/approval-baseline.md) — what `lock` approves, and why it stopped rewriting your spec tree (design)
-- [Extending wairon](docs/extending-wairon.md) — extension packs & wrapper products (with a [working example](examples/wrapper/))
+- [Extending wairon](docs/extending-wairon.md) — extension packs & wrapper products (with a [working example](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/))
 - [Templates](docs/templates.md) — agent rendering templates
 - [Standards](docs/standards/INDEX.md) — the architecture standards the SDD model is built on
 
@@ -211,6 +318,12 @@ validation), js-yaml, the MCP SDK, and Vitest. Bundled with tsup.
 
 Actively developed. For bugs or questions, open an issue.
 
+Working on this repo (or delegating work in it) — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for what this checkout does differently: line
+endings, the gate commands and their baselines, and the stale-MCP-server tell.
+The conventions that hold for *any* wairon project ship in the `sdd-implement`
+and `sdd-delegate` skills.
+
 ## License
 
 MIT