docs: sync to v0.5.0 and carry the cutover's evidence forward

CLAUDE.md

@@ -2,7 +2,7 @@
 
 Decision memory for human- and agent-authored plans — machine-readable ADRs
 that are enforceable in CI and legible to agents, without leaving git.
-Status: early — phases 0–6 landed and v0.4.0 is public. `@adrkit/core`,
+Status: early — phases 0–6 landed and v0.5.0 is public. `@adrkit/core`,
 `@adrkit/evaluator`, `@adrkit/cli` (`lint`, `new`, `graph`, `explain`,
 `check`, `queue`, `migrate --from madr`, `evaluate`) are published on npm, as is
 the independently versioned `@adrkit/spec-kit` Spec Kit extension (0.1.2); the
@@ -17,16 +17,16 @@ driven through the official MCP Inspector. The Inspector defaults to the 2025
 era; select the modern one with `"protocolEra": "modern"` (or `"auto"`) in the
 server's entry in the Inspector's `mcp.json` — there is no CLI flag for it.
 
-## Inbound `@adr` markers (v0.4.0 explain; check/CI extension proposed)
+## Inbound `@adr` markers (v0.5.0: explain, check, and CI)
 
 A file can declare the decision it lives under by putting `@adr 0012` on a
 dedicated comment line inside its first 8192 bytes. v0.4.0 shipped that inbound
-edge for `adr explain <path>` under
-[ADR-0021](./docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md)
-and [#97](https://github.com/mbeacom/adrkit/pull/97). This branch proposes
+edge for `adr explain <path>` under ADR-0021 and
+[#97](https://github.com/mbeacom/adrkit/pull/97). v0.5.0 extended the same
+resolution to `adr check` and the governing-decisions Action under
 [ADR-0022](./docs/adr/0022-scan-inbound-markers-in-check-and-ci-without-giving-them-exit-code-authority.md),
-which extends the same resolution to `adr check` and the governing-decisions
-Action. No schema change: `AdrFrontmatter`,
+which **supersedes ADR-0021** — read 0022, not 0021, for the current scope. No
+schema change: `AdrFrontmatter`,
 `AffectsType`, and `schema/adr.schema.json` are untouched.
 
 Two properties are load-bearing and easy to break:

README.md

@@ -225,24 +225,35 @@ different artifact from a heading convention. That is the whole thesis.
 
 Early, under active development, and deliberately honest about what is proven.
 
-- **Published — v0.4.0 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`,
+- **Published — v0.5.0 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`,
   the deterministic Pass 0 `@adrkit/evaluator`, and the read-only `@adrkit/mcp`
   server are all implemented and released. The MCP server speaks both protocol
   eras and passed real-session dogfood against the published artifact on each,
   driven through the official MCP Inspector
   ([ADR-0018](docs/adr/0018-adopt-mcp-sdk-v2-and-serve-protocol-revision-2026-07-28-dual-era.md)).
-- **New in v0.4.0, and at rung 1 only.** A file can declare the decision it
-  lives under with an `@adr <id>` marker on a dedicated comment line, and
-  `adr explain` resolves that inbound edge alongside the `affects` patterns that
-  already matched the path
-  ([ADR-0021](docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md)).
-  The feature reaches `adr explain` and nothing else: `adr check`, the Action,
-  and the Spec Kit context script do not scan markers, so no CI semantics move.
+- **Expanded in v0.5.0, and at rung 1 only.** A file can declare the decision it
+  lives under with an `@adr <id>` marker on a dedicated comment line. v0.4.0
+  resolved that inbound edge in `adr explain`
+  ([ADR-0021](docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md));
+  v0.5.0 extended it to `adr check` and the governing-decisions Action, so a
+  marker-declared record appears alongside the `affects` patterns that already
+  matched the path
+  ([ADR-0022](docs/adr/0022-scan-inbound-markers-in-check-and-ci-without-giving-them-exit-code-authority.md),
+  superseding ADR-0021).
+  A marker is read only where the file's own format hides it — never inside a
+  fenced block, and in markdown only from `<!--` or `{/*`
+  ([ADR-0023](docs/adr/0023-read-a-marker-only-where-the-format-hides-it-fences-and-markdown-prose.md)).
+  Markers add governance context and findings, but never exit-code authority: no
+  marker a pull request writes can fail a check. A changed ADR record that fails
+  validation still does — that is what the check is for.
   Evidence is unit, contract, and purity coverage plus maintainer verification —
   **rung 1** of the ADR-0014 ladder, not the rungs 1–2 the surfaces below carry.
   Contributed by [@aballiet](https://github.com/aballiet) in
-  [#97](https://github.com/mbeacom/adrkit/pull/97), the first community feature
-  this project has shipped.
+  [#97](https://github.com/mbeacom/adrkit/pull/97) — the first community feature
+  this project has shipped — and
+  [#106](https://github.com/mbeacom/adrkit/pull/106), and by
+  [@davesheffer](https://github.com/davesheffer) in
+  [#109](https://github.com/mbeacom/adrkit/pull/109).
 - **Landed, maintainer reference-verified — not yet externally validated.** The
   Phase 6 ARB queue (`adr queue` plus the managed-issue Action) is verified on
   rungs 1–2 of the

docs/DISTRIBUTION.md

@@ -5,8 +5,9 @@ the `@adrkit/*` CLI presence in the MCP and ADR-tooling ecosystems. It contains
 ready-to-paste content and exact procedures.
 
 > **Submission status.** The official MCP registry entry (§A) **has been published**
-> — `dev.adrkit/mcp` at `0.4.0`, status `active` (first published 2026-07-28 at
-> `0.2.1`; re-published 2026-07-31 for v0.3.0 and 2026-08-08 for v0.4.0). Every other
+> — `dev.adrkit/mcp` at `0.5.0`, status `active` (first published 2026-07-28 at
+> `0.2.1`; re-published 2026-07-31 for v0.3.0, 2026-08-08 for v0.4.0, and
+> 2026-08-10 for v0.5.0). Every other
 > venue below remains prepared but **not submitted**. Every outbound action —
 > publishing to a registry, opening a PR, filling a form, creating a git tag, or
 > posting anywhere — is performed by a human, never by tooling or an agent.
@@ -32,13 +33,13 @@ GitHub repo, so a small number of prerequisites unblock several venues at once.
 ### P1 — npm packages are published ✅
 
 **Satisfied.** `@adrkit/mcp`, `@adrkit/cli`, `@adrkit/core`, and `@adrkit/evaluator`
-are published at `0.4.0` — the exact version `server.json` names. The MCP registry
+are published at `0.5.0` — the exact version `server.json` names. The MCP registry
 hosts *metadata only*; the npm package must already exist at the version named in
-`server.json`. Verified with `npm view @adrkit/mcp@0.4.0 version` → `0.4.0`.
+`server.json`. Verified with `npm view @adrkit/mcp@0.5.0 version` → `0.5.0`.
 
 ### P2 — `mcpName` in the **published** `@adrkit/mcp` ✅
 
-**Satisfied.** `npm view @adrkit/mcp@0.4.0 mcpName` returns `dev.adrkit/mcp`,
+**Satisfied.** `npm view @adrkit/mcp@0.5.0 mcpName` returns `dev.adrkit/mcp`,
 matching `server.json` `name` exactly.
 
 The requirement, and why the ordering mattered: the official registry verifies npm
@@ -104,7 +105,8 @@ confusion in every listing:
 ## A. Official MCP registry (`registry.modelcontextprotocol.io`) — **PUBLISHED**
 
 **Status: published.** First published 2026-07-28 via the DNS namespace path;
-re-published 2026-07-31 for v0.3.0 and 2026-08-08 for v0.4.0. `dev.adrkit/mcp` is listed at `0.4.0` with
+re-published 2026-07-31 for v0.3.0, 2026-08-08 for v0.4.0, and 2026-08-10 for
+v0.5.0. `dev.adrkit/mcp` is listed at `0.5.0` with
 status `active` and `isLatest: true`; see §A4 for the verified response. The
 subsections below are retained as the procedure to repeat on each release.
 
@@ -182,32 +184,34 @@ mcp-publisher publish
 curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mcp"
 ```
 
-**Verified 2026-08-08** (the v0.4.0 re-publication; the entry first went live
-2026-07-28 at `0.2.1`, and was re-published 2026-07-31 for v0.3.0). The registry
-returns the `0.4.0` record as latest:
+**Verified 2026-08-10** (the v0.5.0 re-publication; the entry first went live
+2026-07-28 at `0.2.1`, and was re-published 2026-07-31 for v0.3.0 and 2026-08-08
+for v0.4.0). The registry returns the `0.5.0` record as latest:
 
 | Field | Value |
 |---|---|
 | `name` | `dev.adrkit/mcp` |
-| `version` | `0.4.0` |
-| `packages[0].identifier` / `version` | `@adrkit/mcp` / `0.4.0` |
+| `version` | `0.5.0` |
+| `packages[0].identifier` / `version` | `@adrkit/mcp` / `0.5.0` |
 | `transport.type` | `stdio` |
 | `_meta…/official.status` | `active` |
 | `_meta…/official.isLatest` | `true` |
-| `_meta…/official.publishedAt` | `2026-08-08T23:16:38.484551Z` |
+| `_meta…/official.publishedAt` | `2026-08-10T16:20:32.653575Z` |
 
-The registry retains the superseded `0.2.1` and `0.3.0` records alongside it;
-`isLatest` is the field that distinguishes them.
+The registry retains the superseded `0.2.1`, `0.3.0`, and `0.4.0` records
+alongside it; `isLatest` is the field that distinguishes them, and it is `false`
+on all three.
 
 Rerunning `docs/RELEASING.md` step 7's check with this release's version
-substituted — the response containing both `dev.adrkit/mcp` and `0.4.0` — exits 0.
+substituted — the response containing both `dev.adrkit/mcp` and `0.5.0` — exits 0.
 Step 7 itself stays written against `0.3.0`: it sits inside the completed v0.3.0
 cutover runbook, which is retained as a worked template whose versions the next
 cutover substitutes rather than a live command to run verbatim.
 
 A subsequent release must re-run `mcp-publisher publish` with `server.json`'s two
 version fields bumped; the registry pins a specific npm version and does not track
-`latest` on its own.
+`latest` on its own. Nothing in `release.yml` does this, so it stays a human step
+after the npm publish lands.
 
 ### A5 — the committed `server.json`
 
@@ -217,7 +221,7 @@ version fields bumped; the registry pins a specific npm version and does not tra
   "name": "dev.adrkit/mcp",
   "title": "adrkit decision memory",
   "description": "Deterministic, offline, read-only ADR decision memory for coding agents. No model or network calls.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "websiteUrl": "https://adrkit.dev",
   "repository": {
     "url": "https://github.com/mbeacom/adrkit",
@@ -229,7 +233,7 @@ version fields bumped; the registry pins a specific npm version and does not tra
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@adrkit/mcp",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -260,7 +264,7 @@ version fields bumped; the registry pins a specific npm version and does not tra
 **Listing criteria met?** Yes — schema-valid, npm package exists at the manifest
 version, stdio transport, public repo. Both original blockers (the human namespace
 proof and an npm publication carrying `mcpName`) were cleared for v0.2.1 and remain
-satisfied at v0.4.0.
+satisfied at v0.5.0.
 
 ---
 
@@ -542,8 +546,8 @@ ARB-queue Action from its moving major tag like any other:
 uses: mbeacom/adrkit/packages/ci/queue@v0
 ```
 
-`v0` moves with every release, so it now peels to the v0.4.0 release commit
-(`c3dff3a`) rather than to `31bed03`. That is the point of a moving major tag; the
+`v0` moves with every release, so it now peels to the v0.5.0 release commit
+(`c6bceac`) rather than to `31bed03`. That is the point of a moving major tag; the
 commit named below is the historical one that first made `@v0` resolve.
 
 The rest of this section is the historical record of why a full-commit pin was
@@ -631,7 +635,7 @@ itself, not a pin.
 
 No distribution-blocking source edits are currently delegated to another
 workstream. `packages/mcp/package.json` declares `"mcpName": "dev.adrkit/mcp"`
-(matching `server.json` `name`), v0.4.0 has been cut, and the registry entry is
+(matching `server.json` `name`), v0.5.0 has been cut, and the registry entry is
 **published** at that version (§A4). Nothing in this repository blocks any remaining venue; what is
 left is per-venue human submission, tracked in the readiness table above.
 

docs/RELEASING.md

@@ -9,12 +9,12 @@ Action:
 | `@adrkit/evaluator` | npm |
 | `@adrkit/cli` (`adr`) | npm |
 | `@adrkit/mcp` (`adrkit-mcp`) | npm |
-| `packages/ci/action.yml` | Git tag (latest immutable release `v0.4.0`, moving `v0`) |
+| `packages/ci/action.yml` | Git tag (latest immutable release `v0.5.0`, moving `v0`) |
 
 `@adrkit/ci` stays private because GitHub executes the committed Action bundle
 directly from the referenced repository ref.
 
-The coordinated lockstep surface is published; the current release is `v0.4.0`. `@adrkit/core`,
+The coordinated lockstep surface is published; the current release is `v0.5.0`. `@adrkit/core`,
 `@adrkit/evaluator`, and `@adrkit/cli` use GitHub Actions Trusted Publishing.
 `@adrkit/mcp` was created with the isolated one-time bootstrap path below; its
 Trusted Publisher and token-restriction cleanup must be completed before the
@@ -258,7 +258,7 @@ Two notes worth carrying forward from the v0.3.0 cutover:
 
 - `bun run release:pack` triggers a **non-frozen** `bun install`, which can pull
   transitive drift into the committed `packages/ci/dist` bundles. Check
-  `git status` after step 2; it was clean for v0.3.0 and for v0.4.0.
+  `git status` after step 2; it was clean for v0.3.0, v0.4.0, and v0.5.0.
 - The published-consumer advisory audit reported **0 vulnerabilities** at v0.3.0,
   and `KNOWN_CONSUMER_ADVISORY_ACCEPTANCES` is now empty
   ([ADR-0018](adr/0018-adopt-mcp-sdk-v2-and-serve-protocol-revision-2026-07-28-dual-era.md)
@@ -289,6 +289,23 @@ Three more from the v0.4.0 cutover, all of which cost time:
   skips the adapter because the packed tarball's integrity matches the registry.
   Tracked in [#104](https://github.com/mbeacom/adrkit/issues/104).
 
+Two from the v0.5.0 cutover:
+
+- **The #104 dry-run failure is confirmed dry-run-only.** Before tagging, the
+  claim above was checked rather than trusted: the registry's published
+  `dist.shasum` for `@adrkit/spec-kit@0.1.2` was compared against the shasum the
+  dry run had just packed, and they matched exactly, as did `dist.integrity`. The
+  real run then skipped the adapter and published only the four lockstep packages.
+  `npm view @adrkit/spec-kit@<version> dist.shasum` is a cheap way to turn "the
+  real run should skip it" into "the real run will skip it" before you tag.
+- **The MCP registry is not part of the release workflow.** `release.yml` has no
+  `mcp-publisher` step, so `dev.adrkit/mcp` keeps serving the previous version
+  until a human re-publishes it (see
+  [DISTRIBUTION.md](DISTRIBUTION.md) §A). Its three prerequisites are worth
+  re-checking against the *published* package rather than the working tree:
+  `npm view @adrkit/mcp@<version> version`, `npm view @adrkit/mcp@<version>
+  mcpName`, and both `version` fields in `packages/mcp/server.json`.
+
 1. Start from the final release commit on `main`.
 
    ```sh

site/src/components/Hero.astro

@@ -14,7 +14,7 @@ const { title = data.title, tagline, actions = [] } = data.hero || {};
 				</svg>
 				CLI works today
 			</span>
-			<span>v0.4.0 on npm · decision memory in git</span>
+			<span>v0.5.0 on npm · decision memory in git</span>
 		</div>
 
 		<h1 id="_top" data-page-title set:html={title} />

site/src/content/docs/ci.mdx

@@ -39,7 +39,7 @@ jobs:
         #   token: ${{ github.token }}
 ```
 
-`v0` is a moving major tag. Pin the immutable `v0.4.0` tag or a commit SHA for
+`v0` is a moving major tag. Pin the immutable `v0.5.0` tag or a commit SHA for
 maximum reproducibility.
 
 ## Publish the ARB operations queue
@@ -76,7 +76,7 @@ jobs:
 <Aside type="note" title="Pinning the queue Action">
 	`queue@v0` resolves because the `v0` tag points at a commit containing
 	`packages/ci/queue/action.yml` — first true of the v0.2.1 release, and the tag
-	has moved forward with each release since (currently the v0.4.0 commit, `c3dff3a`). `@v0`
+	has moved forward with each release since (currently the v0.5.0 commit, `c6bceac`). `@v0`
 	is a moving tag; pin the full commit SHA instead if you need a byte-immutable
 	reference. Phase 6 is landed and maintainer reference-verified; external
 	validation ([ADR-0014](/adr/) rung 3) remains open.

site/src/content/docs/index.mdx

@@ -18,7 +18,7 @@ hero:
 <div class="adr-home">
 	<section class="adr-status-band" aria-label="Project status">
 		<div class="adr-status-band__item">
-			<span class="adr-status adr-status--current">Published · v0.4.0</span>
+			<span class="adr-status adr-status--current">Published · v0.5.0</span>
 			<p>
 				<code>@adrkit/core</code>, <code>@adrkit/cli</code>,
 				<code>@adrkit/evaluator</code>, and <code>@adrkit/mcp</code> are on npm,

site/src/content/docs/quickstart.mdx

@@ -10,7 +10,7 @@ decisions govern a file, renders the decision graph, migrates an existing MADR
 corpus in place, emits the ARB operations queue, and runs the deterministic
 evaluator.
 
-<Aside type="tip" title="Published on npm (v0.4.0)">
+<Aside type="tip" title="Published on npm (v0.5.0)">
 	`@adrkit/cli` is live. Consumers install it with your Node package manager and
 	run the `adr` binary — no clone required. Published artifacts are Node-targeted
 	([ADR-0010](/adr/0010-bun-toolchain/)); Bun is used for developing adrkit