textus 0.35.1 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3e6ac596658c63369ce977d194a2c43d0a789cdfa97b04d100b70e572165e63
-  data.tar.gz: c3ed7085fa38777fdc6e8a38e8c4c8f4a51ce113065f24b42f596aa220acb9f3
+  metadata.gz: 15b2e8bcfb3e83425617ee187705b88ad99c1f96671a7ad04a8394073f98065d
+  data.tar.gz: e0711f287c8739fcc2e5f9507fd5637b9c63159b2d8e364f9d65f338138ff432
 SHA512:
-  metadata.gz: a95c23aaf19216505f272f0262b66e1e7a3e01b3e78a2b8062ab827a3c8109a6d085348b3e1b1e664a41f0bbdeaf46cf736b47fe211495905445c9ae283c88fa
-  data.tar.gz: 453327b6cea08e0102e76dd22723d6f77a69d10f8d6810427e23934956d5a332b5f9d33b81d568bf7529cf8ab83bdfb6b323b447d2d9dead6d06c2b703e66ac4
+  metadata.gz: 74ec9edba22fdd7884c7bf1a16b9f73a636524c11f889824a516775857294ea674ebd6f6fe9b0a4d98028d30cf5673b51c376760968baa4d8413c83a33475484
+  data.tar.gz: c097ccd942039828754bd70ae2f457e172ca88166c318c72199138e126301aa4432cec318ff77c456a73de4176c0e6fe65160cca899111dcd27785adc9eff62c

data/CHANGELOG.md

@@ -9,7 +9,140 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
-## 0.35.1 — 2026-05-31 — RSpec foundation consolidation (test-only)
+## Unreleased
+
+## 0.39.0 — 2026-06-01 — Native ignore patterns for entry enumeration ([ADR 0042](docs/architecture/decisions/0042-native-ignore-patterns-for-entry-enumeration.md))
+
+No `textus/3` wire-format change. Manifest schema gains one optional, backward-compatible key (`ignore:`); existing manifests are unaffected.
+
+### Added
+
+- **Per-entry `ignore:` globs on `nested` entries (ADR 0042).** A `nested`
+  entry may declare a list of gitignore-style globs (e.g.
+  `["**/node_modules/**", "**/dist/**"]`) to keep vendored or generated
+  subtrees out of the store. Patterns are honoured by **one shared filter
+  seam** consulted by both resolver enumeration (`list`, `build`) and
+  `textus doctor`, evaluated *above* key-legality: an ignored path is excluded,
+  never judged. This closes the prior divergence where a store could `list`
+  cleanly while `doctor` was red on the same vendored paths. Matching is
+  segment-wise globstar — `**` spans zero or more path segments; within a
+  segment `*` is anchored and `{a,b}` alternates (stdlib `File.fnmatch`,
+  no new dependency). Documented in
+  [`docs/reference/zones.md`](docs/reference/zones.md#nested-entries).
+
+### Internal
+
+- **Dogfood textus in its own repo ([ADR 0041](docs/architecture/decisions/0041-dogfood-textus-in-its-own-repo.md)).**
+  A self-development store and MCP wiring for textus's own repository. No change
+  to the published gem's behavior.
+
+## 0.38.0 — 2026-05-31 — MCP serve acts as agent by default ([ADR 0040](docs/architecture/decisions/0040-mcp-connection-role-and-two-channels.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed
+
+- **The MCP connection acts as the `agent` role by default (ADR 0040).**
+  `textus mcp serve` now resolves its acting role through the standard chain
+  (`--as` → `TEXTUS_ROLE` → `.textus/role`) with an `agent` transport default,
+  instead of silently inheriting the global `human` default. The agent channel
+  proposes; human authority (accept/reject, direct writes) is exercised through
+  the human's own CLI.
+
+### Breaking
+
+- **MCP writes that relied on human authority now require `propose` + `accept`,
+  or an explicit `--as=human`.** A connection that previously `put` straight into
+  `working/`/`identity/` over MCP will get `write_forbidden`. Launch
+  `textus mcp serve --as=human` (or set `TEXTUS_ROLE`/`.textus/role`) to restore
+  the old behavior knowingly; the gate is then advisory.
+
+## 0.37.0 — 2026-05-31 — MCP catalog derive-or-guard ([ADR 0039](docs/architecture/decisions/0039-mcp-catalog-derive-or-guard.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed
+
+- **MCP catalog is now derived from one per-verb contract (ADR 0039).** Each
+  use-case declares its interface once (`verb`/`summary`/`surfaces`/`arg`/`response`);
+  the MCP `tools/list` schemas and `tools/call` dispatch are generated from it.
+  The hand-written `Tools::REGISTRY` and `ToolSchemas` array are gone — a core
+  interface change can no longer leave MCP silently stale (it is derived, or a
+  guard spec fails the build).
+
+### Added
+
+- **`propose` and `rules` are first-class verbs** (Ruby/MCP; `propose` also CLI),
+  no longer MCP-only composed tools. MCP is now a pure projection of the core
+  verb set filtered by `surfaces(:mcp)`.
+
+### Removed
+
+- **Examples consolidated to a single reference.** Removed `examples/hello/` and
+  `examples/claude-plugin/`, keeping `examples/project/` as the one worked example —
+  the role gate (propose → accept), build/publish to `CLAUDE.md`/`AGENTS.md`, schemas,
+  a template, and a `:transform_rows` hook in one place. The `skill_fanout` recipe
+  sidecar, its spec, and the `docs/recipes/` page that existed only to document it are
+  removed alongside. All living docs and `boot`'s `docs.example` now point at
+  `examples/project/`.
+
+### Breaking
+
+- **MCP `schema` tool is keyed by entry `key`, not `family`.** It routes through
+  the `schema` (SchemaEnvelope) verb. Callers passing `{ "family": "..." }` must
+  pass `{ "key": "..." }` instead.
+- **The dispatcher verb `schema_envelope` is renamed `schema`.** Ruby callers
+  using `store.as(role).schema_envelope(key)` must use `store.as(role).schema(key)`.
+
+## 0.36.0 — 2026-05-31 — Transports as pure framings: one verb vocabulary, one session, lifted to core ([ADR 0036](docs/architecture/decisions/0036-transports-as-pure-framings.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed (BREAKING)
+
+- **MCP tool names aligned with the CLI/Ruby verb vocabulary.** The five renamed tools adopt
+  the canonical core names: `tick`→`pulse`, `find`→`list`, `read`→`get`, `write`→`put`,
+  `fetch_stale`→`fetch_all`. The `textus/3` wire format is unchanged; agents that discover
+  tools via `tools/list` (the documented pattern) adapt automatically. Hardcoded tool names
+  in `.mcp.json` files, prompts, or scripts must be updated.
+
+### Added
+
+- **First-class CLI `propose` verb** — `textus propose KEY --as=ROLE [--stdin]` auto-prefixes
+  the manifest's `propose_zone`, matching what the MCP `propose` tool has always done. The
+  previous workaround (`textus put proposals.KEY --as=ROLE`) still works but the caller no
+  longer needs to know the queue zone name.
+- **Stateful `textus pulse` (no `--since`)** — when `--since` is omitted, `pulse` reads and
+  updates a per-role cursor from `.textus/.state/cursor.<role>` (gitignored). Successive
+  invocations see only what changed since the last look, without hand-tracking a sequence
+  number. `--since=N` remains the explicit, stateless override.
+- **`Textus::Session`** — the agent session (role + cursor + propose_zone + manifest_etag,
+  with cursor-advance, `ContractDrift` / `CursorExpired` detection) is now a core value
+  object, not MCP-internal state. `MCP::Session` is now an alias to it.
+- **`Store#session(role:)`** — returns a `Textus::Session` for Ruby embedders; the
+  documented Ruby agent loop uses it instead of hand-tracking `since:`.
+
+## 0.35.2 — 2026-05-31 — Evaluation field rename + Container doc fix (internal)
+
+No `textus/3` wire-format change; no manifest-schema change; no library behavior
+change. Internal refactor and documentation correction only.
+
+### Changed
+
+- `Domain::Policy::Evaluation` now names its manifest member `manifest` directly
+  instead of declaring it `snapshot` and exposing it through a `def manifest =
+  snapshot` alias. Every predicate already read `eval.manifest`; the field now
+  matches its only call name.
+- Dropped the unused `def role = actor` alias on `Evaluation` (zero readers; the
+  real field `actor` is used everywhere).
+
+### Fixed
+
+- Architecture doc (`docs/architecture/README.md`) listed an `:authorizer` member
+  on `Container` that the code does not have. Removed it so the doc matches
+  `lib/textus/container.rb` (7 fields).
+
+
 
 No `textus/3` wire-format change; no manifest-schema change; no library behavior change.
 Test-suite maintenance only.
@@ -343,7 +476,7 @@ Protocol remains `textus/3`.
   `refresh`, `refresh_stale`, `schema`, `rules`). Session state (cursor,
   role, manifest_etag) held server-side. Manifest drift surfaces as
   `ContractDrift` (-32001); cursor expiry as `CursorExpired` (-32002).
-  See [`docs/mcp.md`](docs/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
+  See [`docs/reference/mcp.md`](docs/reference/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
 - `examples/claude-plugin/.mcp.json` and migrated skills/commands/agents —
   zero `textus <verb>` shell strings remain in plugin markdown.
 

data/README.md

@@ -8,6 +8,7 @@
 <p align="center">
   <a href="https://github.com/patrick204nqh/textus/actions/workflows/ci.yml"><img src="https://github.com/patrick204nqh/textus/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://rubygems.org/gems/textus"><img src="https://img.shields.io/gem/v/textus.svg" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/textus"><img src="https://img.shields.io/gem/dt/textus.svg" alt="Gem Downloads"></a>
   <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg" alt="Ruby"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
@@ -29,13 +30,35 @@ flowchart LR
     human(["human"]) -->|author| knowledge["knowledge<br/>(canon)"]
     agent(["agent"]) -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    proposals -->|human accepts| knowledge
+    proposals ==>|human accept| knowledge
     automation(["automation"]) -->|fetch| feeds["feeds<br/>(quarantine)"]
     automation -->|build| artifacts["artifacts<br/>(derived)"]
+    feeds -.->|projection source| artifacts
+    knowledge -.->|projection source| artifacts
+
+    classDef anchor fill:#1f6feb,stroke:#1f6feb,color:#fff;
+    class knowledge anchor;
 ```
 
 *Each actor writes only into its own lane; low-trust input climbs to authoritative lanes only by passing a guarded transition (an agent's proposal needs a human `accept`).*
 
+The point of those lanes is to **build context you can trust**. Place each lane on two axes — how durable it is, and how much you can rely on it without review — and the value shows up as a climb: the high-trust corner (durable *and* authoritative = `knowledge`) is the one place nothing is *written* directly. It's *earned* by crossing the `accept` gate.
+
+```
+                       LOW TRUST                     HIGH TRUST
+                      (unreviewed)                (authoritative)
+              ┌──────────────────────────┬───────────────────────────────┐
+DURABLE       │  notebook                │  knowledge  ★ the goal        │
+(kept)        │  agent's working truth   │  canon — a human authors      │
+              │  durable, but low-trust  │  here · the context you ship  │
+              ├──────────────────────────┼───────────────────────────────┤
+TRANSIENT     │  feeds                   │  proposals  (queue)           │
+(staging)     │  raw external input,     │  a candidate, in review       │
+              │  unverified              │  ▲ climbs via human accept    │
+              └──────────────────────────┴───────────────────────────────┘
+                raw material ──── propose ────► a human accept lifts it to canon
+```
+
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — called a **zone** in the manifest and CLI, the term used everywhere technical from here on — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
 
 ```
@@ -66,10 +89,8 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 ## Try it
 
-- **5-command worked demo** — single terminal scroll, no MCP, no schemas: [`examples/hello/`](examples/hello/)
-- **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/agents-mcp.md`](docs/agents-mcp.md)
-- **Use textus as your own project's context store**: [`examples/project/`](examples/project/)
-- **Use textus to author a Claude plugin** (textus is the source-of-truth, build publishes to `agents/`, `skills/`, `commands/`): [`examples/claude-plugin/`](examples/claude-plugin/)
+- **Worked end-to-end store** — the role gate (propose → accept), build/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`examples/project/`](examples/project/)
+- **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md)
 
 ## Protocol, not just a gem
 
@@ -144,22 +165,22 @@ textus audit --limit=20              # query the audit log
 
 (All verbs return JSON envelopes by default; pass `--output=json` explicitly if you prefer.)
 
-For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
+For a worked store — knowledge entries, a staged proposal, schemas, a template, and a build that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
 
 ## What's shipped
 
 - **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; `publish_to:`/`publish_each:` byte-copy derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × zone-kind gate.** Writes carry `--as=<role>`; a role may write a zone iff it holds the capability the zone's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `quarantine`→`fetch`, `queue`→`propose`, `derived`→`build`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
-- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/agents-mcp.md](docs/agents-mcp.md))
-- **`textus doctor`.** 15 health checks across schemas, hooks, keys, sentinels, and the audit log.
+- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
+- **`textus doctor`.** Health checks across schemas, hooks, keys, sentinels, and the audit log.
 
 ## CLI and zones
 
 All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block).
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
+- Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.md).
 
 `textus boot` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
@@ -214,11 +235,11 @@ See SPEC.md §5.10 for the full hook contract.
 
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
-See [`docs/agents-mcp.md`](docs/agents-mcp.md) for the agent boot → pulse loop.
+See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot → pulse loop.
 
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_boot:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/project/`](examples/project/) — textus as a project's own context store (a fictional Rails service, `ledger`). Human-authored `knowledge/` (project facts, runbooks), a staged ADR in `proposals/` showing the agent-propose / human-accept loop, schemas validating each family, a mustache template plus a `:transform_rows` hook, and a `build` that publishes the `artifacts/orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
 
 ## Tests
 
@@ -226,7 +247,7 @@ See [`docs/agents-mcp.md`](docs/agents-mcp.md) for the agent boot → pulse loop
 bundle exec rspec
 ```
 
-~920 examples; includes conformance fixtures A–I from SPEC §12.
+Includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality
 
@@ -239,4 +260,4 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 
 ## License
 
-MIT.
+[MIT](LICENSE).

data/SPEC.md

@@ -632,7 +632,7 @@ Row transforms are RPC hooks on the `:transform_rows` event. See §5.10.
 
 ### 5.10 Hooks
 
-This section is the normative event table. For the hook-author's guide (how to define and test hooks), see [`docs/events.md`](docs/events.md).
+This section is the normative event table. For the hook-author's guide (how to define and test hooks), see [`docs/how-to/writing-hooks.md`](docs/how-to/writing-hooks.md).
 
 textus has a single hook registration verb: `Textus.hook { |reg| reg.on(event, name, **opts) { ... } }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path; the store-scoped loader drains the queued blocks and invokes each with its own registry.
 
@@ -896,11 +896,14 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `boot [--output=json]` | read | any |
 | `pulse [--since=N]` | read | any |
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
+| `propose K --stdin --as=R` | write | `propose`-holder (auto-prefixes propose_zone) |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `fetch KEY --as=automation` | write | `fetch`-holder (typically `automation`) |
 | `fetch stale [--prefix=K] [--zone=Z] [--as=automation]` | write | `fetch`-holder (typically `automation`) |
 | `build [--prefix=K] [--dry-run]` | write | `build`-holder (typically `automation`) |
+| `retain [--prefix=K] [--zone=Z] --as=ROLE` | write | per zone (role must write the matched zone) |
 | `accept K --as=human` | write | `author`-holder (typically `human`) |
+| `reject K --as=human` | write | `author`-holder (typically `human`) |
 | `init` | write | `human` |
 | `schema {show,init,diff,migrate}` | read/write | `human` for writes |
 | `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
@@ -930,11 +933,14 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
   "changed":        [ { "seq": 1843, "key": "knowledge.notes.x", "verb": "put", "role": "human", "ts": "..." } ],
   "stale":          [ "artifacts.marketplace" ],
   "pending_review": [ "proposals.proposal.123" ],
-  "doctor":         { "ok": true, "warn": 0, "fail": 0 }
+  "doctor":         { "ok": true, "warn": 0, "fail": 0 },
+  "manifest_etag":  "sha256:1f3a…",
+  "next_due_at":    "2026-06-01T09:00:00Z",
+  "hook_errors":    [ { "seq": 1844, "event": "after_put", "hook": "notify", "key": "knowledge.notes.x", "error_class": "Timeout::Error", "error_message": "…", "at": "..." } ]
 }
 ```
 
-`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `manifest_etag` is the `sha256:`-prefixed content hash of the manifest (ADR 0025), for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
 
 **`put` input** (read from stdin when `--stdin` is given):
 
@@ -997,7 +1003,7 @@ The reference Ruby gem follows semver independently and speaks `textus/3`.
 
 Agents interact with a textus store through two verbs: `boot` (once per session, for orientation) and `pulse` (per turn, for deltas). The `boot` envelope's `agent_quickstart` block gives the agent its starting cursor (`latest_seq`), its writable zones, and its propose zone. The `pulse` verb returns a delta envelope keyed on that cursor. When audit log rotation expires a cursor, `CursorExpired` signals the agent to call `boot` again.
 
-For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/agents-mcp.md`](docs/agents-mcp.md).
+For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md).
 
 ## 12. Conformance fixtures
 

data/lib/textus/boot.rb

@@ -71,32 +71,52 @@ module Textus
       },
     }.freeze
 
-    # The CLI verb catalog. Truth lives here; do not derive dynamically.
-    # Agents that read boot should see a stable shape regardless of how
-    # verb implementations evolve.
-    CLI_VERBS = [
-      { "name" => "boot",     "summary" => "this output — orientation for agents and tools" },
-      { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
-      { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
-      { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
-      { "name" => "schema",   "summary" => "field shape for a key family" },
-      { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
+    # Curated agent-facing verb catalog. For verbs that have a Dispatcher contract,
+    # the summary is derived from `contract.summary` at load time (ADR 0039). The
+    # editorial strings below are the fallback for CLI-only verbs without contracts.
+    # CLI_VERBS itself is assigned in textus.rb after Zeitwerk eager_load so that
+    # all contract-declaring files are loaded before derivation runs.
+    CURATED_CLI_VERBS = [
+      { "name" => "boot" },
+      { "name" => "list" },
+      { "name" => "get" },
+      { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
+      { "name" => "schema" },
+      { "name" => "put" },
+      { "name" => "propose" },
       { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
       { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
-      { "name" => "fetch", "summary" => "run an action for a quarantine entry" },
+      { "name" => "fetch" },
       { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
-      { "name" => "audit", "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
-      { "name" => "blame", "summary" => "audit rows for one key joined with git commit metadata" },
-      { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
-      { "name" => "doctor", "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
-      { "name" => "hook",
-        "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
-      { "name" => "pulse",
-        "summary" => "delta since cursor — changed entries, stale, pending proposals, doctor summary" },
+      { "name" => "audit",    "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
+      { "name" => "blame",    "summary" => "audit rows for one key joined with git commit metadata" },
+      { "name" => "rule",     "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
+      { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
+      { "name" => "hook",     "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "pulse" },
     ].freeze
 
+    # Build the CLI verb catalog by deriving each summary from the corresponding
+    # Dispatcher contract when one exists, falling back to the editorial string for
+    # CLI-only verbs without a contract (e.g. accept, build, where). Called once
+    # from textus.rb after eager_load so all contract files are present.
+    def self.build_cli_verbs
+      by_contract = Dispatcher::VERBS.values
+                                     .select { |k| k.respond_to?(:contract?) && k.contract? }
+                                     .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+
+      CURATED_CLI_VERBS.map do |entry|
+        derived = by_contract[entry["name"]]
+        if derived
+          entry.merge("summary" => derived)
+        else
+          entry
+        end
+      end
+    end
+
     def self.agent_quickstart(manifest, audit_log)
       agent_role = manifest.policy.proposer_role
 
@@ -158,7 +178,7 @@ module Textus
         "recipes" => recipes(manifest),
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
-                       "default 'human'",
+                       "then a transport default ('human' for CLI, 'agent' for MCP)",
           "roles" => manifest.data.role_caps.keys,
           "ref" => "SPEC.md §5",
         },
@@ -177,7 +197,7 @@ module Textus
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-        "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
+        "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
       }
     end
 

data/lib/textus/cli/verb/mcp_serve.rb

@@ -1,14 +1,19 @@
 module Textus
   class CLI
     class Verb
-      # Launches the MCP stdio server in the current process. Blocks on
-      # stdin; never returns until stdin closes.
+      # Launches the MCP stdio server in the current process. Blocks on stdin;
+      # never returns until stdin closes. The connection acts as the `agent`
+      # role by default (ADR 0040): the agent channel proposes, it does not
+      # inherit the human's authority. Override per connection with --as, or
+      # TEXTUS_ROLE / .textus/role (same chain as every other verb).
       class MCPServe < Verb
         command_name "serve"
         parent_group Group::MCP
+        option :as_flag, "--as=ROLE"
 
         def call(store)
-          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout).run
+          role = resolved_role(store, default: Textus::Role::AGENT)
+          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
           0
         end
       end

data/lib/textus/cli/verb/propose.rb

@@ -0,0 +1,28 @@
+module Textus
+  class CLI
+    class Verb
+      # Queue a proposal. Mirrors the MCP `propose` tool: resolves the
+      # manifest's propose_zone and prefixes the key, so the author does not
+      # need to know the queue zone's name. ADR 0036.
+      class Propose < Verb
+        command_name "propose"
+
+        option :as_flag, "--as=ROLE"
+        option :use_stdin, "--stdin"
+
+        def call(store)
+          rel = positional.shift or raise UsageError.new("propose requires a key")
+          raise UsageError.new("propose requires --stdin") unless use_stdin
+
+          payload = JSON.parse(@stdin.read)
+          env = store.as(resolved_role(store)).propose(
+            rel,
+            meta: payload["_meta"] || {},
+            body: payload["body"] || "",
+          )
+          emit(env.to_h_for_wire)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/pulse.rb

@@ -4,12 +4,21 @@ module Textus
       class Pulse < Verb
         command_name "pulse"
 
+        option :as_flag, "--as=ROLE"
         option :since, "--since=N"
 
         def call(store)
-          ops = session_for(store)
-          since_n = (since || "0").to_i
-          emit(ops.pulse(since: since_n))
+          role = resolved_role(store)
+          ops = store.as(role)
+
+          if since
+            emit(ops.pulse(since: since.to_i))
+          else
+            cursors = Textus::CursorStore.new(root: store.root, role: role)
+            result = ops.pulse(since: cursors.read)
+            cursors.write(result["cursor"])
+            emit(result)
+          end
         end
       end
     end

data/lib/textus/cli/verb/schema.rb

@@ -7,7 +7,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("schema requires a key")
-          emit(session_for(store).schema_envelope(key))
+          emit(session_for(store).schema(key))
         end
       end
     end

data/lib/textus/cli/verb.rb

@@ -91,9 +91,10 @@ module Textus
 
       # Resolves the active role for this invocation. Honors the verb's
       # `--as` flag if declared, then TEXTUS_ROLE, then the project default.
-      def resolved_role(store)
+      # Pass `default:` to override the fallback (e.g. MCPServe uses AGENT).
+      def resolved_role(store, default: Role::DEFAULT)
         flag = respond_to?(:as_flag) ? as_flag : nil
-        Role.resolve(flag: flag, env: ENV, root: store.root)
+        Role.resolve(flag: flag, env: ENV, root: store.root, default: default)
       end
 
       # Returns a Call value bound to the resolved role. Convenience for

data/lib/textus/contract.rb

@@ -0,0 +1,106 @@
+module Textus
+  # Declarative, co-located interface contract for a verb. One source of truth
+  # for the agent-facing summary, the argument schema, which transports expose
+  # the verb, and how the return value is shaped for the wire. CLI/Ruby/MCP and
+  # boot project from this; the MCP catalog is fully derived from it (ADR 0039).
+  module Contract
+    # One argument of a verb. `positional: true` means it is passed to the
+    # use-case as a positional (e.g. `get(key)`); otherwise as a keyword.
+    # `session_default` names a zero-arg method on `Textus::Session` (Symbol)
+    # that supplies the value when the wire arg is absent; `nil` means no default.
+    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description)
+
+    JSON_TYPES = {
+      String => "string", Integer => "integer", Hash => "object",
+      Array => "array", :boolean => "boolean"
+    }.freeze
+
+    def self.json_type(type)
+      JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
+    end
+
+    Spec = Data.define(:verb, :summary, :args, :surfaces, :response) do
+      def mcp? = surfaces.include?(:mcp)
+
+      def required_args = args.select(&:required)
+
+      # JSON-Schema object for MCP tools/list inputSchema.
+      # Outer keys (:type, :properties, :required) are symbols; inner property
+      # keys are strings — matches the MCP/JSON wire shape expected by clients.
+      def input_schema
+        props = args.to_h do |a|
+          h = { "type" => Contract.json_type(a.type) }
+          h["description"] = a.description if a.description
+          [a.name.to_s, h]
+        end
+        { type: "object", properties: props, required: required_args.map { |a| a.name.to_s } }
+      end
+    end
+
+    # Mixed onto a use-case class via `extend`. Calls accumulate into ivars,
+    # frozen into a Spec on first read of `.contract`.
+    module DSL
+      def verb(name = nil)
+        if name
+          raise "contract already built; declare verb before reading .contract" if defined?(@__contract) && @__contract
+
+          @__verb = name
+        else
+          @__verb
+        end
+      end
+
+      def summary(text = nil)
+        if text
+          raise "contract already built; declare summary before reading .contract" if defined?(@__contract) && @__contract
+
+          @__summary = text
+        else
+          @__summary
+        end
+      end
+
+      def surfaces(*list)
+        if list.empty?
+          @__surfaces ||= []
+        else
+          raise "contract already built; declare surfaces before reading .contract" if defined?(@__contract) && @__contract
+
+          @__surfaces = list
+        end
+      end
+
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil)
+        raise "contract already built; declare args before reading .contract" if defined?(@__contract) && @__contract
+
+        (@__args ||= []) << Arg.new(
+          name: name, type: type, required: required,
+          positional: positional, session_default: session_default, description: description
+        )
+      end
+
+      def response(&blk)
+        @__response = blk if blk
+        @__response || ->(v) { v }
+      end
+
+      def contract?
+        !@__verb.nil?
+      end
+
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      # @__contract uses double-underscore to match the other accumulator ivars
+      # (@__verb, @__args, etc.) and avoid name collision with user-defined `@contract`.
+      def contract
+        @__contract ||= Spec.new(
+          verb: @__verb,
+          summary: @__summary,
+          args: (@__args || []).freeze,
+          surfaces: (@__surfaces || []).freeze,
+          response: response,
+        )
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+  end
+end