@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/README.md

@@ -1,41 +1,172 @@
 # loam
 
-**Architecture-first spec framework for microservice fleets.**
+**Architecture-first semantic integrity and change governance for evolving software systems.**
 
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node: >=22.22.3](https://img.shields.io/badge/node-%3E%3D22.22.3-brightgreen.svg)
 [![CI](https://github.com/ybotok/loam/actions/workflows/ci.yml/badge.svg)](https://github.com/ybotok/loam/actions/workflows/ci.yml)
-<!-- once published: [![npm](https://img.shields.io/npm/v/@ybotok/loam.svg)](https://www.npmjs.com/package/@ybotok/loam) -->
-
-> **Pre-release: `0.1.0-beta.1`.** Every command below is implemented and covered by tests; the package is not on npm yet. See [Status](#status).
-
-`loam` gets a service's documentation and C4 architecture written **from its code**, then lets you drive cross-service features top-down: you author a **C4 delta**, `loam` projects it onto each affected service as concrete work, and `loam gherkin` turns the spec's scenarios into real, digest-stamped Gherkin `.feature` files — the acceptance skeleton that drives TDD, kept honest by `loam validate` reporting when the spec moves under it.
+[![npm](https://img.shields.io/npm/v/@ybotok/loam/alpha.svg?label=npm%20alpha)](https://www.npmjs.com/package/@ybotok/loam)
+
+> **Pre-release: `0.2.0-alpha.13`** is the version this checkout's `package.json` names, on the 0.2
+> line of [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam). Whether npm serves it is not
+> something this file can know — a version is cut before its publish runs, and a publish can fail
+> after — so **the npm dist-tags are the source of truth**: the badge above reads the `alpha` tag, and
+> `npm view @ybotok/loam dist-tags` prints every tag. Prereleases publish under `alpha`, so
+> `npm i @ybotok/loam@alpha` installs the newest one that did. `latest` is moved onto a release by
+> hand once it has published, so a plain `npm i @ybotok/loam` resolves to an earlier release until it
+> is moved. See [Status](#status).
+
+`loam` keeps an authored C4 model, requirements, API and event contracts, permissions, domain
+vocabulary and verification evidence in explicit agreement as a system changes. The same lifecycle
+governs a modular monolith, a distributed service fleet, or a hybrid of both; the CLI and filesystem
+call each governed implementation boundary a `service`, but it need not be a network service.
+
+For an existing boundary, `loam` briefs an agent to document it **by reading its code**, then checks
+the result without pretending to extract architectural meaning itself. Forward changes start from
+an authored C4 delta: `loam` projects it onto each affected boundary, generates digest-stamped
+Gherkin, and checks that behavior, architecture, contracts and evidence still join.
 
 ## Contents
 
-- [Why](#why) · [Install](#install) · [Quick start](#quick-start) · [loam vs OpenSpec](#loam-vs-openspec)
-- [Day zero: onboarding a fleet](#day-zero-onboarding-a-fleet) · [Two flows](#two-flows) · [Principles](#principles)
-- [Commands](#commands) · [Command notes](#command-notes) · [Working with AI agents](#working-with-ai-agents) · [Fleet scale](#fleet-scale)
-- [Docs](#docs) · [Development](#development) · [Status](#status) · [Contributing](#contributing) · [Security](#security) · [License](#license)
+- [Why](#why) · [System shapes](#one-lifecycle-several-system-shapes) · [Install](#install) ·
+  [Quick start](#quick-start) · [Commands](#commands) · [Working with AI agents](#working-with-ai-agents)
+- [Docs](#docs) · [Development](#development) · [Status](#status) · [Contributing](#contributing) ·
+  [Security](#security) · [License](#license)
+- Companion pages: [QUICKSTART.md](QUICKSTART.md) — install-to-first-change ·
+  [WORKFLOW.md](WORKFLOW.md) — the protocol · [SCHEMA.md](SCHEMA.md) — the reference ·
+  [ROADMAP.md](ROADMAP.md) · [COMPARISON.md](COMPARISON.md)
 
 ## Why
 
-Spec-driven development tools treat specs as business-analyst-level documents: there is no architecture layer, and even where planning is shared across repos no service topology is modelled — while a business-simple feature can span many services (e.g. 7 new + 4 changed). C4 diagrams, Gherkin and specs end up as disconnected documents that drift apart quietly. `loam` ties them with one feature-ID spine and makes C4 the center. And because a business spec will never mention the transactional outbox, architecture gets its own requirement axis — `arch.spec.md`, whose `Covers:` lines tie outbox/retry/alert obligations to the C4 elements and health signals they exercise, with coverage derived mechanically rather than trusted.
+Software architecture does not live in one artifact. A business-simple feature can cross modules,
+processes or services while C4 diagrams, requirements, API contracts, permissions and test evidence
+drift independently. `loam` makes the authored C4 model the center and gives those artifacts
+referential integrity: every join below is an exact token spelled in two places, never a heuristic
+over prose.
+
+| The join | Ties |
+|---|---|
+| `Operations:` ↔ OpenAPI `operationId` | a requirement to the endpoint it governs |
+| `Publishes:` / `Consumes:` ↔ AsyncAPI message names | a requirement to the event spine |
+| `Covers:` ↔ C4 elements, `#obl-` tags, `health.yaml` ids | an architectural obligation to what it accounts for |
+| `Requires:` ↔ `architecture/permissions.yaml` | a requirement to the system-wide authorization vocabulary |
+| `Realizes:` ↔ `capabilities/<cap>/spec.md` | a service requirement to the business promise it keeps |
+| `#cap-` / `#req-` on a `dynamic view` ↔ a capability requirement | a cross-service use case to the promise it keeps |
+| a Markdown link ↔ `glossary/<term>.md` | a document to the word it uses |
+
+Architecture has its own requirement axis (`arch.spec.md`) because a business spec will not mention
+the transactional outbox, retries or alerts.
+
+### One lifecycle, several system shapes
+
+Topology changes where loam's checks pay off; it does not change the lifecycle:
+
+- **A modular monolith is one governed boundary.** Bind one root element to one
+  `services/<app>/` directory and draw modules, components and their relationships beneath it.
+  `Covers:` can name those nested elements and edges, and a feature's `delta.likec4` can change
+  them through the same validate/archive transaction as any fleet change.
+- **A distributed system is several governed boundaries.** Each service gets its own directory and
+  binding; cross-boundary edges can join to provider OpenAPI operations or AsyncAPI messages, and a
+  feature is projected onto every boundary it touches.
+- **A hybrid uses both shapes at once.** A modular application can sit beside independently
+  deployed services and external systems in the same landscape. The binding, not the C4 kind or
+  nesting depth, decides which `services/<id>/` owns an element.
+
+For example, the frozen `service` term can name an application while its internal modules remain
+ordinary C4 elements. This is `architecture/landscape.likec4`, the fleet map — the one document
+that declares the kinds:
+
+```likec4
+specification {
+  element softwareSystem
+  element component
+}
+
+model {
+  commerce = softwareSystem 'commerce-app' {
+    metadata {
+      service 'commerce-app'
+    }
+
+    orders = component 'Orders module'
+    billing = component 'Billing module'
+    orders -> billing 'Reserves credit'
+  }
+}
+```
+
+The modules can equally live in `services/commerce-app/model.likec4`, which is the ordinary place
+for them once the application has one — as an **extending model**, declaring no kinds of its own and
+saying `extend commerce { … }` on the element above. SCHEMA.md's "Two shapes of a service model" has
+that shape, the older one that parses alone, and the rule that picks between them.
+
+An internal edge normally carries no `metadata { op }`: that key specifically joins a call to the
+governed boundary's OpenAPI contract. An architecture requirement can instead say
+`Covers: commerce.orders -> commerce.billing`. Fleet-level maturity, dependency and scorecard views
+still aggregate at the bound `service`; nested elements get architecture coverage and feature
+lifecycle, not a separate deployment status invented for each module.
+
+**There is no extractor, and there will not be one.** Nothing deterministic reads a legacy service
+and says what its architecture *means*, and a model that was guessed is worse than none — everyone
+downstream has to re-derive it to know whether to believe it. So loam takes the half of the job that
+is mechanical: it **states the work** and it **checks the result**. An agent does the reading, and
+both halves are written down: the question in the brief or the checklist, the answer in `sources` or
+the verification record.
+
+### What green means here, and what it does not
+
+Most of this category will tell you what it checks. loam ships the other list too, in the binary:
+**[`src/core/brief/unchecked.ts`](https://github.com/ybotok/loam/blob/main/src/core/brief/unchecked.ts)
+is seventeen statements of what no check will ever tell you**, printed into the adoption brief beside
+the checks that do run. It says, in loam's own words, that nothing here knows whether the model is
+the architecture the code actually has, whether a requirement is *true*, whether an `operationId` is
+the one the code serves, or whether `sources` names the files anybody read. And it says the one that
+matters most: **completeness is unchecked** — forty behaviours documented as one requirement passes
+every check loam has, and so does a service with one endpoint documented out of thirty.
+
+That list exists because a check that is silent for want of anything to ask must never read as a
+check that passed. Green here means *the documents agree with each other* — never that they are
+true, and never that they are complete.
+
+The same refusal runs through the evidence model. `loam verify` records who answered every claim,
+and keeps two answers permanently distinguishable:
+
+- **`verified`** — a digest-tagged scenario answered by a green test run. The digest is taken over
+  the scenario's *body*, so rewording a `Given` breaks the link on purpose. Tag-based coverage
+  (`@REQ-1234` and its relatives) survives any rewrite and goes on asserting a claim nobody
+  re-checked.
+- **`attested`** — an agent's word, with `file:line` evidence at an attested commit. Recorded in
+  full, labelled on every surface, and never promoted. A feature whose scenarios rest on attestation
+  does not become verified because a gate would be greener if it did.
+
+Neither gates the archive. The claim loam makes for its evidence is persistence and honest
+provenance — not that every recorded judgement is true.
+
+Files stay the source of truth. Delete `loam` and every artifact remains as Markdown, LikeC4 DSL,
+Gherkin and YAML — no server, no database, no state file, three runtime dependencies. The two flows
+this implies, what gates and what only advises, are in [WORKFLOW.md](WORKFLOW.md).
 
 ## Install
 
-**Node ≥ 22.22.3** (the `engines` floor in `package.json`) is the only prerequisite for everything loam derives from the docs repo. C4 modeling uses **[LikeC4](https://likec4.dev)** (pinned exact), an ordinary npm runtime dependency loaded in-process (TypeScript-native): no JVM, no external CLI. The one outside binary loam ever calls is **`git`**, and only inside a service repo — `verify --service` binds each attestation to that repo's HEAD and refuses (`repository-unavailable`) without one, while `vouch`'s source digest asks `git check-ignore` and treats an absent git as "nothing is ignored" rather than failing.
+**Node ≥ 22.22.3** (the `engines` floor in `package.json`) is the only prerequisite for everything
+loam derives from the docs repo. C4 modeling uses **[LikeC4](https://likec4.dev)** (pinned exact),
+an ordinary npm runtime dependency loaded in-process (TypeScript-native): no JVM, no external CLI.
+The one outside binary loam ever calls is **`git`** — read-only questions in whichever repository
+the command is about (`verify --service`, `vouch`'s source digest, `subsystem move`/`history`, and
+`diff --base`), plus the one blessed `git add` that stages a subsystem move's renames. Never the
+network.
 
 ```bash
 npm install -g @ybotok/loam
 loam --version
 ```
 
-`loam doctor` is the wiring check, not the install check: run where no `loam.json` is in scope, it reports `doctor.config-missing` and exits 1 by design. Save it for after `loam init`.
+`loam doctor` is the wiring check, not the install check: run where no `loam.json` is in scope, it
+reports `doctor.config-missing` and exits 1 by design. Save it for after `loam init`.
 
 A per-repo dev dependency works the same way: `npm i -D @ybotok/loam`, then `npx loam …`.
 
-Until the package is published ([Status](#status)), install from a clone:
+To work on loam itself — or to run an unreleased commit — install from a clone:
 
 ```bash
 git clone https://github.com/ybotok/loam.git && cd loam
@@ -46,170 +177,526 @@ Drop `--link` to build without a global `loam`; on Windows run `npm ci && npm ru
 
 ## Quick start
 
-The repo ships a small example fleet under [`examples/docs/`](examples/docs) — two services, one feature in flight. From a clone, point a throwaway `loam.json` at it and run the real commands (the file is untracked; delete it when done):
+For the shortest install-to-first-feature path, including the exact chat commands and local problem
+report flow, use [QUICKSTART.md](QUICKSTART.md). The routes below explain the alternative starting
+positions in more depth.
 
-```bash
-echo '{ "docsDir": "examples/docs" }' > loam.json   # relative, resolved against this file
-npm run dev -- list                          # what the fleet looks like
-npm run dev -- validate --all                # the CI gate: 0 errors, 3 deliberate warnings
-npm run dev -- archive FEAT-101 --dry-run    # the whole three-axis merge plan, writing nothing
-```
-
-`test/examples.test.ts` pins the validate summary and every finding code, and the archive plan file-for-file, so those outcomes cannot drift from the code; the `list` rendering is not pinned.
-
-To wire loam into your own repositories, start at [Day zero](#day-zero-onboarding-a-fleet).
+`loam --help` ends by naming where to start and the way out, and this section is the same two
+commands in the same order: **`loam init --create`** first — every other command needs the docs repo
+it writes — and **`loam doctor`** whenever a later run does not do what you expected, which reports
+the runtime, the resolved `docsDir`, the access, the binding, and any finding with its `fix:` line.
+Each path below is that first command aimed at a different starting position; `loam diff` is the one
+that needs neither.
 
-## loam vs OpenSpec
-
-loam reads the core of [OpenSpec](https://github.com/Fission-AI/OpenSpec)'s requirement format: requirement/scenario headings and the `ADDED | MODIFIED | REMOVED` delta sections. Routine CI exercises seven representative upstream fixtures; a scheduled/manual sweep reproduces the broader compatibility result — counts *and* parse/serialize/parse stability of every requirement's content — against the full living, active and archived spec trees at the pinned OpenSpec v1.7.0 commit: **207 Markdown files, 739 requirements, 2273 scenarios** (the post-release main canary the same sweep pins is 209 / 742 / 2284). The boundary is explicit: OpenSpec `Purpose`, wrapper, and `RENAMED` semantics are not round-trippable — a `RENAMED` section is a loud `delta.unknown-section` error, not a silent drop, and `migrate-openspec` maps it rather than losing it.
-
-| | OpenSpec | loam |
-|---|---|---|
-| System model | capability specs; beta Stores share planning across repos (Git-owned planning roots, read-only references), but model no service topology | C4 landscape + one ID spine across spec / arch / API |
-| Executability | `/opsx:verify` asks an agent to inspect implementation and tests; advisory | digest-stamped Gherkin; a green cucumber run confirms a scenario mechanically, and a scenario confirmed on an agent's word instead is recorded as **attested, not verified** (`verify.scenario-attested`) |
-| Drift control | structural CLI validation plus agent-led verification on demand; no persisted digests to compare against later | persisted source/content digests + human vouch. `content.stale` is checkable fleet-wide; `sources.stale` only inside each service's own repo. Both are warnings — `--strict` is the CI escalation |
-| Change merge | validates prepared requirement updates, supports `RENAMED`, then writes specs sequentially | transactional 3-axis merge behind a coherence gate, digest-checked byte-level undo, and a commit journal that repairs an interrupted merge |
-| Agent surface | skills + commands for 34 tools at v1.7.0; `openspec update` regenerates them in place, skipping ones already current | skills for 20 tools and commands for the 19 that read them (Codex takes skills only); `--json` on every command; generated files carry a version stamp and are **never** regenerated — drift is reported (`doctor.agent-files-stale`) and repaired by hand |
-| Entry curve | minutes | you learn LikeC4 + frontmatter + the operationId spine first |
+### Start from the fleet spine
 
-Honest boundary: for a single repo without cross-service contracts, OpenSpec is simpler *and sufficient*. The full comparison — including what loam deliberately refuses to borrow — is in [COMPARISON.md](COMPARISON.md); migration is covered by [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md).
+The path that pays off first, because it is the only one whose checks have two sides to compare.
+It needs **no requirement Markdown, no `loam adopt`, and no `loam vouch`** — just the map and the
+contracts you already have.
 
-## Day zero: onboarding a fleet
+Write a `fleet.yaml` naming your services and who calls whom
+([`examples/fleet.yaml`](https://github.com/ybotok/loam/blob/main/examples/fleet.yaml) is a real
+one), then:
 
-A fleet of ten services is **eleven repositories**: one docs repo and ten service repos, each with its own committed `loam.json`. There is no batch command and no fleet manifest, deliberately — the wiring is one file per repo, and it is reviewable. In order:
-
-1. **Create the docs repo.** In an empty directory that will be the shared source of truth:
+```bash
+loam init --docs . --create        # in an empty directory: the docs repo
+loam seed --from fleet.yaml        # the fleet map + one services/<id>/ per service
+```
 
-   ```bash
-   loam init --docs . --create
-   ```
+Now do the two things only you can do:
 
-   That scaffolds `services/`, `features/`, `architecture/landscape.likec4`, `AGENTS.md`, and the docs repo's own `loam.json` (`docsDir: "."`, plus the `agentTools` it wrote for) — so every later command run *inside* the docs repo finds the fleet. An empty directory holds no tool dot-directory to detect, so the Claude Code fallback always fires here too: six slash commands and six Agent Skills under `.claude/` ([Working with AI agents](#working-with-ai-agents)). Commit all of it.
+1. **Drop each service's existing `openapi.yaml`** into `services/<id>/`. Copy the one your build
+   already produces — loam never generates it and never reads your code.
+2. **Name the operation on each call edge** in `architecture/landscape.likec4`:
+   `metadata { op 'createOrder' }`. This is the labour, and it is also the artifact nothing else
+   produces — a drawn arrow becomes a checked join.
 
-2. **Draw what you already know** in `architecture/landscape.likec4`. It can start almost empty; it is a **required** artifact, not an optional one — `loam validate --all` reports `landscape.missing` as an error the moment `services/` holds a directory (an empty one counts, before a single document lands in it), because with no fleet map every cross-service check is blind rather than passing.
+```bash
+loam validate --all
+```
 
-3. **Bind each service repo.** Once per service, in that service's own checkout, beside the docs repo:
+That already convicts the fleet's real edges: a call naming an operation its provider does not
+define is `spine.op-undefined`, an **error**, and one letter is enough — `authorisePayment` against
+a contract spelling it `authorizePayment` fails here and nowhere else a team normally runs.
+
+**Expect a red run, and read it correctly.** Five seeded services with no C4 centre report
+`service.no-model` (error) five times, and `service.no-spec` (warn) five times. Those are not
+misconfiguration: they are a truthful reading of a fleet where adoption has not started, and they
+stay until you write those documents. The finding you came for is the spine one. Under the `--base`
+PR gate [below](#guard-the-fleets-edges-on-every-pr), a PR that adds a service's `openapi.yaml`
+stays red until that service has a `model.likec4` — the gate grades the service the PR touched, and
+`service.no-model` is that ratchet working as designed — while a PR that only names operations on
+the map is graded on those edges alone.
+[`test/spine-first.test.ts`](https://github.com/ybotok/loam/blob/main/test/spine-first.test.ts)
+pins this whole sequence against the shipped `examples/fleet.yaml`, so the recipe cannot drift from
+the binary.
+
+From here, [WORKFLOW.md's day zero](WORKFLOW.md#day-zero-onboarding-a-fleet) is the rest: bind each
+service repo, adopt, grade, promote. Bind each one with the service profile:
 
-   ```bash
-   loam init --docs ../docs-repo --service payment-service   # no --create: it JOINS
-   loam doctor                                               # confirms the wiring
-   ```
+```bash
+# in each service checkout, beside the docs repo
+loam init --docs ../docs --service payment-service --agent-profile service
+loam doctor
+```
 
-   `--service` is the binding: without it `loam vouch` and `loam gherkin` refuse outright, and `loam verify --service --record` / `--results` refuse to attest, because none of them will write a service's documents from a repo that has not said which service it is. Reading — `loam verify --service` on its own — needs no binding, because it writes nothing. Commit the `loam.json`.
+Pass the profile explicitly. `--agent-profile` defaults to `full`, with `--service` or without it,
+and `full` writes all seven entry points into the checkout — `loam-feature` and `loam-ship` among
+them, the two workflows that author a feature and archive it into the living docs, which the `docs`
+profile gives to the docs repo. `service` writes the five that run beside the code: `loam-adopt`,
+`loam-implement`, `loam-check`, `loam-verify` and `loam-report`. Across a hundred service repos that
+is the difference between one place a cross-service change starts and a hundred places an agent
+can be told to start one. The people in those service repos need about a screen of this:
+[docs/SERVICE-TEAMS.md](https://github.com/ybotok/loam/blob/main/docs/SERVICE-TEAMS.md).
+
+### Guard the fleet's edges on every PR
+
+Two commands, each installable on its own with no part of the workflow above adopted. **`loam diff`
+exits 1 when a pull request removes an operation or an event message the fleet still consumes**,
+and names the consumers — of a removal, a deprecation, or a change to what an operation or message
+returns. That question — *who is joined to this?* — is the one a fleet answers wrong, and it is
+answerable only from a document that knows the whole fleet. **`loam validate --all --base <ref>`
+grades only the boundaries the branch touched**, which is what lets a strict gate go in on the
+first day of adoption and tighten as the system gets written down.
+
+```yaml
+# .github/workflows/fleet-edges.yml — in the docs repo
+name: fleet edges
+on: pull_request
+jobs:
+  edges:
+    runs-on: ubuntu-latest
+    env:
+      LOAM: "@ybotok/loam@0.2.0-alpha.13"   # an exact version: bump it in a PR of its own
+      BASE: origin/${{ github.base_ref }}
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }          # every step reads the base out of git history
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      # did you remove something an authored consumer still names? (fails) — and
+      # who is joined to each operation or message you changed? (warns, naming them)
+      - run: npx -y "$LOAM" diff --base "$BASE"
+      # did you document what you touched?
+      - run: npx -y "$LOAM" validate --all --base "$BASE" --strict
+      # does a changed operation break its readers? oasdiff answers that; loam does not
+      - run: |
+          for spec in $(git diff --name-only --diff-filter=M "$BASE"... -- 'services/*openapi.yaml'); do
+            git show "$BASE:./$spec" > "$RUNNER_TEMP/base.yaml"
+            docker run --rm -v "$RUNNER_TEMP:/base:ro" -v "$PWD:/head:ro" tufin/oasdiff \
+              breaking /base/base.yaml "/head/$spec" --fail-on ERR
+          done
+```
 
-4. **Adopt each service.** In its repo: `loam adopt --service <id> --json` emits the brief — every file to write, the grammar of each, what the fleet map already says, and the block the map still owes this service. An agent reads the code and writes the baseline as `draft`. `warnings[]` catches the typo case, where an id one letter off would have produced a complete, validating baseline for a service that does not exist.
+**Pin loam, and move the pin on purpose.** An unpinned `npx -y @ybotok/loam` runs whatever the
+`latest` tag points at on the day the job starts, so a release can change what gates your pull
+requests in the middle of a review. Bump `LOAM` in a pull request of its own: run
+`loam subsystem sync` with the new version, update the `<!-- generated by loam vX.Y.Z -->` stamp
+in the docs repo's `AGENTS.md`, and read the release's CHANGELOG entry, which opens with what a
+repository notices after upgrading. Pin the oasdiff image's tag the same way.
+
+Three steps, three different questions, and none is another's cheaper form. `diff` reports every
+removal against the fleet's authored consumers — landscape edges, other services' living
+requirements, use-case hops — rather than against a rule list, which is why it repays installation
+before anything else exists. It names who is joined to a changed operation or message, and it never
+says whether the change breaks them: loam does not read what a schema says, so a renamed required
+field and a new optional one are the same warning to it. That half is oasdiff's, and
+`asyncapi diff`'s for event contracts. A caller drawn on the map with no operation on its edge is
+listed as one nobody could check, never counted as no caller. `validate --base` grades the
+boundaries this branch changed, at full strictness, and says out loud how much of the system that
+was — a run with nothing in scope prints that it graded nothing rather than the word valid.
+Unscoped, neither setting is usable on a partly-documented system: `loam validate --all` is green
+over boundaries nobody has written yet, because warnings do not gate, and `--strict` over all of
+them is red from the first minute of adoption until the last one is done.
+
+An archive's PR stays red under `--base --strict` until its re-vouches land: the merge moves every
+vouched spec it touches under its vouch stamp, so `content.stale` follows, and `loam archive` names
+each such spec and its owner (`revouchOwed`) so those re-vouches can join the same PR.
+
+**A `--base`-scoped validate cannot see a victim boundary the change did not touch.** Remove an
+operation `payment-service` owns, and `checkout-web` — whose living requirement still names it —
+is not in scope, so nothing in that gate reports the broken join. That is `loam diff --base`'s
+question, it stays `loam diff --base`'s, and a green scoped validate is not a statement about the
+consumers of what changed. A join the branch itself *wrote* is the other case: a call edge it adds
+or edits in `architecture/` is graded against its provider's contract even with the provider out of
+scope, so the one-letter `authorisePayment` above fails on the PR that introduces it.
+[WORKFLOW.md](WORKFLOW.md#what-actually-gates) has what each does and
+does not grade — including the oasdiff invocation for the byte-level OpenAPI breaking-change
+catalogue, which loam deliberately does not reimplement.
+
+### Check each service repo on its own pull requests
+
+The docs repo's job cannot see provenance. `sources` resolve only inside a service's own
+repository, so `sources.stale` — the code under a vouched spec moved — surfaces only in that
+service repo's CI ([SCHEMA.md](SCHEMA.md), "Operating at fleet scale"). Its committed `loam.json`
+reaches the docs repo through a relative `docsDir` such as `"../docs"`, so the job rebuilds the
+side-by-side layout a laptop has. `actions/checkout` refuses `path: ../docs` — it writes only
+beneath `GITHUB_WORKSPACE` — so check out **both** repositories as subdirectories of the workspace,
+siblings, and run loam from the service's:
+
+```yaml
+# .github/workflows/loam.yml — in each service repo
+name: loam
+on: pull_request
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      LOAM: "@ybotok/loam@0.2.0-alpha.13"   # the docs repo's pin: move them together
+      SERVICE: payment-service              # this repo's "service" in its loam.json
+    steps:
+      # Both repositories as siblings under the workspace, the way a laptop holds
+      # them, so the committed "docsDir": "../docs" resolves unchanged.
+      - uses: actions/checkout@v4
+        with: { path: payment-service }
+      - uses: actions/checkout@v4
+        with:
+          repository: acme/docs                       # your docs repo
+          path: docs                                  # the last segment of docsDir
+          token: ${{ secrets.LOAM_DOCS_READ_TOKEN }}  # contents: read on the docs repo
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: loam validate --service
+        working-directory: payment-service
+        run: |
+          rc=0
+          npx -y "$LOAM" validate --service "$SERVICE" --json > "$RUNNER_TEMP/loam.json" || rc=$?
+          # one annotation per error and warning; a refusal (docs-missing, …) is one error
+          jq -r '
+            def esc: gsub("%"; "%25") | gsub("\r"; "%0D") | gsub("\n"; "%0A");
+            if .ok then
+              .targets[].findings[] | select(.severity != "ok")
+              | "::\(if .severity == "error" then "error" else "warning" end) title=\(.code)::\(.message | esc) (docs: \(.locations[0].path))"
+            else "::error title=\(.error.code)::\(.error.message | esc)" end
+          ' "$RUNNER_TEMP/loam.json"
+          # the same findings as a table on the run's summary page
+          jq -r '
+            if .ok then
+              "### loam validate --service \(.targets[0].id) — \(.summary.errors) error(s), \(.summary.warnings) warning(s)",
+              "", "| severity | code | finding |", "|---|---|---|",
+              (.targets[].findings[] | select(.severity != "ok")
+                | "| \(.severity) | `\(.code)` | \(.message | gsub("\\|"; "\\|") | gsub("\n"; " ")) |")
+            else "### loam refused: `\(.error.code)`", "", .error.message end
+          ' "$RUNNER_TEMP/loam.json" >> "$GITHUB_STEP_SUMMARY"
+          exit "$rc"
+```
 
-5. **Grade it, twice.** `loam validate --service <id> --json` in the service repo (its own axes plus `sources`, which only that repo can resolve), then `loam validate --all --json` in the docs repo — the fleet cross-check that catches a landscape edit which never landed.
+Run from a `payment-service` checkout beside `examples/docs`, in a repository with no
+`src/main/java/` — the source that service's specs name — the step exits 1 and prints:
 
-6. **Promote it.** A human runs `loam vouch --service <id>` in the service repo: `draft → verified`, stamping the source and content digests that make later staleness detectable. `loam list --json` in the docs repo then grades the whole fleet on the presence ladder `empty → partial → documented → sourced → vouched`, and `loam list --needs-work` is the remaining worklist.
+```text
+::warning title=spine.op-link-missing::payment-service: landscape edge checkout-web → payment-service ("Calls the payment API") has no operation link (metadata { op }) (docs: services/payment-service)
+::error title=sources.path-missing::payment-service: spec.md: 1 source(s) do not exist — src/main/java/ (docs: services/payment-service)
+::error title=sources.path-missing::payment-service: arch.spec.md: 1 source(s) do not exist — src/main/java/ (docs: services/payment-service)
+```
 
-Steps 3–6 repeat per service and are independent — no ordering, no lock, no shared state between two services' runs — so ten services can be onboarded by ten people in parallel. The one file they all touch is the landscape: step 2 draws it, step 4's brief tells each of them to *add* their own element to it where the map does not yet know the service, and step 5's `--all` reads it.
+The annotations carry no `file=`, on purpose: every location loam reports is a path in the docs
+repo, which is not the repository this pull request diffs, so GitHub could not place one on a line
+here. They land on the check run and its summary instead. A docs repo that is private needs a token
+that can read it — a fine-grained token or a GitHub App token with `contents: read` on that one
+repository — because the workflow's own `GITHUB_TOKEN` reads only the repository it runs in. Add
+`--strict` once the service is vouched and its warnings are ones you mean to keep at zero; before
+that, the warnings are the adoption still to do.
 
-## Two flows
+The same layout answers the deploy question. In the deploy pipeline, check the docs repo out with
+`fetch-depth: 0` — `--since` is read from its git history — and ask whether this service may ship:
 
+```bash
+npx -y "$LOAM" gate --service "$SERVICE" --since "$DOCS_SHA_OF_LAST_DEPLOY"
 ```
-BOOTSTRAP (once per service, reverse):
-    code ──adopt──►  brief ──agent──►  C4 baseline + capability spec   [truth = code]
 
-FORWARD (per feature, generative):
-    intent → C4 delta → Gherkin (BDD) → tests → code      [truth = model]
-                 ▲                                   │
-                 └──── done-check: verify ◄──────────┘
-                        (a checklist of the feature's own promises,
-                         answered against the code, with evidence)
+`gate` executes nothing and writes nothing, and without `--strict` its warnings stay advisory;
+[WORKFLOW.md](WORKFLOW.md#what-actually-gates) says what each finding of it means for a pipeline.
+
+**Cloud agents in a service repo** need the same sibling on disk before they start: a lone clone
+of the service answers every docs-reading command with `docs-missing`. GitHub's Copilot coding
+agent and Codex cloud each start from the one repository the task names and run a setup step you
+own, so clone the docs repo there, into the committed `docsDir`. Copilot reads the job
+`copilot-setup-steps` from `.github/workflows/copilot-setup-steps.yml` on the default branch, and
+an
+[Agents secret](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/configure-secrets-and-variables)
+reaches those steps as an environment variable:
+
+```yaml
+# .github/workflows/copilot-setup-steps.yml — in each service repo
+name: Copilot setup steps
+on: workflow_dispatch
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions: { contents: read }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm install -g @ybotok/loam@0.2.0-alpha.13
+      # "../docs" is outside the workspace, so git clone rather than actions/checkout;
+      # the second command takes the token back out of the clone's config
+      - run: |
+          git clone --depth 1 "https://x-access-token:${LOAM_DOCS_READ_TOKEN}@github.com/acme/docs.git" ../docs
+          git -C ../docs remote set-url origin https://github.com/acme/docs.git
+      - run: loam doctor
 ```
 
-**There is no extractor, and there will not be one.** Nothing deterministic reads a legacy service and says what its architecture *means*, and a model that was guessed is worse than none — everyone downstream has to re-derive it to know whether to believe it. So loam takes the half of the job that is mechanical: it **states the work** and it **checks the result**. An agent does the reading.
-
-The same split runs the done-check. `verify` cannot compare a generated model to the delta (two generated models of the same code disagree every run, so the diff would flap and get switched off), but it *can* derive the question set deterministically: every service the delta introduces, every operation the feature adds, every operation-linked call it draws, every scenario it wrote. The agent answers with a `file:line` — required to be non-empty in the docs-repo all-at-once form, and under `--service` resolved inside the service repo and pinned to its commit — and every answer is recorded next to the feature, marked with who gave it (`answered_by: runner` or `answered_by: agent`).
+Codex cloud has no workflow file: the same commands go in the environment's setup script, with
+the token as an environment **secret** — Codex hands secrets to the setup script only and removes
+them before the agent phase, which is all a clone needs. Pin Node.js to 22 or newer in the
+environment's package versions, and spell the target from the repository root, because where the
+script starts is not documented:
 
-**The scenario claims are where that mark carries weight.** The generated suite's digest tags ride into the cucumber JSON report, so `verify --results` answers a `scenario.tested` claim mechanically: only a green, digest-matched run confirms one, and names never match anything. But a legacy service with no runnable suite yet must still be able to record its answers, so `--record` may confirm a scenario claim too — on somebody's word. loam does not pretend those are the same thing. A record holding any of them never reads back as `verified`: complete, it reads **`verdict: "attested"`**; short of complete — an unanswered claim anywhere, or the feature moved under the answers — `unverified`. `verify` prints `verify.scenario-attested` naming each claim, `loam status` re-reports it and offers `next.verify-attested`, and the record travels into `features/archive/` saying so. `verified: true` in the JSON envelope means every scenario claim came from a test run. None of it gates anything: the notice is a warning, and `archive` does not read the record at all.
-
-## Principles
-
-- **Files are the source of truth**; the CLI is a derived convenience. Delete `loam` and every artifact remains as Markdown / LikeC4 DSL / Gherkin / YAML. No binary, no database, no state file.
-- **Thin, not a platform.** One shared docs repo + a CLI. No server, no DB, no Backstage.
-- **Mechanical vs semantic.** Deterministic checks validate *shape* (valid DSL, resolvable IDs, coverage); an LLM writes *narrative* (the docs, the Gherkin behavior).
-- **loam never guesses about code.** It reads the docs repo; inside a service repo it only ever hashes or locates what a document already named — the files a `sources` list covers, the `file:line` an answer cites, the cucumber report `--results` was handed. It never parses code or derives meaning from it. Where a judgement about a codebase is needed — what this service is, whether that scenario has a test — loam states the **question**, precisely and repeatably, and an agent answers it. Both halves are written down: the question in the brief or the checklist, the answer in `sources` or `verification.yaml`.
-
-## Commands
+```bash
+npm install -g @ybotok/loam@0.2.0-alpha.13
+DOCS="$(git rev-parse --show-toplevel)/../docs"
+git clone --depth 1 "https://x-access-token:${LOAM_DOCS_READ_TOKEN}@github.com/acme/docs.git" "$DOCS"
+git -C "$DOCS" remote set-url origin https://github.com/acme/docs.git
+loam doctor
+```
 
-| Command | What it does |
-|---|---|
-| `loam init --docs <dir> [--service <id>]` | Bind this repository to the single shared docs repo: write a committed local `loam.json` and, for every AI tool it detects here (Claude Code when it finds none), a command file and an Agent Skill per workflow. `--create` scaffolds the docs repo itself instead — `services/`, `features/`, `architecture/landscape.likec4` and its `AGENTS.md`. |
-| `loam list [services\|features]` | What is in the docs repo, and what is missing from it. |
-| `loam status [<FEAT>]` | Where the work stands and what to do next, as a projection over the two gates. Derived every run; writes nothing. |
-| `loam doctor` | Read-only preflight for runtime, config, docs-repo access, fleet roots, counts, and the current service binding. Blockers exit 1; incomplete optional bindings stay warnings. |
-| `loam dependencies [<FEAT>]` | Derive the active-feature dependency graph and same-identity conflicts from requirement deltas and OpenAPI operationIds. Optional focus includes transitive prerequisites. |
-| `loam explore [<service>...]` | Read the fleet around a change nobody has written down yet: the ring one hop out, each service's maturity and living operations, the features already in flight over the same ground, and the `loam new` line the seeds imply. `--op <id>` seeds from an operation. Writes nothing. |
-| `loam instructions [<workflow>] [args...]` | Print one of the six workflow protocols, `$1`/`$2` filled in — version-matched to this binary, which is what the generated command and skill files point at. Reads no config. |
-| `loam new <FEAT> [--title <t>] [--touches <id>] [--new-service <id>]` | Scaffold a feature: intent, C4 delta, and a requirement delta for every service named by `--touches` / `--new-service` (both repeatable). The title is optional and becomes the directory slug. |
-| `loam show <service\|FEAT>` | Everything loam knows about one service or feature. |
-| `loam adopt --service <id>` | Brief an agent to write this service's baseline into the docs repo as `draft`. Writes nothing. |
-| `loam delta <FEAT> [--service <id>]` | Project a feature onto one service: the intent, its requirement deltas with every requirement body and every Given/When/Then line reproduced verbatim, the endpoints it adds or retires, and the edges around it. The output doubles as a coding-agent task. |
-| `loam gherkin [<FEAT>] [--service <id>]` | Emit spec scenarios as digest-stamped Gherkin `.feature` files into the service repo's `<gherkinDir>/loam/`. |
-| `loam rebase <FEAT> [--service <id>]` | Pin the feature to the living versions it was written against, on the requirement axis and the contract axis. `--dry-run` shows what would be pinned. |
-| `loam validate [<id>] [--service <id>\|--feature <id>] [--all]` | Validate one service or feature, or the whole fleet in one run (the docs repo's CI gate). The positional id resolves a feature first; `--service` / `--feature` force the reading. `--strict` exits 1 on warnings too. |
-| `loam verify <FEAT> [--service <id>]` | The done-check: derive a checklist of the feature's own promises, and record the answers with their evidence. |
-| `loam vouch --service <id>` | The human promotion `draft` → `verified`: stamp a living spec against the code it was written from. Run in the service's own repo. |
-| `loam archive <FEAT>` | Merge a shipped feature into the living specs, API and landscape; gated on gating coherence issues, on what only the computed merge can see, and on living documents the merge cannot rewrite safely. `--approve` overrides the judgement calls, never the mechanical losses. `--dry-run` prints the plan and writes nothing. |
-| `loam unarchive <FEAT>` | Take that back: restore the living docs from the snapshot archive left behind, and re-open the feature. |
-| `loam audit-openspec <root>` | Read-only inventory of an OpenSpec checkout/workspace/Store checkout. Writes nothing; `--write-mapping <path>` emits the decision skeleton you fill in. |
-| `loam migrate-openspec <root> --map <path>` | Validate a completed mapping against a re-read of the source, and materialize staged migration docs. Dry-run is the default. |
+The clone is the agent's reading, not a second place it can deliver. A cloud agent opens its pull
+request against the repository it was started in, so anything it writes into the docs checkout —
+a verification record, a spec edit — stays in its sandbox. `loam-implement`'s own outputs, the
+generated Gherkin and the code, land in the service repo as usual; what belongs in the docs repo
+goes there through that repo's own pull request.
 
-Every command takes `--json`: findings carry stable codes (`c4.valid`, `spine.op-undefined`, `coherence.ok` …) so an agent branches on the code, not on prose. The envelope keeps three different questions apart, each on the command that can answer it — `ok` (the command ran) on every envelope, `valid` (the docs pass) on `validate`, and `verified` (every claim is confirmed **and** every scenario claim came from a test run) on `verify`, beside `verdict`, which carries the third state, `attested`, for a record whose scenarios rest on an agent's word.
+### Try loam on one governed system in five minutes
 
-### Command notes
+The full model may be one application or a fleet; the trial is one repository. In the codebase you
+know best (after [installing](#install)):
 
-**`loam init`** — `--docs` **joins** an existing docs repo; `--create` is required to make a new one, so a mistyped path cannot scaffold a second source of truth. `--service <id>` is what a **service** repo needs: it is the binding `vouch`, `gherkin` and `verify --service --record`/`--results` require before they will write for that service. `--tools <ids>|all` overrides the tool scan; `--no-commands` / `--no-skills` drop one delivery — and the two are exclusive, refused together, since one names the files to write and the other suppresses them. `docsDir` is stored exactly as you typed it and resolved against `loam.json`, so a relative `../docs-repo` works on every clone — and `--docs` wins only when you actually pass it, so a re-run in a wired repo keeps the pointer its committed `loam.json` already spells, `--create` included (`docsDirSource: "flag" | "config" | "default"` in `--json` says which).
+```bash
+loam init --docs loam-docs --create --service commerce-app
+```
 
-**`loam status`** — the question an agent has when it joins a repo halfway or loses its session. Artifacts come back `missing`/`blocked`/`draft`/`ready`/`done`, and `next[]` is ordered, each entry a stable code plus the literal command. It takes the union of what `validate --feature` errors on and what `archive` refuses to merge, so it may be redder than either and is never greener than both. There is no state file to go stale.
+One run does two things: it scaffolds a new docs repo at `loam-docs/` — `services/`, `features/`,
+`architecture/landscape.likec4`, its own `AGENTS.md` and `loam.json` — and it binds this repository
+to the id `commerce-app` in a committed `loam.json` beside your code (plus the slash commands and
+Agent Skills for the AI tools it detects here — [Working with AI agents](#working-with-ai-agents)).
+`init` ends by printing the first hour, which is this loop:
 
-**`loam new`** — the scaffold passes `loam validate --feature` with **zero errors**; the warning left standing is the `owner` you have to fill in yourself, and a feature that introduces a service starts on a second, `c4.uncovered`, until its `arch.spec.md` delta carries a `Covers:` line for the element the delta adds. For a requirements-only feature you delete the scaffolded `delta.likec4` yourself — `new` says so on the way out, and the feature validates clean without it.
+```bash
+loam adopt --service commerce-app --json   # the brief: an agent reads the code, writes the baseline as draft
+loam validate --service commerce-app       # grade the result in this repo
+loam vouch --service commerce-app          # you, not the agent: draft -> verified
+loam status                                   # what to do next, derived from the files
+```
 
-**`loam adopt`** — the brief names the target paths, the grammar of each, what the landscape already says, the checks that follow, and the ones that do not exist.
+What the trial pays off on is the adopt → validate → vouch mechanics: the brief, the graded
+baseline, the human promotion that makes later staleness detectable. In a modular monolith,
+`arch.spec.md` and `Covers:` can already govern the nested model inside this one boundary. The
+cross-boundary contract spine needs a second service — one boundary has no remote edge to join.
+When a second service wants in, graduate to the full wiring:
+[WORKFLOW.md's day zero](WORKFLOW.md#day-zero-onboarding-a-fleet) is the same steps, pluralized.
 
-**`loam gherkin`** — a feature's changed requirements, or (without a feature) the full living suite. Deterministic, digest-stamped, regeneration-owned; run in the service's own repo.
+### Explore the example fleet
 
-**`loam rebase`** — writes `Based-On:` on every MODIFIED/REMOVED requirement and `x-loam-based-on` on every operation in the contract delta that the living docs already hold; what this feature is *adding* has nothing to pin against, and the output says so per item. On the requirement axis that stops a second feature rewriting the same requirement from landing on top of the first in silence; on the contract axis it also marks the rest of the delta as **quotation** — an `openapi.yaml` is a complete document, so without the pin the merge upserts operations you only restated and reverts whatever landed on them. Restamping is the last step of resolving a collision, not the resolution — the output says which pins moved.
+Installed from npm rather than cloned? The example fleet ships inside the package, and one command
+copies it out — through the same journaled write path every other loam writer uses, byte for byte.
+It binds no repository, records no `docsDir`, and writes nothing outside the directory you name:
 
-**`loam verify`** — `--results <report.json>` answers the scenario claims from a cucumber JSON run, digest-matched, so only a green run confirms one, and the record writes down which file it read (path, sha256, mtime). It answers *only* those claims, so on a feature with open `service.exists` / `api.exposes` claims it is passed alongside `--record` or refused (`answers-mismatch`). `--record <answers.json>` takes the agent's answers, refusing anything unevidenced — under `--service`, refusing a `file:line` that does not resolve in that repo at the attested commit — and a scenario claim answered that way makes the record `attested` rather than `verified`. A cross-service feature is recorded **once per service repo** with `--service <id>`, each run adding its own commit-bound attestation to one shared record; the `--service`-less `--record` form writes the whole record from one place and is refused (`record-federated`) once anyone else has attested.
+```bash
+loam init --example ./loam-demo
+cd loam-demo && loam validate --all     # 0 errors, 10 deliberate warnings
+```
 
-**`loam unarchive`** — it refuses rather than guesses: `snapshot-stale` when a merged file moved since (`--force` says that was meant), and `snapshot-corrupt` when a pre-image no longer hashes to what the archive recorded for it, which `--force` deliberately does **not** override — the damage there is to the undo itself.
+That tree is the one the repo ships under
+[`examples/docs/`](https://github.com/ybotok/loam/tree/main/examples/docs) — five services, two
+features already shipped, two in flight, the event spine, the permission vocabulary, the business
+tree, and two verification records that read `attested` and `verified` so the difference between
+them can be seen standing.
+[`examples/README.md`](https://github.com/ybotok/loam/blob/main/examples/README.md) is the guided
+tour: what each service is there to show, and what every one of the ten deliberate warnings
+demonstrates. From a clone, step into the fleet where it sits and run the real commands — it carries
+its own committed `loam.json`, so there is nothing to write first and nothing to delete afterwards
+(working from source instead of an installed binary, substitute `npx tsx ../../src/cli.ts` for
+`loam`):
 
-**`loam audit-openspec` / `loam migrate-openspec`** — the audit reports capabilities, active and archived changes, counts, RENAMED and unsupported shapes, and every capability→service decision still needing a human. The migration validates your completed mapping against a re-read of the source, and with `--apply --target <empty-dir>` materializes **staged migration docs** into a separate directory. `--map` is required — there is no one-shot form.
+```bash
+cd examples/docs                    # the tree governs itself: its loam.json says "docsDir": "."
+loam list                           # the fleet and its maturity ladder
+loam status                         # what to do next, derived from the files
+loam validate --all                 # the CI gate: 0 errors, 10 deliberate warnings
+loam archive FEAT-101 --dry-run     # the whole three-axis merge plan, writing nothing
+loam archive FEAT-112 --dry-run     # an operation being retired, writing nothing
+loam verify FEAT-088                # an archived feature's done-check: attested
+loam verify FEAT-120                # its pair, same check: verified
+```
 
-### How `archive` protects the source of truth
+`test/examples.test.ts` pins the validate summary and every finding code, and both archive plans
+file-for-file, so those outcomes cannot drift from the code; the `list` rendering is not pinned.
 
-`archive` is the one command that rewrites the source of truth, so it takes an advisory lock on the docs repo for the whole plan-and-commit (a second writer — another `archive`, an `unarchive`, a `rebase` — refuses with `docs-busy` rather than interleaving), computes the whole merge before touching disk, commits each file through a temp file swapped in atomically after re-checking the bytes it read (a rename for an overwrite, a no-clobber `link(2)` for a create, so a file that appeared after the plan was computed is never buried), and rolls back what it already swapped if any part fails. It also records the bytes it overwrote inside the archived feature — with a digest of each pre-image, so `unarchive` can tell an intact one from an edited one — which is what makes `unarchive` an undo rather than a guess. A process **killed mid-commit** is covered too: an intent journal (`.loam-commit`) is fsynced before the first swap, and the next `archive`/`unarchive` recovers from it under the lock, rewriting each half-written file from the snapshot — an interrupted archive is undone, an interrupted unarchive is *finished*, because the merged text it was replacing is written down nowhere else — or refusing with `commit-interrupted` when a file has been edited since. `loam doctor` reports that state rather than calling the repo healthy.
+## Commands
 
-The gate itself comes in two kinds. Coherence, an unknown service and the OpenAPI plan are judgement calls, and `--approve` carries them; two refusals are mechanical loss and `--approve` deliberately does not — a living document still holding git conflict markers (`merge-failed`) and a living requirement that has strayed outside `## Requirements` (`living-outside-requirements`). loam's docs files must be **UTF-8** for the same reason: undecodable bytes refuse the merge (`merge-failed`, naming the file) instead of being rewritten as U+FFFD, and a non-UTF-8 `openapi.yaml` grades `openapi.invalid`. **`verify` does not gate `archive`** — coherence gates because loam *computed* it; a verdict is somebody's word about code loam never read, and a gate in front of shipping only teaches everyone that the cheapest way past it is to say yes.
+Every command takes `--json`; findings carry stable codes (`c4.valid`, `spine.op-undefined`,
+`coherence.ok` …) so an agent branches on the code, not on prose. Flags are listed in full below —
+`loam <command> --help` is the same list from the binary you are running, and
+[WORKFLOW.md's command notes](WORKFLOW.md#command-notes) is the per-command behavior that a table
+cannot hold.
 
-API retirement is explicit and reviewable: a feature marks the exact path/method operation with `x-loam-remove: true` — **inside the operation being retired, beside its `operationId`** — and removes the governing requirement in the same delta. A marker written one level up, at path level beside the methods, addresses no operation and retires nothing; archive refuses it (`openapi.remove-marker-path-level`) rather than publishing a meaningless key into the fleet's living contract. Validation refuses stale, mismatched, or unjustified markers; archive deletes the method without persisting the marker or garbage-collecting components, and reports the removals in both text and JSON. See [SCHEMA.md](SCHEMA.md) for the lifecycle contract.
+| Command | Flags | What it does |
+|---|---|---|
+| `loam init` | `--docs <dir>` `--service <id>` `--create` `--force` `--tools <ids>` `--agent-profile <full\|service\|docs>` `--example <dir>` `--no-commands` `--no-skills` `--mcp` `--mcp-author` | Bind this repository to the single shared docs repo: a committed local `loam.json`, plus command and Agent Skill pointers for detected AI tools. Profiles narrow the six lifecycle workflows to a repo's role; the support-only `loam-report` stays in every profile. Re-running init refreshes only unchanged loam-owned pointers; edited files are preserved. `--mcp` writes the read-only host entry, while `--mcp-author` opts into the bounded authoring tools. `--create` scaffolds the docs repo; `--example` copies the packaged example and stops |
+| `loam seed` | `--from <file>` | Template the fleet map and one `services/<id>/` directory per service from a tiny human-authored `fleet.yaml`. Mechanical, never a guess: a human stated every fact. Refuses once the landscape has been hand-edited |
+| `loam list [services\|features\|capabilities\|glossary\|suites]` | `--archived` `--needs-work` `--review-order` `--subsystem <name>` `--owners <path>` | What is in the docs repo, and what is missing from it. `capabilities` rolls up who realizes each promise; `glossary` rolls up each term with the documents that cite it; `suites` groups the use cases by `#suite-` tag and names the services each suite needs up (`loam list suites <name>` shows one) |
+| `loam status [<FEAT>]` | `--service <id>` | Where the work stands and what to do next, as a projection over the two gates. Each `next[]` row has an `execution` object that says whether it is runnable, where, and what input or edit is still needed. Derived every run; writes nothing |
+| `loam doctor` | — | Read-only preflight for runtime, config, docs-repo access, fleet roots, counts, and the current service binding. Blockers exit 1; incomplete optional bindings stay warnings |
+| `loam dependencies [<FEAT>]` | — | The active-feature dependency graph and same-identity conflicts, derived from requirement deltas and OpenAPI operationIds |
+| `loam diff` | `--base <ref>` | Semantic diff of the living docs against a base git ref of the docs repo — the review lens for a docs-repo PR, with the authored consumers of every removal, deprecation and contract change named. Exit 1 on a removal the fleet still consumes |
+| `loam explore [<service>...]` | `--op <operationId>` `--capability <id>` `--as <FEAT>` | Read the fleet around a change nobody has written down yet: the ring one hop out, each service's maturity and living operations, the features already in flight over the same ground, and the `loam new` line the seeds imply |
+| `loam context <service>` | `--feature <FEAT>` | Assemble one service's docs slice — living requirements verbatim, both contracts, the fleet edges around it, permissions, capabilities, provenance, and every active feature's delta over it — as one deterministic briefing |
+| `loam steps` | `--service <id>` `--duplicates` `--json` | Inventory the step phrases of one service's scenarios: how many distinct steps its suite is written in, how few definitions cover most of them, and which phrases differ only by an article or a trailing clause. Reads the living specs, writes nothing — the work-list a team writes its step definitions from, diffed against the optional `services/<svc>/steps.yaml` catalogue when one exists |
+| `loam instructions [<workflow>] [args...]` | `--no-fix-tables` | Print one of the six workflow protocols, the separate `loam-report` support protocol, or one of the five reference pages `loam-codes`, `loam-spine`, `loam-authoring`, `loam-done-check` and `loam-drawing`, version-matched to this binary. Workflow `$1`/`$2` placeholders are filled; support/reference pages take no arguments. Reads no config. `--no-fix-tables` collapses the per-code fix tables to a line each, keeping the paragraph that says which scope graded them: `loam-check`'s page, almost all of it fix tables, comes back in a few kilobytes, while a support/reference page holds no such table and comes back byte-identical |
+| `loam explain [<subject>]` | `--codes` | Explain a finding code, a refusal code, or a concept term. Most finding prose is parsed at runtime from the shipped fix tables, so it cannot drift from the binary; the `doctor.*`, `next.*`, `diff.*` and `gate.*` families, which no fix table grades, are answered from a registry written beside them. Every text-mode refusal prints `<code>  ·  loam explain <code>` on stderr and every non-`ok` finding line carries its code in parentheses, so the lookup is reachable without re-running under `--json`. The concept terms cover every word loam prints to a person — the stages (`ready`, `done`), the claim kinds, the `loam tasks` steps, the maturity ladder. Omit the subject to list the terms; `--codes` lists the whole vocabulary — every finding code and every refusal code it can answer, each row the same answer `explain <code> --json` gives for that one |
+| `loam open` | `--root <dir>` `--out <file>` `--force` | Write a `.code-workspace` joining the docs repo and every service checkout whose committed `loam.json` binds to it. Never overwrites without `--force` |
+| `loam mcp` | `--author` | Serve sixteen read tools, version-matched instruction resources and a declared envelope output schema over MCP. `--author` adds `new`, `rebase`, `gherkin` and an archive dry-run; it never exposes `vouch`, verification recording or a committing archive — [the MCP server](WORKFLOW.md#the-mcp-server) |
+| `loam new <FEAT>` | `--title <text>` `--touches <id>` `--new-service <id>` `--capability <id>` `--modifies <Req-ID>` | Scaffold a feature: intent, C4 delta, a requirement delta per service named by `--touches`/`--new-service`, and a capability delta per promise named by `--capability` (all repeatable). `--modifies` copies a touched service's living requirement into an uncommented `## MODIFIED Requirements` block with its `Based-On:` pin already set, so a small change is new → edit → archive; when every touched service is rewritten that way and nothing is introduced, no `delta.likec4` is written |
+| `loam show <service\|FEAT>` | `--type <kind>` | Everything loam knows about one service or feature. A feature's JSON includes a semantic `review` pack: intent, exact architecture objects, API/event slices, dependencies, artifacts, verification, blockers and next actions. `--type` forces an ambiguous reading |
+| `loam subsystem <verb> [names...]` | `--into <name>` `--under <name>` `--title <text>` `--description <text>` `--owner <name>` | Manage the grouping tree under `services/` — a navigable tree no identity depends on. `new`/`rm`, `move … --into`, `rename`, `list`, `history`, `sync` |
+| `loam adopt` | `--service <id>` `--subsystem <name>` `--targets` | Brief an agent to write this service's baseline into the docs repo as `draft`: the target paths, the grammar of each, what the landscape already says — and, for an element no edge touches, the edges the service's own model.likec4 attests — and the checks that follow. Writes nothing. `--targets` narrows it to what varies by service — the walk, the 52 checks and the seventeen statements of what nothing checks are the same bytes everywhere, so a `full` field names the one run that carries them. Both sizes, for the example fleet's payment-service, are in the payload table of [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md#what-an-agent-is-handed--payload-sizes), which a test regenerates from the tree |
+| `loam delta <FEAT>` | `--service <id>` | Project a feature onto one service: the intent, its requirement deltas with every body and Given/When/Then line verbatim, the endpoints it adds or retires, and the edges around it. Doubles as a coding-agent task |
+| `loam tasks <FEAT>` | `--service <id>` `--next` | The same checklist `loam verify` grades, read forwards: one work unit per promise the feature makes, each carrying the step it waits on (`describe`, `generate`, `implement`, `attested`) and the fact that closes it — only a confirmed claim in a non-stale verification record retires one, and an attested scenario stays visible. Derived every run and writes nothing. `--service` is a pure lens that adds what this service is waiting on elsewhere, and in a service repository it defaults to that service when the feature touches it; the frontier orders providers before consumers as advice, never a lock. The per-unit work packet, and `--next` is the single leaf packet an orchestrator hands a coding agent |
+| `loam gherkin [<FEAT>]` | `--service <id>` `--dry-run` | Emit spec scenarios as digest-stamped Gherkin `.feature` files into the service repo's `<gherkinDir>/loam/` |
+| `loam rebase [<FEAT>]` | `--service <id>` `--dry-run` `--living` | Pin the feature to the living versions it was written against, on the requirement axis and the contract axis. `--living` takes no feature: it pins the living corpus's `Realizes:` entries to the capability requirements they name, which is what makes `capability.realizes-stale` able to fire later |
+| `loam validate [<id>]` | `--service <id>` `--feature <id>` `--all` `--base <ref>` `--strict` `--errors-only` | Validate one service or feature, or the whole fleet in one run. JSON findings carry `locations[]`: an exact primary location when the check knows one, otherwise the narrowest proved scope. `--base` is the adoption ratchet, not a substitute for `loam diff`; `--strict` exits 1 on warnings; `--errors-only` drops the `ok` confirmations from the text view, keeping every warning |
+| `loam verify <FEAT>` | `--record <file>` `--results <file>` `--contract-results <file>` `--diff-answers <files...>` `--service <id>` | The done-check: derive a checklist of the feature's own promises, and record the answers with their evidence. `--results`/`--contract-results` answer claims from a test report; `--diff-answers` cross-examines two blind answer sets |
+| `loam vouch` | `--service <id>` `--yes` `--pack` `--sample <n>` | The human promotion `draft` → `verified`: stamp a living spec against the code it was written from. `--pack` prints the re-vouch reading pack; `--sample <n>` records a partial read as one. Run in the service's own repo |
+| `loam gate` | `--service <id>` `--since <ref>` `--strict` | Can this service deploy? A pure query over recorded evidence for deploy pipelines outside loam's lifecycle. Executes nothing, writes nothing; errors exit 1, warnings stay advisory. Without `--since` it grades in-flight features only; `--since` (the docs commit the last deploy recorded) adds every feature archived after it |
+| `loam archive <FEAT>` | `--approve` `--dry-run` | Merge a finished feature into the living specs, API, events, business tree and landscape; gated on what only the computed merge can see — the documents, never the code or the verification record. `--approve` overrides the judgement calls, never the mechanical losses |
+| `loam unarchive <FEAT>` | `--force` | Take that back: restore the living docs from the snapshot archive left behind, and re-open the feature |
+| `loam audit-openspec <root>` | `--write-mapping <path>` | Read-only inventory of an OpenSpec checkout/workspace/Store checkout. `--write-mapping` emits the decision skeleton you fill in |
+| `loam migrate-openspec <root>` | `--map <path>` `--mapping <path>` `--apply` `--target <directory>` | Validate a completed mapping against a re-read of the source, and materialize staged migration docs. Dry-run is the default |
+
+The envelope keeps three different questions apart, each on the command that can answer it — `ok`
+(the command ran) on every envelope, `valid` (the docs pass) on `validate`, and `verified` (every
+claim is confirmed **and** every scenario claim came from a test run) on `verify`, beside `verdict`,
+which carries the third state, `attested`, for a record whose scenarios rest on an agent's word.
+Every envelope also says what answered it — `contractVersion` for the shape and `version` for the
+binary — because the two move independently: a release bumps one and leaves the other alone, so a
+new build never reads as a contract break, and a green run from a loam that is behind is
+recognisable as one. Every success payload carries `command`, so a host holding a pile of envelopes
+branches on one field instead of guessing from the presence of `valid` or `services`.
 
 ## Working with AI agents
 
-`loam init --create` writes `AGENTS.md` into the docs repo — the process contract, travelling with the thing it describes; a join finds it there and refuses a `--docs` target without one. Into the repo it runs in, every `init` writes the six workflow bodies (`loam-adopt`, `loam-feature`, `loam-implement`, `loam-check`, `loam-verify`, `loam-ship`), **twice each for nineteen of the twenty tools**: as a command file in the tool's own command, prompt or workflow directory, which you type — `/loam-check` for most, `/loam:check` where the tool namespaces by directory, `@loam-check` in Amazon Q's prompt library — and as an Agent Skill at `<tool-dir>/skills/loam-<x>/SKILL.md`, which the model loads by itself when the task matches the skill's description. Codex is the twentieth: it reads `.codex/skills/` and loads no custom command files, so it gets skills only rather than files nothing will ever open. One shared body, a thin per-tool wrapper; `--no-commands` and `--no-skills` each suppress one delivery.
-
-Which tools is detected from the repo: `init` scans each of the 20 tools it knows for its own marker paths — usually just its dot-directory, but Copilot's are the files *inside* `.github/`, because almost every repo has a `.github/` and almost none of them means Copilot. The twenty are Claude Code, Cursor, GitHub Copilot, Gemini CLI, opencode, Cline, Amazon Q, Antigravity, Auggie, Codex, Continue, Crush, Devin, Factory, Junie, Kilo Code, Kiro, Qwen, Roo Code and Trae. It writes for the ones it finds, and falls back to Claude Code when it finds none. `--tools <ids>|all` overrides the scan; an unknown id is refused, not skipped. What it wrote for is recorded in `loam.json` as `agentTools`, which is how `loam doctor` reports a command or skill file that a newer loam would lay down (`doctor.agent-files-missing`) without mistaking a tool nobody selected for one that fell behind — and a repo that asked for one delivery only (`--no-skills`, `--no-commands`) is not reported as missing the other.
-
-**A generated file is a pointer, not a protocol.** It carries what does not move between releases — what the workflow is for, and the verbs in order — and defers this release's flags, finding codes and fix tables to `loam instructions <workflow>`, which ships inside the binary you are about to run. That split exists because the two go stale in opposite directions and only one of them is fixable: a file written once and never regenerated will eventually describe a different loam with total confidence, while the command cannot. `loam instructions` reads no `loam.json` and no docs repo, deliberately — `loam-adopt`'s own first step is to run `loam init` when there is no config, so it cannot be the step that requires one.
-
-**Nothing is ever overwritten and nothing is ever refreshed**, and that is the whole difference from `openspec update`: your edits to a generated file outrank the template, so drift is reported and never repaired. To make that reportable at all, every generated command and skill body opens with `<!-- generated by loam vX.Y.Z -->`; `loam doctor` reads **only that line** and raises `doctor.agent-files-stale` for a file carrying no stamp or an older one. It never compares bodies — "your file differs from the template" is one step from offering to rewrite it. The fix is a human's: read the file, then bump the stamp, or delete it and re-run `loam init`. The AGENTS.md version stamp (`agents.stale`) works the same way. A repo scaffolded by an older loam keeps the files it was given, protocol text and all — nothing rewrites them, and the stamp is how you know. Running a tool loam has no adapter for? Point it at `AGENTS.md` — the commands are thin wrappers over the CLI, so any runner that can read a file and exec `loam` has everything.
-
-## Fleet scale
-
-One docs repo, a hundred services, many teams: the docs repo bootstraps itself with `loam init --docs . --create`, ownership is CODEOWNERS, `vouch` and `archive` land through reviewed PRs, provenance runs in each service repo's own CI, and `loam list --json` grades every service on a presence-honest maturity ladder (`empty → partial → documented → sourced → vouched`). The full operating model — including `loam.json` per repo, the federated verification record, the per-service CI summary contract and the one-landscape decision — is in [SCHEMA.md](SCHEMA.md).
-
-The shape that has been measured, on a generated 120-service fleet with 400 and 800 op-linked landscape edges and 10 active features (built CLI, 8-core laptop, idle, wall clock including Node startup — of which ~0.16 s is Node itself): `loam list` **~0.45 s**, `loam validate --service <id>` — the command each service repo's CI runs — **~0.6 s**, and `loam status` **~1.3 s** — it grades every active feature's `delta.likec4`, so it costs about 0.11 s per feature *in flight* and is nearly flat in the size of the fleet (the same 120 services with one active feature answer in ~0.34 s). The fleet gate is the outlier: `loam validate --all` over the same 120 services takes **~13–14 s**, because it parses a fresh LikeC4 workspace per service rather than sharing one. That cost is fixed and linear in the number of services, and it is CPU inside the model construction, not I/O — bounded concurrency measurably does not help. It is the docs repo's own CI job and it is not on anybody's inner loop; on a machine whose cores are already busy, expect meaningfully more. `test/scale.test.ts` gates a smaller fleet — 30 services, 10 features, 24 op-linked edges — under a 110 s wall-clock ceiling: a blowup alarm sized to stay quiet inside a 64-file parallel suite, so it catches the order-of-magnitude regression an accidental per-service re-parse causes, not a two-fold one.
+`loam init --create` writes `AGENTS.md` into the docs repo — the process contract, travelling with
+the thing it describes; a join finds it there and refuses a `--docs` target without one. Into the
+repo it runs in, every `init` writes pointers for the six workflow bodies (`loam-adopt`,
+`loam-feature`, `loam-implement`, `loam-check`, `loam-verify`, `loam-ship`) plus the separate
+`loam-report` support protocol, **twice each for nineteen of the
+twenty-one targets**: as a command file you type — `/loam-check` for most, `/loam:check` where the
+tool namespaces by directory, `@loam-check` in Amazon Q's prompt library — and as an Agent Skill
+at `<tool-dir>/skills/loam-<x>/SKILL.md`, which the model loads by itself when the task matches. Two
+targets are skills only: Codex loads no custom command files, and its target writes
+`.codex/skills/` — a root Codex still reads but no longer documents (its skills page names only
+`.agents/skills`; select `agents` too if you want the documented one) — and
+`agents` is not a tool at all but the vendor-neutral `.agents/skills/` root that Cursor, GitHub
+Copilot, Codex, Gemini CLI, Zed and Roo Code each document reading — one copy those six share
+instead of six copies of the same bytes. `--no-commands` and `--no-skills` each suppress one
+delivery.
+
+**The explicit command is the recommended, predictable entry point; natural language remains a
+shortcut.** A normal chat lifecycle is `/loam-feature FEAT-101 "Split payments"` to propose,
+`/loam-implement FEAT-101 payment-service` in each affected checkout, `/loam-check`,
+`/loam-verify FEAT-101`, then `/loam-ship FEAT-101`. Most hosts use the flat slash spelling;
+Gemini namespaces it as `/loam:feature`, Amazon Q exposes `@loam-feature`, and a skills-only host
+uses its explicit skill syntax such as `$loam-feature`. Saying “implement FEAT-101” may load that
+same skill automatically. Both routes reach the same binary-owned protocol; after entry, the agent
+runs the status/edit/validate loop rather than asking the user to type every internal command.
+
+When the binary or agent integration behaves unexpectedly, `/loam-report` (or `$loam-report` on a
+skills-only host) collects a sanitized, reproducible local report under `loam-reports/`. It records
+the version, doctor/status evidence, stable codes, write state and the smallest safe reproduction;
+it does not repair the repo, retry a writer, include secrets, or upload anything. The support
+protocol ships in every agent profile but remains outside the six-step lifecycle.
+
+Which tools is detected from the repo: `init` scans each of the 21 targets it knows for its own
+marker paths — usually just its dot-directory, but Copilot's are the files *inside* `.github/` and
+the vendor-neutral one's is `.agents/skills/` rather than `.agents/`, because almost every repo has
+a `.github/`, a `.agents/` is claimed by other conventions too, and almost none of either means the
+tool. It writes for the ones it finds, and falls back to Claude Code when it finds none.
+`--tools <ids>|all` overrides the scan; an unknown id is refused, not skipped. `--agent-profile`
+selects `full`, `service` or `docs`, so a service checkout need not install feature-authoring and
+shipping entry points. `loam.json` records the tools, profile and sha256 of every pointer loam owns;
+that is how `doctor` distinguishes missing managed files from workflows nobody selected.
+
+**A generated file is a pointer, not a protocol.** It carries what does not move between releases —
+what the workflow is for, and the verbs in order — and defers this release's flags, finding codes
+and fix tables to `loam instructions <workflow>`, which ships inside the binary you are about to
+run. That split exists because the two go stale in opposite directions and only one of them is
+fixable: embedded protocol text eventually describes a different loam with total confidence, while
+the command cannot. Pointing at the binary is also what makes the protocol
+affordable to load: `loam instructions loam-check --no-fix-tables` prints the same page with its
+per-code fix tables collapsed to a line each — from a page that is almost all tables down to a few
+kilobytes — and `loam explain <code> --json` answers, one code at a time, whichever two or three of
+those rows a run actually reported. What each of those costs in bytes and tokens, page by page, is
+[docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md)'s payload table,
+generated from the tree rather than typed. A copy frozen into the generated file would have charged
+the whole page every session, and gone stale doing it. `AGENTS.md` itself was the one generated file that argument did
+not reach — it was the process contract *and* the reference manual, and every session paid for all
+of it — so four **reference pages** now come out of the binary instead, printed by
+`loam instructions`: `loam-codes` (which codes each invocation can raise), `loam-spine` (every join
+between the artifacts, and the `Based-On:` pins), `loam-authoring` (`arch.spec.md`, the generated
+Gherkin suite, frontmatter, and writing a feature a reviewer can follow) and `loam-done-check` (how
+`loam verify` derives its claims, and verified versus attested). A fifth page, `loam-drawing`,
+never stood in `AGENTS.md`: it teaches how to draw the map so that a person can read it — one
+relationship kind per kind of traffic, an arrow only where evidence gives one, a legend, and
+overview views that each answer one question. What stayed is what a reader needs to form a question at all: the layout,
+the cycle, which element is which service, the validator's rules and the archive gate. The
+orientation stays below both the 32,768-byte Codex chain limit and the smaller 12,000-byte
+workspace-rule ceiling — `test/agents.test.ts` fails the build the day it does not. Detailed pages are fetched only when the task reaches them. `loam init`
+writes **no file** for a reference page: a page printed on demand describes the loam you are
+running, not the one that scaffolded the repository.
+
+The code inventory is that same split applied twice, and the largest page is what it left behind.
+`loam instructions loam-codes` lists which codes each invocation can raise — nearly every code the
+scaffolded docs name, and the one fact no other surface carries — and no longer says what
+any of them means, because `loam explain <code>` answers that from the binary actually running and a
+paragraph written once at `init` cannot. Dropping the duplicated gloss came first and took the file
+from 120,896 bytes to 109,399; moving the inventory off it took the remaining 79,679. The OpenSpec
+migration codes keep their notes inline on the page, because they are almost all of the codes
+`loam explain` does not answer yet, and a pointer to an explanation that does not exist is worse
+than the prose it replaced.
+
+**Refresh is ownership-aware.** Re-running `loam init` may replace a pointer only when its bytes
+still match the digest recorded when loam last wrote it. The first human edit breaks that equality
+and permanently wins; loam preserves the file and `doctor` reports its stale stamp for review.
+Missing pointers are created. This gives unchanged repositories current entry points without an
+`openspec update`-style overwrite of team customizations.
+
+For hosts that reach tools through MCP rather than a shell, see [the MCP server](WORKFLOW.md#the-mcp-server).
+Read tools declare `readOnlyHint`; every tool declares the shared envelope output schema; the compact
+orientation and all workflow/support/reference pages are MCP resources, including a compact loam-check
+resource without the 223-row fix table. `loam init --mcp` writes the
+read-only host entry. `--mcp-author` is a separate explicit choice that adds bounded writers while
+still excluding vouch, evidence recording and a committing archive. An existing `.mcp.json` is
+always preserved byte for byte, with the entry printed for manual merge.
 
 ## Docs
 
-- [WORKFLOW.md](WORKFLOW.md) — the working protocol: the artifact graph and its derived states, what gates and what only advises, the six workflows, and how an agent drives the whole cycle from `--json`.
-- [SCHEMA.md](SCHEMA.md) — the docs-repo layout, each artifact's grammar, and the decisions behind them: the coherence rules, how `archive` writes and `unarchive` undoes, operating at fleet scale.
-- [COMPARISON.md](COMPARISON.md) — loam vs OpenSpec, honestly: seven axes, when OpenSpec is enough, what loam refuses to borrow.
-- [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) — moving an OpenSpec repo onto loam: what maps, what is lost, what must be added.
-- [CHANGELOG.md](CHANGELOG.md) — what changed; one `[Unreleased]` entry so far, because nothing has been released yet.
+- [QUICKSTART.md](QUICKSTART.md) — the shortest complete path from install to adoption, the first
+  agent-driven feature, and a local problem report when something behaves unexpectedly.
+- [WORKFLOW.md](WORKFLOW.md) — the working protocol: day zero, the artifact graph and its derived
+  states, what gates and what only advises, the six workflows, the per-command notes, and how an
+  agent drives the cycle from `--json`.
+- [SCHEMA.md](SCHEMA.md) — the docs-repo layout, each artifact's grammar, and the decisions behind
+  them: the coherence rules, how `archive` writes and `unarchive` undoes, operating at fleet scale.
+- [COMPARISON.md](COMPARISON.md) — where loam fits beside architecture-as-code tools, software and
+  event catalogs, contract verification and diff engines, requirements traceability, and code-level
+  architecture checks. Each is treated as a neighbouring specialist, not an opponent loam needs to
+  replace. One dated section sets out what the spec-driven change tools — OpenSpec, Spec Kit and
+  Kiro — each offer for a change that crosses repositories, what is still open upstream, and where
+  loam differs.
+- [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) — moving an OpenSpec repo onto loam: what
+  maps, what is lost, what must be added.
+- [ROADMAP.md](ROADMAP.md) — the evidence-backed improvement plan, priorities, non-goals and exit
+  criteria.
+- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.13 plus the changes on `main` under
+  `[Unreleased]`.
+- [docs/SERVICE-TEAMS.md](https://github.com/ybotok/loam/blob/main/docs/SERVICE-TEAMS.md) — one
+  screen for a team whose repository is one service in the fleet: the commands, the slash
+  commands, what to know before vouching, and the codes they will actually meet.
+- [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md) — what a
+  fleet-sized run costs, with the method, the machine and the committed runs behind every number,
+  and what each payload loam hands an agent weighs in bytes and tokens.
 
 ## Development
 
@@ -218,31 +705,53 @@ npm run setup              # or: npm ci && npm run build
 npm run dev -- --help      # run the CLI from source
 npm run lint
 npm run typecheck
+npm run arch:check          # package-level dependency graph stays acyclic
 npm test                   # vitest
 npm run test:coverage      # full src/**/*.ts coverage with enforced thresholds
 npm run test:package       # clean, pack, install the tarball, run its loam binary
-npm run pilot:check        # the pilot harness against its own example manifest
-# optional, against the exact upstream checkout named in "loam vs OpenSpec" (the
-# flag matters: --baseline defaults to canary, and the sweep refuses a checkout
-# at any other HEAD):
+# optional, against the exact upstream checkout named in MIGRATING-from-OpenSpec.md
+# (--baseline defaults to release, the certified pin; every pinned baseline refuses a
+# checkout at any other HEAD, and only --baseline latest sweeps an unpinned one):
 npm run test:openspec-corpus -- --baseline release /path/to/OpenSpec
 ```
 
-`npm run setup` is `bash scripts/setup.sh`, so on Windows use `npm ci && npm run build`. [CONTRIBUTING.md](CONTRIBUTING.md) has the rest — the local loop, what a reviewable change looks like, and the release posture; the pilot harness itself is documented under [`docs/pilot/`](docs/pilot).
+`npm run setup` is `bash scripts/setup.sh`, so on Windows use `npm ci && npm run build`.
+[CONTRIBUTING.md](CONTRIBUTING.md) has the rest — the local loop, what a reviewable change looks
+like, and the release posture.
 
 ## Status
 
-Every command in the table is implemented, `verify --results` included — the generated suite's cucumber report feeds the done-check, closing the TDD loop mechanically. Remaining: `render` (diagrams — delegated to LikeC4's own tooling), `health` **compose**, UI-prototype generation. Composing a `health.yaml` is what is missing, not reading one: `validate` already grades its `slis:`/`alerts:` ids against the living `arch.spec.md`'s `Covers:` lines (`health.uncovered`, `health.invalid`).
-
-The release-candidate manifest is `@ybotok/loam@0.1.0-beta.1`: as of 2026-08-06 the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships under the maintainer's own npm user scope. The registry had no package at that scoped name when it was last checked — a registry fact this repository cannot confirm, so re-check it before tagging. Until it is published, use the clone install above rather than treating the package as published.
+Every command in the table is implemented, including `verify --results` and its contract-test
+sibling `verify --contract-results`, the full AsyncAPI feature lifecycle, OpenAPI path-item and
+component baselines, the `architecture/permissions.yaml` authorization vocabulary, the declared- and
+authored-capability axes with the `Realizes:` join, use cases graded as `dynamic view`s, the
+`glossary/<term>.md` domain vocabulary checked through the links that cite it, and the
+`architecture/obligations.yaml` architectural obligations checked through `#obl-` tags and
+`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the scheduled CI
+`stability` job has still to be observed green. Speculative `render`, health composition and UI
+generation come later. Behind that status stand **205 test files** (counted 2026-10-22): the count is graded
+against a live readdir by `test/docs-facts.test.ts`, so this sentence fails the suite the moment it
+trails the tree.
+
+The package is published as [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam): the
+unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships under the
+maintainer's own npm user scope. Releases are tag-driven and maintainer-only
+([CONTRIBUTING.md](CONTRIBUTING.md)). This checkout is `0.2.0-alpha.13` — a version pinned to
+`package.json` by a drift test, so it is always the version of the checkout you are reading, and for
+that reason it says nothing about whether that version reached npm.
+`npm view @ybotok/loam dist-tags` is the answer to what installs.
 
 ## Contributing
 
-Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the local loop (`lint`, `typecheck`, `test`, `test:package`) and what a reviewable change looks like here.
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the complete local
+gate and what a reviewable change looks like here.
 
 ## Security
 
-Please do not report a suspected vulnerability in a public issue. [SECURITY.md](SECURITY.md) says what to include and names the intended private route — GitHub Private Vulnerability Reporting, which is not switched on for the canonical repository yet, so the link there does not resolve until it is.
+Do not put vulnerability details in a public issue. Report privately through
+[GitHub Private Vulnerability Reporting](https://github.com/ybotok/loam/security/advisories/new),
+which is enabled for this repository; [SECURITY.md](SECURITY.md) says what to include and what to
+leave out.
 
 ## License