@wairon/cli 5.1.1-dev.106 → 5.1.1-dev.108

package/dist/templates/skills/sdd-architect.md

@@ -48,7 +48,8 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
    - Do NOT design components or interfaces for the entire system all at once. Proceed **one subsystem at a time** to ensure focused, manageable design reviews.
    - For the active subsystem:
      1. Design and add all L2 Components (Portals, Orchestrators, Stores, etc.) using `sdd_add_component` (defaulting to `status: draft`).
-        The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — apply the **held-state recipe** below BEFORE adding a bare Store.
+        The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — give that state a component of its own, choosing the **smallest sound shape** from the held-state guidance below.
+        Design the SMALLEST sound system: count the components against the endpoints and the state they serve. Ten endpoints over two simple tables is a handful of components, not thirty; every block you add must buy a rule it enforces or a seam it opens.
      2. Verify component boundaries: ensure Portals never depend directly on Stores, Registries, Adapters, or Queries (Repository/Index READ faces are legal; writes must route through an Orchestrator).
      3. Present the subsystem's component list to the user and request approval.
      4. Once approved, define the L3 Interfaces (`.interface.yaml`, via `sdd_define_interface`) for each component in this subsystem.
@@ -78,13 +79,12 @@ The full standard is the source of truth; this is the summary you design against
    - **No wildcard block**: decompose instead. Held or derived state → Store/Index/Repository; behaviour over a value's own fields → a type method; external I/O → Adapter; logic → an Orchestrator with the narrowest `dependencyClass` that holds; one live thing → Actor. `Specialist` and `Gateway` are retired (`STEREOTYPE_RETIRED`): `wairon doctor --fix` retypes a Specialist as an Orchestrator, and a Gateway becomes the Portal it owned, with the `gateway` variant.
 2. **Patterns** (named compositions; set `owns`): `Repository` — the data-access component for one aggregate: owns one Store + its Registry + Indexes + Queries + optional Adapter; consumers use the facade only, never the inner blocks. A `Query` lives only inside a Repository and depends only on its Store, a backend Adapter or pure logic. Reads across aggregates go through a read Orchestrator (or a read-model Repository whose Query runs the join), and an outbox is a sibling Repository. A pattern owns only building blocks, never another pattern — compose patterns at the subsystem (L1) level.
    - **Variants** (`variant:` on a component): the built-in `arbiter`, `projector`, `composer` and `codec` (on Orchestrator) and `gateway` (on Portal: authenticates, authorizes, validates or rate-limits before it dispatches, with its inbound auth in `auth`), then any global and project variants, a later layer overriding by id. A variant carries guidance; what an Orchestrator may depend on is its own `dependencyClass`.
-   - **No Persistence Shortcuts**: Every domain entity requiring state preservation (even simple settings, configurations, permissions, or in-memory rules) **must** utilize a proper `Repository` composed of `Store`, `Registry`, and `Index` blocks. Under no circumstances may you skip repositories/stores, store state inside an `Orchestrator` directly, or combine `Store`, `Registry`, and `Index` roles into a single "storage" or "helper" component.
-   - **Held-state recipe (apply the moment state appears — do not wait for a refused link):**
-     1. `sdd_add_component` the members: `<x>_store` (Store), `<x>_registry` (Registry — write path), `<x>_index` (Index — read path).
-     2. `sdd_add_component` the facade: `<x>_repository` (Repository, `owns: [<x>_store, <x>_registry, <x>_index]`).
-     3. Point every consumer at the `<x>_repository` facade — never at the inner blocks.
-     - *Lightweight exception*: for genuinely simple held state, a deliberately **standalone Store** is sanctioned — consumers from the workflow layer only (a workflow Orchestrator or an Actor), acknowledged with a `lint.allow` reason on the `UNOWNED_STORE` warning. The state stays VISIBLE as a component either way.
-     - *Never*: hold state as fields inside an Orchestrator because a Store link was refused. A refused link means "apply this recipe", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
+   - **No Persistence Shortcuts**: held state always lives in a data component of its own — never as fields inside an `Orchestrator`, and never merged with logic into a "storage" or "helper" component. WHICH data shape is the smallest one that is sound for the state at hand:
+   - **Held-state guidance (apply the moment state appears — do not wait for a refused link), smallest first:**
+     1. **Genuinely simple state** — a settings record, a table read and written by key, a small set — is **one standalone `Store`**. This is the sanctioned shape, not a shortcut: its consumers are on the workflow layer (a workflow Orchestrator or an Actor; a Portal reaches it through that Orchestrator), and you acknowledge the `UNOWNED_STORE` warning with a `lint.allow` reason ("simple keyed state, no lookups beyond the key"). Do NOT add a Registry, Index or Repository around it to make it look complete.
+     2. **State with real lookup or index needs** — reads by something other than the key (by owner, by date range, by status), several read projections, or a write path that must keep invariants across them — is the **`Repository` pattern**: `<x>_store` (Store), `<x>_registry` (Registry — write path), one `<x>_index` per real lookup (Index — read path), and the `<x>_repository` facade that `owns` them; every consumer points at the facade. Add an Index only for a lookup a narrative actually performs; a Repository with one Index that only re-reads by key is the simple case dressed up — use step 1.
+     3. Never split Store/Registry/Index for state that step 1 covers, and never combine their roles into one component when step 2 applies.
+     - *Never*: hold state as fields inside an Orchestrator because a Store link was refused. A refused link means "give the state its component", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
 3. **owns vs dependsOn**: `owns` = a pattern's private member blocks (exactly one hop), or a Supervisor's supervision state (its own Stores and Registries). `dependsOn` = collaborators (other facades / standalone blocks). Never depend on a block privately owned by another pattern.
 4. **Decoupling**: Registry (write) and Index (read) are independent — both work on the Store; the Registry never updates Indexes (Indexes share the Store's references and project structural changes). A Store is depended *upon*; it never depends on a Registry/Index. An Index depends on its Store, a backend Adapter or pure logic; only when one projection is itself worth re-presenting another way may a derived Index depend on another Index — owned by the same Repository, never in a cycle (`ARCHITECTURE_VIOLATION_INDEX_DEP` otherwise). Keep it the exception: it is not a way to chain lookups.
 5. **Behaviour placement**: behaviour lives where it can be performed autonomously over its own state (`order.total()`, `dog.bark()`); behaviour needing an external actor lives on the *acting* component, taking the entity as an argument (a `Carrier` ships an order — not `order.ship()`). Prefer composition + interfaces over inheritance.
@@ -101,7 +101,7 @@ JSON for review. You never hand-author spec YAML. What to know beyond the tool
 schemas:
 
 - **Levels & files** (written by the tools): L0 `.wai/specs/.index.yaml` → L1 `<sub>/.index.yaml` → L2 `<sub>/<comp>/.index.yaml` (owned members nest one level deeper) → L3 `.interface.yaml` → L4+L5 `.implementation.yaml`. Types live under `types/` (system-level shared, or per subsystem).
-- **Statuses**: `draft` → `design` → `complete` — authoring readiness. Completeness rules relax to warnings while draft/design. Approval is separate: `wairon lock` (human-run) validates the tree as if complete and records the approval in `.wai/lock.json`; it never rewrites a spec's `status`.
+- **Statuses**: `draft` → `design` → `complete` — authoring readiness. Completeness rules relax to warnings while draft/design. Approval is separate: `wairon lock` (human-run) validates the tree as if complete and records the approval in `.wai/lock.json`; it never rewrites a spec's `status`. A status is readiness, never design: it is left out of the approval, so promoting a spec to `complete` after the lock never reopens it (and never needs a re-lock).
 - **designDepth** (project `rules.designDepth`, per-subsystem override, or a pack profile's default): how deep the team COMMITS to designing — `components | interfaces | implementations | narratives` (default `narratives` = full depth). Expectation checks below the depth are gated (nothing deeper is demanded to exist); soundness of whatever IS authored always applies. Ask the user their intended depth at Stage 1 if unclear — do not assume a team that stops at L3 is "incomplete".
 - **publicInterfaces (L1)**: each entry MUST name the `component` realizing it. Its export kind is DERIVED from the backing Portal's `transport` — never author a `type`. Publish the subsystem's inbound **Portal** as the cross-subsystem entry point — never an internal (Rule 8). A contract consumers IMPLEMENT rather than call (a trait, a callback, a webhook) is exported with `role: implement` (typically the Adapter holding the port); the consumer's interface declares `implements: alias::name` and states every method with the same signature. Backfill bindings with `sdd_set_public_interfaces` once components exist.
 - **Subsystem consumers**: an entry may list `consumers: [<subsystem>, …]` — the subsystems the surface is published to. Absent, any subsystem may depend on it; present, only those may, and a dependency from any other subsystem is `CROSS_SUBSYSTEM_UNLISTED_CONSUMER` (an error). Use it for an internal Portal meant for one or two peers, so the boundary says who may call it.
@@ -110,7 +110,7 @@ schemas:
 - **Libraries are called directly**: another project's `InProcess` Portal (a crate, a package, a jar, an FFI/DLL surface) is called from ANY component — `alias::portal` in `dependsOn`, `alias::portal.verb` in a call step — with no client Adapter. Pure logic may call only library verbs declared `effect: none`, read logic also `effect: read` (`LIBRARY_CALL_IMPURE`); a native library (no `abi`) called from another `targetLanguage` needs `abi: c` or `abi: wasm` (`LANGUAGE_BRIDGE_MISSING`). Wrapping a volatile third-party API in your own Adapter is a good habit, not a rule. Within one project a sibling subsystem is still reached through a client Adapter or a `trustedLink`.
 - **Transport and naming**: name a Portal for what it serves, not its wire (`order_portal`, not `http_handler`); the `transport` says the wire. Method names follow the project's method casing — camelCase for TypeScript and Java, snake_case for Rust and Python, from `targetLanguage` unless `rules.naming` says otherwise — and a wire name that differs (an HTTP path, a CLI command like `lock-check`, a JSON-RPC method like `tools/call`) lives on the method's `endpoint`, never in the method name.
 - **trustedLinks (L1)**: `{ subsystem, reason }` — declared on the SOURCE subsystem, it licenses a direct in-process edge into the named sibling **without the client-Adapter shim** (the deliberate fast lane). The target must still be in the sibling's `publicInterfaces` (its published Portal); a target-side declaration grants nothing. It also acknowledges a mutual-dependency pair.
-- **Declare planned code at design time**: give each implementation the `sourcePath` its code will live at (and a method its own `sourcePath` when its body lives elsewhere). Code linkage — `sourcePath`, `symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers — is not part of the approval, so declaring or changing it never asks for a re-lock. A file not written yet is `SOURCE_FILE_PLANNED` (a notice, never a `--ci` failure) until the component's realization begins; never strip a planned path to quiet anything. A team that wants CI to demand code for every designed implementation sets `rules.conformance.requireCode: true`.
+- **Declare planned code at design time**: give each implementation the `sourcePath` its code will live at (and a method its own `sourcePath` when its body lives elsewhere) — and each TYPE the `sourcePath` of the file that will declare it (with `symbol` when the code name differs): a type without one is never compared with the code's shape, which is `MISSING_TYPE_SOURCE_PATH` (a notice while its subsystem has no code, a warning once it has). Code linkage — `sourcePath`, `symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers — is not part of the approval, so declaring or changing it never asks for a re-lock. A file not written yet is `SOURCE_FILE_PLANNED` (a notice, never a `--ci` failure) until the component's realization begins; never strip a planned path to quiet anything. A team that wants CI to demand code for every designed implementation sets `rules.conformance.requireCode: true`.
 - **Externals — the pin gates, live drift is visible**: declare a project this one consumes with `sdd_add_external` (alias; source `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>`; optional `project`, `use`, `description`) instead of editing `.wai/project.yaml`. It refuses in one sentence what cannot be declared, takes the declaration back out when the producer contradicts it (another id, an unexported `use` name), and pins it by default. The owner's gate judges each external against its pin; `sdd_validate_tree` and `sdd_get_status` add ADVISORY live-drift findings (`EXTERNAL_LIVE_INCOMPATIBLE`, `EXTERNAL_DRIFTED`, `EXTERNAL_LIVE_UNCOMPARED`) that never make the tree invalid — adapt the uses, then the human re-pins. `wairon externals status` is the human's opt-in live gate.
 - **Growing a system — subsystems → parts → projects**: boundaries are earned. Keep subsystems in one folder until a piece needs its own folder or repository; then make it a **part** — `members: { scheduler: services/scheduler }` (or `../admin`, or `git-url#<commit>`), created by `sdd_add_member` (a part by default) or `sdd_externalize_subsystem`. A part's subsystems stay this project's own: local ids, the ordinary subsystem rules, this project's lock. Make a **project** — its own id, exports and lock, referenced as `alias::name` — only when it needs its own team, release, approval or public surface: `sdd_promote_member`, and `sdd_demote_member` to undo it. What a member is follows from its content (an id, an L0 or a lock); `as:` only asserts it.
 - **Members & the family's shape**: relocate a member with `sdd_move_member`. Every other change of a family's shape is a **family migration**: `sdd_attach_member` (an existing project becomes a member), `sdd_detach_member` / `sdd_adopt_member` (out of the family and back), `sdd_rename_project`, `sdd_rename_member_alias`, `sdd_internalize_member` (a member folded back in, its metadata sent to explicit homes) and `sdd_externalize_subsystem`. Call it with `dryRun: true` first and show the human the plan; applied, it writes every project it touches or none, and it never locks — it names the projects to re-lock.

package/dist/templates/skills/sdd-delegate.md

@@ -24,7 +24,7 @@ You are the **Delegation Orchestrator**. Your job is to hand scoped work to a fo
    - Pick the agent whose `ownedPaths`/domain matches the task. If no agent fits, stop and tell the user the topology has a gap.
 2. **Fetch the LIVE brief**:
    - Call `sdd_get_agent_brief(agentId)` (or read the `wairon-agent://<agentId>` resource).
-   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`), and — when the project opted into `execution.tier` — `profile` and `budget`.
+   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`; TypeScript's table is the one code conformance reads back, while Rust's and Python's are mapping-only tables the code analyzer does not check, and the table says so), `codeFence?` (where the agent may write code — for a subsystem owner also the project's shared setup files: manifest, compiler settings, crate or package root), an `## Externals used` section for a component reaching another project (each alias, the names it uses, the producer's transport and abi, and the pinned snapshot `.wai/externals/<alias>.yaml`, which joins `readPaths` — code against the pin, never the producer's source), and — when the project opted into `execution.tier` — `profile` and `budget`.
    - **Never reuse a brief across delegations or after a re-lock** — fetch fresh per delegation; the call is cheap and the brief is always current.
 3. **Spawn a GENERIC subagent from the brief**:
    - Prompt: `brief.instructions`, plus the concrete task description.

package/docs/architecture.md

@@ -71,7 +71,7 @@ to the artifacts the host AI tool consumes:
   (`runWithProjectRoot`) — reusing the core, validation, and MCP layers unchanged.
 - **Everything is file-based** under `.wai/` — no database, and no daemon for the
   core workflow. `wairon serve` is an **opt-in** hosting daemon (see the
-  [hosted server guide](design/hosted-mcp-server.md)) that serves the same
+  [hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md)) that serves the same
   file-based tools over HTTP.
 
 ---

package/docs/cli.md

@@ -74,8 +74,11 @@ warnings as errors (notices are printed and counted, never fatal).
   **family root** (the project that declares the members). A member validated on
   its own judges its own gate with its `network` entries counted as declared, and
   says so in one line, so a green member run is never read as a proven one.
-  **In CI, run `wairon validate --ci` at the family root**; a member in its own
-  repository adds the root's run to its pipeline or relies on the root
+  **In CI, run `wairon validate --ci` at the family root**, after installing
+  the project's dependencies (`npm ci` or your package manager's equivalent —
+  the gate reads TypeScript/JavaScript code with the project's own TypeScript;
+  see [Using it in GitHub Actions](#using-it-in-github-actions)); a member in
+  its own repository adds the root's run to its pipeline or relies on the root
   repository's.
 - **Externals, compared live (advisory: the pin gates).** The gate judges each
   external against its pin. Then every external the run did not compose is
@@ -97,6 +100,58 @@ warnings as errors (notices are printed and counted, never fatal).
   `METHOD_SOURCE_PATH_MISSING` (warning). `rules.conformance.requireCode: true`
   in `project.yaml` reports the two notices as errors, for a CI that must say
   every designed implementation has code.
+- **Types are linked to code too.** A type spec without a `sourcePath` is
+  `MISSING_TYPE_SOURCE_PATH` — a notice before its subsystem has code, a
+  warning after. Plan a type's `sourcePath` when you plan the implementations'.
+- **What the closing line says.** Plain `validate` passes with warnings and
+  says so — `Passed with N warning(s)` (`--ci` fails on them); `All checks
+  passed` means none. A tree holding no design yet (no L0, or an L0 with nothing
+  below it) says there is nothing to check.
+- **Unknown keys are reported.** A key a spec's schema does not know (an
+  `exports:` table in the L0 — the export table is `publicInterfaces`; a
+  misspelt field) is `UNKNOWN_SPEC_KEY`, and an unknown setting in
+  `.wai/project.yaml` is `UNKNOWN_CONFIG_KEY` (both warnings): the parse would
+  otherwise drop them without a word.
+- **Code that crosses the design.** A call through a constructor-injected
+  collaborator is collaboration whatever the import's form: when its type comes
+  from a component the caller never declared, even through `import type`, it is
+  `UNDECLARED_DEPENDENCY`; a Portal calling a write- or lifecycle-effect method
+  of a Repository, Index, Store or Registry that way is
+  `PORTAL_WRITE_SHORTCUT_IN_CODE` (error, the code twin of
+  `PORTAL_WRITE_SHORTCUT`); and a file importing a technology's package
+  outside the components that bind it is `TECH_LEAKAGE_IN_CODE`. A technology's
+  packages are its declared tokens (its name, or its `matches`) plus the common
+  packages wairon knows for it — see [Technologies and their
+  packages](#technologies-and-their-packages). An Adapter's call step to a verb
+  of a Portal that declares an out-of-process transport (HTTP, gRPC, a
+  database, a bus, a CLI…) is the link the design models: it is never resolved
+  to the remote Portal's file, so it never reads as `CALL_ORIGIN_UNRESOLVED`;
+  the call to the Adapter stays checked. Likewise the Adapter's `dependsOn` to
+  that Portal is realized by the link, never reported `UNREALIZED_DEPENDENCY`:
+  never add an import across a network boundary to satisfy a check.
+
+#### Technologies and their packages
+
+`TECH_LEAKAGE_IN_CODE` compares each import's package with the packages of the
+technologies an implementation binds. A design writes the technology the way
+people say it (`postgres`) while the code imports its driver (`pg`), so wairon
+knows the common packages of the common technologies by default:
+
+| Technology (any of these names) | Packages |
+| --- | --- |
+| `postgres`, `postgresql`, `pg` | `pg`, `postgres`, `pg-promise`, `@neondatabase/serverless`, `@vercel/postgres` |
+| `mysql`, `mariadb` | `mysql2`, `mysql`, `mariadb` |
+| `redis`, `valkey` | `redis`, `ioredis`, `@redis/client` |
+| `mongodb`, `mongo` | `mongodb`, `mongoose` |
+| `sqlite`, `sqlite3` | `better-sqlite3`, `sqlite3`, `sqlite` |
+| `kafka` | `kafkajs`, `node-rdkafka` |
+| `rabbitmq`, `amqp` | `amqplib`, `amqp-connection-manager` |
+
+An HTTP client (`fetch`, `axios`, `got`, `undici`) is never a technology — it is
+how an Adapter reaches anything — so no entry names one. To extend the list,
+write the technology as `{ name, matches }` (each `matches` token is a package
+too), or have a pack contribute `technologyPackages: { <technology>: [<package>,
+…] }`.
 
 ### `wairon generate [--target <name>] [--domain <id>] [--domains <ids>] [--root] [--family] [--no-prune] [--global] [--dry-run]`
 Reconcile the generated guides, skills and context, and — only when the project
@@ -164,11 +219,27 @@ digests read each spec's **design**: where it is realized — `sourcePath`,
 out (`specsReading: design`). Linking code to an approved design, or a change and
 its revert, never stales the lock; declare planned `sourcePath`s at design time.
 
-A **format-2** record (written before this reading) still passes `lock-check`
-while nothing it covered moved. `wairon doctor --fix` re-expresses it as format 3
-in place — keeping `lockedAt`, `lockedBy`, the results and the member pins, and
-recording `reexpressed: { at, fromAlgorithm, fromReading, by }`. A format-2 record
-that no longer matches reads stale once; one `wairon lock` clears it for good.
+**Readiness is not part of the approval either.** A spec's `status` (`draft`,
+`design`, `complete`) says how far authoring is, never what the design says, so
+it is left out of the design view: promoting a spec to `complete` after the lock
+never reopens it. A format-3 record taken while the view still carried `status`
+keeps passing when nothing but a status moved — it is judged in the reading it
+was taken in, each spec's approved status recovered from its digest — and
+`wairon doctor --fix` carries it into the current reading without a review.
+
+A **format-2** record (written before code linkage left the approval) still passes
+`lock-check` while nothing it covered moved. `wairon doctor --fix` re-expresses it
+as format 3 in place — before any other repair touches a spec — keeping
+`lockedAt`, `lockedBy`, the results and the member pins, and recording
+`reexpressed: { at, fromAlgorithm, fromReading, by }`. When no spec file moved
+but the record still does not match, what moved is the **gate** it was judged
+under — the design rules of a newer wairon release, the project's rule tuning,
+`composition`, the network declaration, consumed contracts or a member's
+approval — never your design: `lock-check` and `doctor` say exactly that, `doctor
+--fix` still carries the record into the design reading (its claim stays as
+certified, so it reads stale for that stated cause), and one `wairon lock`
+re-approves the unchanged design. A format-2 record whose specs moved reads stale
+once; one `wairon lock` clears it for good.
 
 It writes **nothing into your spec tree**. The approval is one sha256 per spec
 (over its design view) on `.wai/lock.json`, the record that was always committed — so your
@@ -260,9 +331,12 @@ merging is the thing that was reviewed.
 
 #### Using it in GitHub Actions
 
-This repository publishes it as a **reusable workflow** (from v6.0.0 — the
-workflow and the `lock-check` command do not exist in earlier releases). Add one
-job to your own workflow:
+This repository publishes it as a **reusable workflow**. **6.0.0 is the first
+release that ships the workflow and the `lock-check` command** — earlier releases
+have neither, and no `v6.0.0` tag exists before that release. On a dev build (and
+until 6.0.0 is out), pin the dev tag matching `wairon --version` instead: a CLI
+reporting `5.1.1-dev.107` pins `@v5.1.1-dev.107` with `wairon-version:
+'5.1.1-dev.107'`. Add one job to your own workflow:
 
 ```yaml
 # .github/workflows/ci.yml in YOUR repository
@@ -286,6 +360,7 @@ With inputs (all optional):
       wairon-version: '6.0.0'           # version or npm dist-tag, 6.0.0 or later (default: latest)
       strict: true                      # fail when nothing was approved — use it once you have locked (default: false)
       validate: true                    # also run `wairon validate --ci` there (default: true)
+      install: auto                     # the project's dependencies before validate: auto | none | <command> (default: auto)
       node-version: '20'                # (default: '20')
       runs-on: ubuntu-latest            # (default: ubuntu-latest)
 ```
@@ -304,6 +379,44 @@ directory (`validate: false` turns it off). Point `working-directory` at the
 **family root** — the project that declares the members — so that run is the
 family run, which judges the network proofs no member's own gate can.
 
+**The project's dependencies come first.** The conformance gate reads
+TypeScript/JavaScript code with the project's own TypeScript compiler. A fresh
+checkout has none until the project's dependencies are installed, and then every
+file is analyzed below exact grade and `--ci` fails on `CONFORMANCE_DEGRADED` —
+a finding about the runner, not your design. So before `validate --ci` the job
+installs them with the project's own package manager (`install: auto`, the
+default): nothing without a `package.json`; otherwise the nearest lockfile from
+`working-directory` up to the repository root decides — `package-lock.json` →
+`npm ci`, `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`, `yarn.lock` →
+`yarn install` (`--immutable`, or `--frozen-lockfile` for Yarn 1). `install:
+none` skips it; any other value is run as the install command. The approval
+check alone (`validate: false`) installs nothing.
+
+#### Without the reusable workflow
+
+The same gate as plain steps — for another CI system, or a job of your own. For
+a TypeScript/JavaScript project with code, **install the project's dependencies
+before `wairon validate --ci`** (`npm ci`, `pnpm install --frozen-lockfile` or
+`yarn install --immutable`, whichever your lockfile is for):
+
+```yaml
+# .github/workflows/design.yml in YOUR repository
+on: [pull_request]
+
+jobs:
+  design:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install --global @wairon/cli@6.0.0   # the version you lock with
+      - run: wairon lock-check --strict
+      - run: npm ci                                    # the project's dependencies: the gate reads your code with your TypeScript
+      - run: wairon validate --ci
+```
+
 **A failing job does not block a merge on its own.** A workflow can only fail;
 making a failing job stop a merge is a branch-protection / ruleset setting on
 your repository ("Require status checks to pass" → add this job). No workflow
@@ -348,9 +461,12 @@ The design changes, so one `wairon lock` follows. After it, declare the entries
 the migration cannot know — a CLI, a stdio tool surface (`JSONRPC`), a library
 (`InProcess`) — and model a caller or remove each verb still reported unreached.
 
-`--fix` also re-expresses a format-2 lock record that still provably covers the
-tree as format 3 (see `wairon lock`), keeping who approved it and when; when it
-no longer covers the tree, doctor says that one `wairon lock` is needed.
+`--fix` also re-expresses an earlier lock record — format 2, or format 3 taken
+while `status` was still in the approval — in the current reading, first, before
+any repair touches a spec (see `wairon lock`), keeping who approved it and when.
+A format-2 record over a tree no file of which moved is carried into the design
+reading even when the gate it was judged under moved; doctor then says the cause
+(the gate, not the design) and that one `wairon lock` re-approves it.
 
 ### `wairon list` (alias `ls`) / `wairon show <id>`
 List, or show full details of, the agents resolved from the spec tree
@@ -544,7 +660,32 @@ promise and how a consumer follows renames).
 - A tree without an L0 is refused. The JSON Schema ships in the package as
   `schemas/design-export-1.json`, and the library twin is `exportDesign()`.
 
-### `wairon network flows|policy|diagram|check|why`
+### `wairon type rename-field <type> <field> <new-name>`
+Renames a field of a type and respells every reference to it — each foreign
+key `references: <type>.<field>` naming it, the type's own included. The field
+keeps its place, type and description; its old name joins the field's rename
+trace (`previousNames`), which `wairon export` shows as `formerly`, so a
+consumer holding the old name reads a rename, not a removal and an addition.
+Traces and prose are never rewritten. It refuses, writing nothing, a type or
+field that does not exist, a name that is not an identifier, and a name another
+field of the type holds or retired. The MCP twin is `sdd_rename_field`. As with
+any design edit, the next `wairon lock` approves it.
+
+### `wairon method rename-param <component> <method> <param> <new-name>`
+Renames a parameter of a contract method. The parameter moves on every
+interface of the component that declares the method, keeping its place, type,
+description and optionality; its old name joins the parameter's rename trace
+(`previousNames`), which `wairon export` shows as `formerly`, so a generator or
+consumer reads a rename, not a signature change. Each signature is re-derived
+from the params (a method whose `signatureFrom` names this one follows by
+itself), and an HTTP endpoint path placeholder `{old}` on the method's own
+binding is respelled — the URL a caller sends is unchanged. Prose is never
+rewritten. It refuses, writing nothing, a component, method or parameter that
+does not exist (or a parameter the method takes from a `signatureFrom`), a name
+that is not an identifier, and a name another parameter of the method holds or
+retired. The MCP twin is `sdd_rename_param`. The next `wairon lock` approves it.
+
+### `wairon network flows|policy|diagram|check|why|declare|undeclare`
 Networking derived from the design: the reach the validator already models
 (modelled calls, Portal entries and their scopes, declared networks and their
 gateways), never addresses. Run at the family root.
@@ -562,6 +703,9 @@ gateways), never addresses. Run at the family root.
   unknown verb.
 - `why <from> <to>` prints the modelled chain behind one flow. It exits 1
   when nothing allows it.
+- `declare [--description <text>]` writes the project's `network` declaration
+  into `.wai/project.yaml`; `undeclare` removes it (the assistant's twin is
+  `sdd_set_network`). It changes which rules fire: validate, then re-lock.
 
 [Derived networking](network.md) describes every output, the bindings file
 and the observed-flow format.
@@ -611,6 +755,60 @@ then move the pin with `wairon member update`. An uncached git part offline is
 declared `externals`, the name a public name in that project's L0 export table.
 An id without `::` is local — a part's subsystems included.
 
+**Authoring the L0 export table.** What another project may reference is the
+project's **L0 export table**: the `publicInterfaces` list of the L0 spec
+(`.wai/specs/.index.yaml`). It is authored in two steps, both through the MCP
+tools (an assistant runs them; a human may edit the YAML the same way):
+
+1. Each subsystem publishes its own surface — its inbound Portal, and the types
+   it shares — with `sdd_set_public_interfaces` (an L1 `publicInterfaces`).
+2. The L0 **re-exports** from those subsystems with `sdd_update_spec` on kind
+   `system`, delta `publicInterfaces`. Each entry names a subsystem in `from`;
+   `from` alone re-exports everything it publishes, `component` (optionally
+   narrowed with `interface`) or `typeDef` picks one item, `as` renames it
+   (the public name consumers write after `alias::`), `role: implement` marks
+   an extension point consumers implement, and `audience` decides who may see
+   it (below).
+
+```yaml
+# .wai/specs/.index.yaml (excerpt)
+publicInterfaces:
+  - from: distance            # everything the distance subsystem publishes
+  - from: tiles
+    component: tile_portal
+    as: tiles                 # consumers write geo::tiles
+    audience: external
+  - from: shared
+    typeDef: coordinate       # a shared type, as geo::coordinate
+```
+
+The key is `publicInterfaces` — an `exports:` (or any other key the schema does
+not know) is reported as `UNKNOWN_SPEC_KEY`, never silently ignored, and an
+unknown setting in `.wai/project.yaml` as `UNKNOWN_CONFIG_KEY`. A reference to a
+name the producer does not export is `EXTERNAL_NOT_EXPORTED`.
+
+**Export audiences.** Each L0 entry carries an `audience` (default `instance`)
+that decides who may see the public name. Narrowest first:
+
+| Audience | Who sees it |
+|----------|-------------|
+| `project` | Only this project's family: its members, its parent and their siblings. |
+| `department` | The family, and — on a hosted instance — the projects of the owning department. A local sibling checkout or git consumer does **not** see it. |
+| `instance` | The default. Any project on the instance, and any local consumer by path or git. |
+| `partner` | Also consumers outside the instance that a partner grant admits. |
+| `external` | Publicly consumable. |
+
+A consumer is read at one audience: a family project at `project`, so it sees
+everything; a path, git or hosted consumer outside the family at `instance`, so
+it sees `instance`, `partner` and `external` entries only. A name exported to a
+narrower audience is refused by `externals add` (and `externals use`), naming
+the export's audience, the consumer's and this ranking. Because a project cannot
+tell from its own tree whether its consumers are hosted department units,
+`validate` notes every `department` export (`EXPORT_AUDIENCE_NARROW`, a
+notice): widen it to `instance` when a sibling checkout or a git consumer uses
+it, or keep it and allow the notice. A re-export can narrow an audience, never
+widen it (`EXPORT_WIDENS_AUDIENCE`).
+
 | Command | Description |
 |---------|-------------|
 | `wairon member add <alias> <source> [--project] [--description <text>]` | Create a member at `<source>` (`path`, `../path` or `git-url[#commit]`) and declare it by the shorthand. A **part** by default: a specs folder (and, outside this project, its `partOf`). With `--project` a project: its `project.yaml` declaring `<alias>` as its id and its L0, each only when absent. A git member is never scaffolded: it is pinned at the commit given, else the default branch head, and its content decides what it is |
@@ -657,7 +855,13 @@ included); applying it stages every change with a backup under each project's
 `.wai/transactions/<id>/` (never committed) and swaps them in, restoring every
 backup on any failure. A crash mid-swap leaves a journal: `wairon status` and
 `wairon validate` show it as a notice, and `wairon doctor --fix` rolls it back.
-No verb ever locks — each names the projects to re-lock. A member stored in a
+No verb ever locks — each names the projects to re-lock. A promote (or `externalize --as project`) re-roots every
+source path that moves with the new project: a path inside the new project's folder becomes
+member-relative, and one outside it (source code you have not moved yet) becomes a member-relative
+*planned* path — `SOURCE_FILE_PLANNED`, never a path that escapes the root — so the new project
+validates on day one and you move the code when you are ready. A topic finding
+(`UNCONSUMED_TOPIC`, `UNSOURCED_SUBSCRIPTION`) is sited at its topic: an allow names it
+with `at: <topic>`. A member stored in a
 `../` sibling checkout on the same volume joins the same transaction: its files
 change all-or-nothing with the family's, the coordinator's journal names every
 owner (so `wairon doctor --fix` recovers from either root), and the plan says
@@ -731,21 +935,23 @@ project, so it holds nothing machine-specific: it runs `wairon mcp serve` from t
 and the server attaches to the project it is started in. A `--global` registration is
 machine-wide and names the running CLI by its absolute path.
 
-The local server offers 38 tools:
+The local server offers 47 tools:
 
 | Group | Tools |
 |-------|-------|
 | Topology (read) | `listAgents`, `getAgent`, `listDomains`, `validateTopology`, `getProjectConfig` |
 | Authoring | `sdd_initialize_system`, `sdd_add_subsystem`, `sdd_set_public_interfaces`, `sdd_add_component`, `sdd_define_interface`, `sdd_set_endpoints`, `sdd_write_narrative`, `sdd_add_type`, `sdd_update_spec`, `sdd_delete_spec` |
 | Reading and checking | `sdd_get_spec`, `sdd_get_status`, `sdd_validate_tree` |
-| Renames and moves (in this tree) | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_type`, `sdd_move_methods` |
+| Renames and moves (in this tree) | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_param`, `sdd_rename_type`, `sdd_rename_field`, `sdd_move_methods` |
 | Members and family migrations (each takes `dryRun`) | `sdd_add_member`, `sdd_move_member`, `sdd_externalize_subsystem`, `sdd_promote_member`, `sdd_demote_member`, `sdd_internalize_member`, `sdd_attach_member`, `sdd_detach_member`, `sdd_adopt_member`, `sdd_rename_project`, `sdd_rename_member_alias` |
-| Externals | `sdd_add_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
+| Externals | `sdd_add_external`, `sdd_update_external`, `sdd_remove_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
+| Public surface (the producer's side) | `sdd_list_consumers`, `sdd_surface_diff` |
+| Network | `sdd_set_network`, `sdd_get_network_flows`, `sdd_explain_flow` |
 | Packs | `sdd_pack_impact` |
 | Delegation | `sdd_get_agent_brief` (the live brief for one agent; also served as the `wairon-agent://` resource) |
 
 A hosted server adds its own `sdd_host_*` and `sdd_landscape_*` tools; see the
-[hosted server guide](design/hosted-mcp-server.md).
+[hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md).
 
 ---
 
@@ -755,7 +961,7 @@ A hosted server adds its own `sdd_host_*` and `sdd_landscape_*` tools; see the
 projects behind one endpoint — a public **data plane** (the `sdd_*` tools over
 streamable HTTP, per-project API-key scoped) and an admin **control plane**
 (project & key lifecycle, state-scoped lock). See the
-[hosted server guide](design/hosted-mcp-server.md) for the architecture, Docker
+[hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md) for the architecture, Docker
 self-hosting, auth, and sizing.
 
 ### `wairon serve [--host <h>] [--port <p>] [--admin-host <h>] [--admin-port <p>] [--data-dir <path>] [--no-auth]`
@@ -851,10 +1057,13 @@ return the impact of every pack they applied in their results.
 
 | Command | Description |
 |---------|-------------|
-| `wairon externals add <alias> [<source>] [--project <id>] [--ref <ref>] [--dir <dir>] [--use a,b\|'*'] [--description <text>] [--no-pin] [--dry-run] [--json]` | Declare one external in `.wai/project.yaml`. The source is the location grammar members use: `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>` (the commit is the ref the pin follows, fixed there); omit it when the family provides the producer. It is checked against the producer it reaches: one answering to another id, or not exporting a `use` name to this project, takes the declaration back out and names the id or the closest exported names. Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why. A refusal is one sentence naming the accepted form, and exits 1 |
-| `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`; exits 1 when an alias could not be pinned (unresolved or unreachable — its previous pin stays) |
-| `wairon externals status [--json]` | Each pin compared with its live producer per used member — `unchanged`, `changed`, `renamed` (with the new name), `removed`, `unlocked`, `unavailable` — and each external's health (`incompatible`, `not compared`, `drifted`, `ok`). Git producers are fetched. The opt-in **live** gate: exits 1 when any external is incompatible, 2 when nothing is incompatible but something could not be compared (never a pass), 0 otherwise |
-| `wairon externals list [--json]` | The declared externals, how each resolves and what is pinned; a malformed declaration is listed with its problem, never hidden |
+| `wairon externals add <alias> [<source>] [--project <id>] [--ref <ref>] [--dir <dir>] [--use a,b\|'*'] [--description <text>] [--no-pin] [--dry-run] [--json]` | Declare one external in `.wai/project.yaml`. The source is the location grammar members use: `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>` (the commit is the ref the pin follows, fixed there); omit it when the family provides the producer. Text that is no location (braces, quotes, whitespace) is refused. The declaration is checked against the producer it reaches **before** anything is written — `--dry-run` included: one answering to another id, or not exporting a `use` name to this project, is refused naming the id, the closest exported names, or the narrower audience the name is exported to (see Export audiences). Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why, and exits 2 (nothing was pinned). A refusal is one sentence naming the accepted form, and exits 1 |
+| `wairon externals use <alias> [--add a,b\|'*'] [--remove c] [--dry-run] [--json]` | Change one declared external's `use` imports, so the specs may name the producer's public names bare (e.g. so an `implements` of the producer's trait spells its types as the producer does — though `alias::name` and the bare imported name compare as one type either way). An added name the producer does not export to this project is refused. The pin is untouched. Exits 1 on a refusal |
+| `wairon externals remove <alias> [--dry-run] [--json]` | Remove one external: its declaration and its pin (`.wai/externals/<alias>.yaml` and its lock entry) together. An orphaned pin — one whose declaration was deleted by hand, which `externals list` shows — is removed too. Exits 1 when the alias is neither declared nor pinned |
+| `wairon externals consumers [--json]` | From a producer's root: the family projects in reach that consume it — each with the alias and section it declares it under and the public names its specs use — so a producer sees who breaks before it changes its surface. A sibling checkout, git or hosted consumer outside the family declares its dependency on its own side and is not visible here |
+| `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`. The snapshot is rewritten whenever anything it carries moved — not only the signatures the digest covers: a producer that added `abi: c`, changed a transport or a role, or recorded a rename is refreshed by a re-pin. Exits 1 when an alias could not be pinned (unresolved or unreachable — its previous pin stays) |
+| `wairon externals status [--json]` | Each pin compared with its live producer per used member — `unchanged`, `changed`, `renamed` (with the new name), `removed`, `unlocked`, `unavailable` — and each external's health (`incompatible`, `not compared`, `drifted`, `ok`); a pinned snapshot that no longer carries what the producer says (a stale `abi`, transport or role) is `drifted`, never `ok`, and names the stale facts. A use the lock does not hold is still compared with the live producer: gone from it, it is `removed` or `renamed`. Git producers are fetched. The opt-in **live** gate: exits 1 when any external is incompatible, 2 when nothing is incompatible but something could not be compared (never a pass), 0 otherwise |
+| `wairon externals list [--json]` | The declared externals, how each resolves and what is pinned; a malformed declaration, and an orphaned pin whose declaration is gone, are listed with their problem, never hidden |
 | `wairon surface export \| import \| list [--audience <level>] [--format native\|openapi] [--portal <id>] [--out <path>] [--source <path>]` | Exchange a public surface document: export this project's (native snapshot or one OpenAPI document per portal), import one, or list them |
 | `wairon produce <notion\|miro> [--page <id>] [--token <token>]` | Project the local spec tree to Notion or Miro (the token comes from `--token`, the environment, else a prompt; nothing is stored) |
 

package/docs/extending-wairon.md

@@ -9,7 +9,7 @@ rules) that wairon reads and imports. A product built this way (a
 wairon installation: no fork, no build step, and wairon core never learns
 the platform exists.
 
-A working wrapper lives at [`examples/wrapper/`](../examples/wrapper/) and
+A working wrapper lives at [`examples/wrapper/`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/) and
 is guarded by `tests/examples/wrapper-example.test.ts`, so it cannot
 silently rot.
 
@@ -17,7 +17,7 @@ silently rot.
 
 > **New model (preferred).** Installing a pack makes it *available*; a project
 > then *selects* it. Installing no longer grants a pack authority over every
-> project on the machine — see [pack scoping](design/pack-scoping.md).
+> project on the machine — see [pack scoping](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/pack-scoping.md).
 
 ```sh
 wairon pack install ./appenser-1.2.0.wpack   # into this wairon install's store
@@ -101,6 +101,7 @@ project's doctrine anywhere:
 - uses: SYW-Apps/Waffle-AIron/.github/actions/setup-wairon@v5
   with:
     packs: sync          # sync (default) | none (bundled repos) | explicit sources
+- run: npm ci            # a TS/JS project with code: its own dependencies first (see docs/cli.md)
 - run: wairon validate --ci
 ```
 
@@ -267,7 +268,7 @@ wairon pack add ./my-product-pack --global   # machine-wide
 
 The installer injects once and leaves — from then on plain `wairon
 validate` enforces the doctrine, and `wairon pack remove` undoes it. See
-[`examples/wrapper/install.js`](../examples/wrapper/install.js) for the
+[`examples/wrapper/install.js`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/install.js) for the
 template. A spec-only product (implementation lives on a cloud platform)
 needs nothing more: the wrapped repository holds specs + docs, wairon holds
 the gate.
@@ -595,7 +596,7 @@ project's externals against their live producers, and the family checks),
 `globalPacksDir`, `discoverPacks`, `setProjectRoot`, the `SddRule` /
 `RuleContext` / `LoadedExtensions` / `DeclarativePack` types, `SDD_RULES`,
 `composeRuleSequence`, and the spec loaders/savers. See
-[`examples/wrapper/wrapper.js`](../examples/wrapper/wrapper.js).
+[`examples/wrapper/wrapper.js`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/wrapper.js).
 
 ## Spec-only wrappers
 

package/docs/network.md

@@ -1,27 +1,32 @@
 # Derived networking: `wairon network`
 
-wairon derives a system's network from its design. The inputs are the calls you model, the entries you declare on Portals (`invokedBy: {kind: entry, scope: outside | network}`), the networks your projects declare (`network: true` in `.wai/project.yaml`) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+wairon derives a system's network from its design. The inputs are the calls you model, the entries you declare on Portals (`invokedBy: {kind: entry, scope: outside | network}`), the networks your projects declare (`network` in `.wai/project.yaml`, written by `wairon network declare [--description <text>]` — `undeclare` removes it — or by the assistant's `sdd_set_network` tool) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+
+**The gate comes first.** Every network command reads the design as the validator judges it. A flow an error sits on (`GATEWAY_BYPASSED`, ...) is **refused**: the matrix marks its row `REFUSED` with the findings, a policy never admits it (and `policy` exits 1, naming it at the head of the file), `why` answers that the gate refuses it, and `check` files an observed flow that only a refused flow would allow as disallowed. A warning (`ENTRY_UNPROVEN`, ...) only marks its row. Each command prints the findings it was judged against.
 
 Specs never hold an address, a port, a namespace or a label. Those deployment facts come from a **bindings file** that the team keeps outside `.wai/` and passes when generating policy. The design stays logical, and the deployment stays yours.
 
-Every command runs at the project you are in. At a project that declares members, the commands cover its whole family; `--no-recursive` limits them to that project alone. Run them at the family root: only the family run can narrow a `network` entry to the callers it really has.
+Every command runs at the project you are in. At a project that declares members, the commands cover its whole family; `--no-recursive` limits them to that project alone. Inside a member, they answer from the enclosing family — the parent's network declaration and the callers the parent models, the same answer the family root gives — and `--no-recursive` judges the member alone. Only the family run can narrow a `network` entry to the callers it really has.
 
 ## The outputs, and what each is for
 
 | Command | Output | What a team does with it |
 |---|---|---|
-| `wairon network flows [--format json\|csv\|markdown] [--out <file>]` | The **allowed-flows matrix**: one row per flow (from, to, transport, binding, networks crossed, gateway, evidence) | Review it in pull requests as the authoritative "who talks to whom". A design change that adds a dependency shows up as a new row before any code or firewall change exists. The CSV suits spreadsheets and audits, and the Markdown suits review comments. |
-| `wairon network policy --bindings <file> [--out <file>]` | **Kubernetes `NetworkPolicy`** YAML: one ingress policy per called workload | Commit it to the deployment repository and diff it in CI. A design change becomes a policy diff that the security reviewer reads in the same PR. |
+| `wairon network flows [--format json\|csv\|markdown] [--out <file>]` | The **allowed-flows matrix**: one row per flow (from, to, transport, binding, networks crossed, gateway, evidence) | Review it in pull requests as the authoritative "who talks to whom". A design change that adds a dependency shows up as a new row before any code or firewall change exists. The CSV suits spreadsheets and audits, and the Markdown suits review comments. A design that fails the gate exits 1. |
+| `wairon network policy --bindings <file> [--out <file>]` | **Kubernetes `NetworkPolicy`** YAML: one ingress policy per called workload | Commit it to the deployment repository and diff it in CI. A design change becomes a policy diff that the security reviewer reads in the same PR. A design that fails the gate exits 1: the refused flows are left out and named at the head of the file. A design name the bindings leave unbound also exits 1. |
 | `wairon network diagram [--out <file>]` | A **Mermaid** flowchart: declared networks as nested boundaries, gateways on them, an `outside` node, and flows aggregated per workload pair | Use it as the data-flow diagram with trust boundaries that threat modelling starts from: each boundary an edge crosses is a place to ask the STRIDE questions. It also works for onboarding and on architecture pages. The hosted canvas draws the same picture in its **Network** view (`/canvas/<project>/network`; the system spec's `diagram.defaultView: network` opens the canvas there). |
-| `wairon network check --observed <file> [--bindings <file>]` | **Unexpected** flows (seen, but nothing allows them), **unknown verbs** (an allowed pair, but a method and path no contract declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected or unknown, so it can gate a pipeline. Unexercised flows are review items, such as dead dependencies or rules to tighten, and never fail the command. |
-| `wairon network why <from> <to>` | The modelled chain behind a flow: the entry or call step, each network entered, the gateway, and the verb with its binding | Answer a firewall change request or an incident question ("why does checkout talk to payments?") from the design, in one command. Exits 1 when nothing allows the flow, and names what does reach the target instead. |
+| `wairon network check --observed <file> [--bindings <file>]` | **Unexpected** flows (seen, but nothing allows the pair), **disallowed** flows (a verb the destination declares, but not allowed from that source, or only by a flow the gate refuses), **unknown verbs** (an allowed pair, but a method and path no contract of the destination declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected, disallowed or unknown, so it can gate a pipeline. Unexercised flows are review items, such as dead dependencies or rules to tighten, and never fail the command. |
+| `wairon network why <from> <to>` | The modelled chain behind a flow: the entry or call step, each network entered, the gateway, and the verb with its binding | Answer a firewall change request or an incident question ("why does checkout talk to payments?") from the design, in one command. Exits 1 when nothing allows the flow, and names what does reach the target instead; says so when the gate refuses the flow, when a name is unknown (a typo, not a refusal), and — exiting 0 — when the callee is reached in-process, which is never a network flow. |
+| `wairon network declare [--description <text>]` / `undeclare` | Writes (or removes) `network` in `.wai/project.yaml` | Declare the boundary without a hand edit. It changes which rules fire, so validate, then re-lock. |
 
-The MCP server offers the same reads to an assistant while it designs: `sdd_get_network_flows` (optionally `to: <project | portal | portal.verb>`) and `sdd_explain_flow` (`from`, `to`). The hosted server serves the view model at `GET /web/projects/network?projectId=…`.
+The MCP server offers the same reads to an assistant while it designs: `sdd_get_network_flows` (optionally `to: <project | portal | portal.verb>`) and `sdd_explain_flow` (`from`, `to`), and the declaration as `sdd_set_network` (`declared`, `description`). The hosted server serves the view model at `GET /web/projects/network?projectId=…`.
 
 ### What becomes a flow
 
 - Only **network transports** produce flows: HTTP, gRPC, GraphQL, MessageBus and Custom. In-process libraries, CLI commands, IPC and JSON-RPC over stdio never do.
 - A **modelled call** into a network verb from another subsystem or project is a flow from the calling component. It names the networks it enters and the gateway it passes.
+- A verb's **binding** is the path a cluster sees: an HTTP endpoint is joined under its Portal's `basePath` (`basePath: /v1` and `POST /orders` bind `POST /v1/orders`), so L7 checks match real paths.
+- An **Adapter's transport** is its target Portal's: the Adapter calls the Portal's verbs over it. An Adapter may state one (`sdd_add_component` fills it in from the Portal its `dependsOn` names); a stated transport that disagrees with the target's is `ADAPTER_TRANSPORT_MISMATCH`, so changing a Portal's transport shows its impact on every Adapter that calls it.
 - An **`outside` entry** is a flow from outside the verb's innermost network. For an outermost network that is the world (`outside`); for a nested network it is the next network out (`network:<parent>`). Scopes are relative.
 - A **`network` entry** is a flow from anywhere inside the network. At the family root, when modelled callers prove the entry, the blanket row is replaced by those callers. The matrix is therefore least-privilege by construction: "the network may reach this" becomes "these two Adapters reach this".
 
@@ -36,7 +41,7 @@ The MCP server offers the same reads to an assistant while it designs: `sdd_get_
 - A component, as `project::component` or bare for the root's own.
 - On the receiving end, also `project::portal.verb`.
 
-Each party has a **default workload name**: a member's project key, or for the root project's own components their subsystem. When the root's component reaches into another project, the caller is named by its component.
+Each party has a **default workload name**: a member's project key, or for the root project's own components their subsystem — also when the root's component reaches into another project: the caller is named by its workload (its subsystem, the pod it runs in), with the component kept for the evidence, so a bindings file written per service keeps covering it after a callee is promoted.
 
 ## The bindings file
 
@@ -64,7 +69,11 @@ outside:                           # what "outside" means for a policy
 - `outside` lists the CIDR blocks admitted for callers from outside, for example the internet, a load balancer range or an intranet. Without it, nothing from outside is admitted.
 - A source in another namespace gets a `namespaceSelector` on `kubernetes.io/metadata.name`. A network-wide source bound without a namespace matches in any namespace (`namespaceSelector: {}`).
 
-**Nothing is guessed.** A design name the bindings do not map is selected by the placeholder label `wairon.dev/workload: <name>`, which matches no pod until you bind it or label one. It is listed in the document and on stderr, and at the top of the output under `# UNBOUND:`. MessageBus flows travel through the broker rather than pod to pod, so they are listed as `# NOT EXPRESSED` instead of opening ingress. Default deny is implied: each policy selects its workload and admits only what the design allows.
+**Nothing is guessed.** A design name the bindings do not map is selected by the placeholder label `wairon.dev/workload: <name>`, which matches no pod until you bind it or label one. It is listed in the document and on stderr, and at the top of the output under `# UNBOUND:`, and `policy` exits 1 so a pipeline notices. MessageBus flows travel through the broker rather than pod to pod, so they are listed as `# NOT EXPRESSED` instead of opening ingress. Default deny is implied: each policy selects its workload and admits only what the design allows.
+
+**Renamed projects.** A bindings key, or a name in an observed-flow file, that is a project's former id (its rename trace, `previousIds`) still resolves to the renamed project, and the output carries a `# NOTE` naming the rename, so you can update the key at your pace instead of finding a policy that selects nothing or a legitimate flow filed as unexpected. `wairon project rename` lists the binding and telemetry keys to rename in its plan.
+
+**Mixed reach.** A NetworkPolicy cannot split traffic by path. When one workload serves verbs of different reach on one port — a verb entered from `outside` and a verb only the network may call — its policy has to admit the union, and `policy` says so in a `# NOTE` naming the verbs. To keep the narrower verb narrow at L4, bind the Portal on its own (a `<project>::<portal>` key with its own selector or port): it then gets a policy of its own.
 
 ## The observed-flow format
 
@@ -88,6 +97,7 @@ Or JSON with the same fields, as a list or as `{ "flows": [...] }`:
 - A row without `method` and `path` is an L4 observation: it exercises every allowed flow between the pair.
 - A row with both is checked at L7 against the verbs' bindings. `{id}` and `:id` path segments match any value, and gRPC paths (`/pkg.Service/Method`) match the `service/method` binding.
 - A malformed row (no source or destination, or a non-integer count) is refused with its row number, and nothing is half-read.
+- A name that is a project's former id is mapped to the renamed project, with a `# NOTE` (see **Renamed projects** above).
 
 ## A typical loop