textus 0.43.0 → 0.43.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c2c92f27b720b90f0dfa268174cf9d9ea775b37f92bb38ed90cd9719d7b2626
-  data.tar.gz: f5018ecfd8d72666d48236d42395e44819766659088bc98b1c69ad4fccf2fce8
+  metadata.gz: d352b5ae1e1274a454c6488497c8bad60659b9c4f70ceb86da822f883b1559c5
+  data.tar.gz: fca73540d82d4a0e7ae9d527bdae43451c8a13a89f0da486e049232754a6b6d4
 SHA512:
-  metadata.gz: 758b3a9da98edb000100e9b6d1665829d94333f53e38f3a68104d33a4aefd831947e235ecb3048e16b388e0256239dfe6f66708d1253b7bfcbb56360a74350bc
-  data.tar.gz: d72be31709261f1aff37f00a9b213e03d8121758f61e781bfdd1626eb16122d994d64491f4c37be4c851031e8bd122d9df8d8abd682228e2693162d3861c865d
+  metadata.gz: 7559e8f9b1c49a2ddbf0a3bf83c5653fa951f3f575a53113274a3b1f857fabfb709649720d6137963f9b411aa87b1178f296ae4a9f907963250920e28a77880e
+  data.tar.gz: 60dea75e32ccdae818a6da8a4303ff7e14fd248e4230e0b7f54af45c24ea9539eaf0103707820e006e1e0ed925c030179b8e3483eb889a5120eb67afd030e9f7

data/CHANGELOG.md

@@ -9,6 +9,35 @@ 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.43.2 — 2026-06-02 — Agent-legible MCP contracts ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md))
+
+No `textus/3` wire-format change. One breaking (pre-1.0) change on the MCP transport — `put`/`propose` take frontmatter under `_meta` (was `meta`) — plus per-argument descriptions on every MCP tool and a fully catalog-derived agent verb surface.
+
+### Changed
+
+- **BREAKING (pre-1.0): MCP `put`/`propose` take frontmatter under `_meta`, not `meta` ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** Every *read* returns the envelope under `_meta` (`get`, SPEC §8), and the CLI `--stdin` envelope already speaks `_meta` — only the MCP `put`/`propose` argument diverged as `meta`, breaking the natural read → edit → write round-trip. The contract gains a `wire_name` primitive so the wire speaks `_meta` while the use-case keeps its `meta:` kwarg (the ADR 0039 signature guard still reconciles). An MCP client that hardcoded the `meta` argument renames one key. The Ruby API (`store.put(meta:)`) and the CLI `--stdin` envelope are unchanged.
+- **`boot.agent_quickstart.write_verbs` derives from the MCP catalog ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** It now returns bare verb names (`put propose fetch fetch_all`) like `read_verbs`, instead of the CLI string `"put KEY --as=agent --stdin"` (`--as`/`--stdin` are meaningless on an MCP connection — role is connection-resolved, ADR 0040). Closes the de-CLI follow-up named in ADR 0056; a symmetric guard spec fails the build if a CLI string creeps back.
+
+### Added
+
+- **Per-argument descriptions on every MCP tool ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** All MCP-surfaced verb arguments now carry a one-line `description:` in their `tools/list` `inputSchema` (was 2 of ~30) — including `put`'s `body`/`content` mutual-exclusivity and the maintenance `dry_run` "default false applies immediately" gotcha. They ship once in `tools/list` at no per-call cost, so an agent can form a valid call from the schema alone.
+
+## 0.43.1 — 2026-06-02 — `boot` agent surface derives from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md))
+
+No `textus/3` wire-format change — `boot`'s agent-orientation fields are corrected to match the verbs an MCP agent can actually call.
+
+### Fixed
+
+- **`boot.agent_quickstart.read_verbs` had drifted from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** It was a hand-maintained list that advertised CLI-only read verbs an MCP agent cannot call (`audit`, `freshness`, `doctor`) while omitting the ones it can and needs (`schema`, `rules`). It now **derives** from `MCP::Catalog` (`get list pulse schema boot rules`) and is reconciled by a guard spec, so it can no longer advertise an uncallable verb or omit a callable one. This is what led downstream skills to shell out to a CLI for schema discovery instead of calling the `schema` verb.
+
+### Changed
+
+- **`boot.agent_protocol.recipes` reference verbs, not CLI strings ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** Each recipe step names a verb (`get KEY`, `schema KEY`, `put KEY`, `propose KEY`, `fetch_all`) or a plain build step, instead of a `textus …` / `echo … | textus …` shell line — each transport frames the verb itself (CLI vs MCP tool). Keeps shell syntax out of the surface an MCP agent reads. `human_steps` still name `accept` (the author-only transition, not an MCP tool, by design).
+
+### Added
+
+- **ADR 0054 (Proposed, no implementation): entry-level `desc`.** Records the decision to add an optional one-line `desc:` to manifest entries — surfaced in `boot.entries`/`list` — turning the manifest into a navigable index so an agent finds the right data without a caller hardcoding the key. Pre-registers ADR 0055 (a `find`/search verb) as the evidence-triggered follow-up. Documentation only in this release.
+
 ## 0.43.0 — 2026-06-02 — Typed `publish:` block + remove `index_filename` ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md), [0053](docs/architecture/decisions/0053-remove-index-filename.md))
 
 No `textus/3` wire-format change. Two breaking (pre-1.0) changes on the publish/enumeration surface: the two top-level publish keys become one typed `publish:` block, and the unused `index_filename:` enumeration feature is removed. Both fail at load with a migration-pointing message.

data/SPEC.md

@@ -197,14 +197,14 @@ entries:
     path: knowledge/network/org
     zone: knowledge
     schema: person
-    owner: textus:network
+    owner: human:network
     nested: true
 
   - key: artifacts.catalogs.people
     path: artifacts/catalogs/people.md
     zone: artifacts
     schema: null
-    owner: textus:build
+    owner: automation:build
 
 rules:
   - match: feeds.**
@@ -404,7 +404,7 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 - key: output.catalogs.skills
   path: output/catalogs/skills.md
   zone: output
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; external automation invokes it
@@ -800,7 +800,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "protocol": "textus/3",
   "key": "knowledge.network.org.jane",
   "zone": "knowledge",
-  "owner": "textus:network",
+  "owner": "human:network",
   "path": "/absolute/path/to/.textus/zones/knowledge/network/org/jane.md",
   "format": "markdown",
   "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
@@ -898,7 +898,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 ```json
 {
   "agent_quickstart": {
-    "read_verbs":     ["boot", "get", "list", "audit", "pulse", "freshness", "doctor"],
+    "read_verbs":     ["get", "list", "pulse", "schema", "boot", "rules"],
     "write_verbs":    ["put KEY --as=agent --stdin"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
@@ -907,6 +907,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 }
 ```
 
+`read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema` for an entry's field shape, `rules` for its freshness/guard policy) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema` verb before a `put`/`propose`, not by shelling out to a CLI.
+
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
 **`textus pulse` output shape:**

data/docs/architecture/README.md

@@ -1,7 +1,7 @@
 # Textus architecture
 
 > **Explanation** · for contributors · **read this first** for orientation before SPEC
-> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-05 (v0.35)
+> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-06 (v0.43)
 
 ```mermaid
 flowchart TD

data/docs/reference/conventions.md

@@ -1,7 +1,7 @@
 # Conventions
 
 > **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
-> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.35)
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-06 (v0.43)
 
 Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../../SPEC.md`](../../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
 
@@ -39,11 +39,11 @@ Inside `knowledge/`, group by **domain** (identity, people, projects, decisions,
 
 ## Owner strings
 
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
+The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*. The form is `<archetype>` or `<archetype>:<subject>`; the archetype must be one of `human`, `agent`, `automation` (validated at load — ADR 0045), and the subject is free-form:
 
-- `textus:network` — humans curate
+- `human:network` — humans curate
 - `agent:planner` — a specific named agent
-- `build:catalog-skills` — a specific build job
+- `automation:catalog-skills` — a specific build job
 
 Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
 
@@ -58,7 +58,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
   path: artifacts/catalogs/people.md
   zone: artifacts
   schema: null
-  owner: build:catalog-people
+  owner: automation:catalog-people
   compute:
     kind: projection
     select: knowledge.network.org   # prefix or list of prefixes
@@ -75,7 +75,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
 - key: artifacts.catalogs.skills
   path: artifacts/catalogs/skills.md
   zone: artifacts
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; the automation invokes it
@@ -106,7 +106,7 @@ rules:
 A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
 
 ```sh
-textus fetch stale --zone=intake --as=automation   # in cron / CI
+textus fetch stale --zone=feeds --as=automation   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
@@ -137,7 +137,7 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
 
 - **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
+- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
 - **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
 The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.

data/lib/textus/boot.rb

@@ -127,14 +127,25 @@ module Textus
       propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
-        "read_verbs" => %w[boot get list audit pulse freshness doctor],
-        "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        # Both verb lists derive from the MCP catalog (ADR 0056, ADR 0057): the
+        # agent's real read and write surface, named as verbs the agent calls —
+        # not CLI strings. read_verbs can neither advertise a verb the agent
+        # cannot call (audit/freshness/doctor are CLI-only) nor omit one it can
+        # (schema/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
+        # framing (role is connection-resolved over MCP; there is no stdin).
+        # writable_zones / propose_zone below carry the agent's write authority.
+        "read_verbs" => Textus::MCP::Catalog.read_verbs,
+        "write_verbs" => agent_role ? Textus::MCP::Catalog.write_verbs : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
         "latest_seq" => audit_log.latest_seq,
       }
     end
 
+    # Recipes reference verbs, not a transport's CLI strings (ADR 0056): every
+    # step names a verb the agent can call (each transport frames it — CLI as
+    # `textus get KEY`, MCP as the `get` tool) or is a plain build step. This
+    # keeps shell lines out of the surface an MCP agent reads.
     def self.recipes(manifest)
       queue = manifest.policy.queue_zone
       feeds = zone_label(manifest, :quarantine, "the quarantine zone")
@@ -142,32 +153,32 @@ module Textus
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
-            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
-            "textus get KEY                            # returns envelope JSON",
+            "list (zone:, prefix:) — discover keys without reading bodies",
+            "get KEY — returns the entry envelope",
           ],
         },
         "write" => {
           "purpose" => "create or update an entry",
           "steps" => [
-            "textus schema get FAMILY                  # learn the _meta field shape",
-            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
-            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
+            "schema KEY — learn the _meta field shape (required, optional, field types) before writing",
+            "assemble an envelope: { _meta: {…}, body: \"…\" }",
+            "put KEY — persist it (role-gated); pass if_etag to guard a concurrent edit",
           ],
         },
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "echo ENVELOPE | textus put #{queue}.KEY --as=agent --stdin",
+            "propose KEY — writes the change into the #{queue} zone for review",
           ],
           "human_steps" => [
-            "textus accept #{queue}.KEY --as=human       # promotes the proposal to its target zone",
+            "accept #{queue}.KEY — promotes the proposal into its target zone",
           ],
         },
         "fetch" => {
-          "purpose" => "rebuild stale quarantine-zone caches from their declared actions",
+          "purpose" => "refresh stale quarantine-zone caches from their declared intake",
           "steps" => [
-            "textus freshness --zone=#{feeds}            # report fresh/stale per entry",
-            "textus fetch stale --zone=#{feeds} --as=automation",
+            "pulse — its `stale` list names entries past their ttl",
+            "fetch_all (zone: #{feeds}) — re-pull the stale entries",
           ],
         },
       }

data/lib/textus/contract.rb

@@ -8,7 +8,14 @@ module Textus
     # 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)
+    # `wire_name` is the name the arg carries on the wire (MCP JSON property / CLI
+    # envelope key) when it must differ from the use-case kwarg `name` — e.g. `put`
+    # takes the `meta:` kwarg but exposes `_meta` on the wire to match what `get`
+    # returns and what the CLI `--stdin` envelope already speaks (ADR 0057).
+    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description, :wire_name) do
+      # The name used on the wire (defaults to the kwarg name).
+      def wire = wire_name || name
+    end
 
     JSON_TYPES = {
       String => "string", Integer => "integer", Hash => "object",
@@ -31,9 +38,9 @@ module Textus
         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]
+          [a.wire.to_s, h]
         end
-        { type: "object", properties: props, required: required_args.map { |a| a.name.to_s } }
+        { type: "object", properties: props, required: required_args.map { |a| a.wire.to_s } }
       end
     end
 
@@ -70,12 +77,13 @@ module Textus
         end
       end
 
-      def arg(name, type, required: false, positional: false, session_default: nil, description: nil)
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil) # rubocop:disable Metrics/ParameterLists
         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
+          positional: positional, session_default: session_default,
+          description: description, wire_name: wire_name
         )
       end
 

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -7,8 +7,8 @@ module Textus
       verb     :key_delete_prefix
       summary  "Bulk-delete every leaf key under prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix,  String, required: true
-      arg :dry_run, :boolean
+      arg :prefix,  String, required: true, description: "every leaf key under this dotted prefix is deleted"
+      arg :dry_run, :boolean, description: "true returns the Plan without writing; default false applies the delete immediately"
       response(&:to_h)
 
       def initialize(container:, call:)

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -8,9 +8,9 @@ module Textus
       verb     :key_mv_prefix
       summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
       surfaces :cli, :ruby, :mcp
-      arg :from_prefix, String, required: true
-      arg :to_prefix,   String, required: true
-      arg :dry_run,     :boolean
+      arg :from_prefix, String, required: true, description: "dotted prefix whose leaf keys are renamed"
+      arg :to_prefix,   String, required: true, description: "dotted prefix the keys are renamed to"
+      arg :dry_run,     :boolean, description: "true returns the Plan without writing; default false applies the rename immediately"
       response(&:to_h)
 
       def initialize(container:, call:)

data/lib/textus/maintenance/migrate.rb

@@ -10,8 +10,9 @@ module Textus
       verb     :migrate
       summary  "Run a YAML migration plan (multi-op)."
       surfaces :cli, :ruby, :mcp
-      arg :plan_yaml, String, required: true
-      arg :dry_run,   :boolean
+      arg :plan_yaml, String, required: true,
+                              description: "YAML listing the migration ops (zone_mv, key_mv_prefix, key_delete_prefix) run in order"
+      arg :dry_run,   :boolean, description: "true returns the combined plan without writing; default false applies every op immediately"
       response(&:to_h)
 
       def initialize(container:, call:)

data/lib/textus/maintenance/rule_lint.rb

@@ -11,7 +11,8 @@ module Textus
       verb     :rule_lint
       summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
       surfaces :cli, :ruby, :mcp
-      arg :candidate_yaml, String, required: true
+      arg :candidate_yaml, String, required: true,
+                                   description: "manifest YAML; its `rules:` block is diffed against the live manifest (no writes)"
       response(&:to_h)
 
       def initialize(container:, call:)

data/lib/textus/maintenance/zone_mv.rb

@@ -11,9 +11,9 @@ module Textus
       verb     :zone_mv
       summary  "Rename a zone — manifest + files. Refuses if destination exists."
       surfaces :cli, :ruby, :mcp
-      arg :from,    String, required: true
-      arg :to,      String, required: true
-      arg :dry_run, :boolean
+      arg :from,    String, required: true, description: "current zone name"
+      arg :to,      String, required: true, description: "new zone name; refused if a zone by this name already exists"
+      arg :dry_run, :boolean, description: "true returns the plan without writing; default false applies the rename immediately"
       response(&:to_h)
 
       def initialize(container:, call:)

data/lib/textus/mcp/catalog.rb

@@ -11,7 +11,7 @@ module Textus
       # Contracts of every MCP-surfaced verb, in Dispatcher order.
       def specs
         Textus::Dispatcher::VERBS.values
-                                 .select { |k| k.respond_to?(:contract?) && k.contract? && k.contract.mcp? }
+                                 .select { |k| mcp_surfaced?(k) }
                                  .map(&:contract)
       end
 
@@ -25,9 +25,34 @@ module Textus
         specs.map { |s| s.verb.to_s }
       end
 
+      # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
+      # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
+      # from this so it can never advertise a verb the agent cannot call, nor
+      # omit one it can (ADR 0056). Excludes Write/Maintenance.
+      def read_verbs
+        Textus::Dispatcher::VERBS
+          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Read::") }
+          .keys.map(&:to_s)
+      end
+
+      # MCP-surfaced write verbs, by Dispatcher class namespace — the mirror of
+      # read_verbs for the write side. `boot.agent_quickstart.write_verbs` derives
+      # from this so it advertises bare verb names the agent can call (no `--as`/
+      # `--stdin` CLI framing), finishing the de-CLI-ing of the agent surface
+      # (ADR 0056, ADR 0057).
+      def write_verbs
+        Textus::Dispatcher::VERBS
+          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Write::") }
+          .keys.map(&:to_s)
+      end
+
+      def mcp_surfaced?(klass)
+        klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+      end
+
       def call(name, session:, store:, args:)
         klass = Textus::Dispatcher::VERBS[name.to_sym]
-        raise ToolError.new("unknown tool: #{name}") unless klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+        raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
 
         spec = klass.contract
         pos, kw = map_args(spec, args || {}, session)
@@ -45,14 +70,14 @@ module Textus
       # the session when absent from the wire; they are never treated as missing.
       # Positional args are emitted in contract declaration order; use-case signatures must match.
       def map_args(spec, raw, session = nil)
-        missing = spec.required_args.map { |a| a.name.to_s } - raw.keys
+        missing = spec.required_args.map { |a| a.wire.to_s } - raw.keys
         raise ToolError.new("#{spec.verb}: missing #{missing.join(", ")}") unless missing.empty?
 
         positional = []
         keyword = {}
         spec.args.each do |a|
-          if raw.key?(a.name.to_s)
-            value = raw[a.name.to_s]
+          if raw.key?(a.wire.to_s)
+            value = raw[a.wire.to_s]
           elsif a.session_default && session
             value = session.public_send(a.session_default)
           else

data/lib/textus/read/get.rb

@@ -11,7 +11,8 @@ module Textus
       verb     :get
       summary  "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness)."
       surfaces :cli, :ruby, :mcp
-      arg :key, String, required: true, positional: true
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to read, e.g. 'knowledge.project'"
       response(&:to_h_for_wire)
 
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)

data/lib/textus/read/list.rb

@@ -6,8 +6,8 @@ module Textus
       verb     :list
       summary  "List keys filtered by zone and/or prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix, String
-      arg :zone,   String
+      arg :prefix, String, description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.runbooks'"
+      arg :zone,   String, description: "restrict to one zone by name (see `boot` zones); combine with prefix to narrow further"
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest

data/lib/textus/read/rules.rb

@@ -9,7 +9,8 @@ module Textus
       verb     :rules
       summary  "Return effective rules for a key (fetch, guard, ...)."
       surfaces :ruby, :mcp
-      arg :key, String, required: true, positional: true
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose effective rules you want (fetch ttl/action, write guard, ...)"
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest

data/lib/textus/read/schema_envelope.rb

@@ -6,7 +6,8 @@ module Textus
       verb     :schema
       summary  "Return the schema (field shape) for an entry's family, by key."
       surfaces :ruby, :mcp
-      arg :key, String, required: true, positional: true
+      arg :key, String, required: true, positional: true,
+                        description: "any key in the family whose schema you want; returns required/optional fields and their types"
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.43.0"
+  VERSION = "0.43.2"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/fetch_all.rb

@@ -6,8 +6,8 @@ module Textus
       verb     :fetch_all
       summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix, String
-      arg :zone,   String
+      arg :prefix, String, description: "only refresh stale entries whose key starts with this dotted prefix"
+      arg :zone,   String, description: "only refresh stale entries in this quarantine zone (see `pulse` stale list)"
 
       def initialize(container:, call:)
         @container    = container

data/lib/textus/write/fetch_worker.rb

@@ -8,7 +8,8 @@ module Textus
       verb     :fetch
       summary  "Run a fetch action for one quarantine entry."
       surfaces :cli, :ruby, :mcp
-      arg :key, String, required: true, positional: true
+      arg :key, String, required: true, positional: true,
+                        description: "quarantine-zone entry key to refresh using its declared intake action"
       response { |outcome| { "outcome" => outcome.class.name.split("::").last.downcase } }
 
       FETCH_TIMEOUT_SECONDS = IntakeFetch::FETCH_TIMEOUT_SECONDS

data/lib/textus/write/propose.rb

@@ -12,9 +12,12 @@ module Textus
       surfaces :cli, :ruby, :mcp
       arg :key,     String, required: true, positional: true,
                             description: "key relative to propose_zone, e.g. 'decisions.feature-x'"
-      arg :meta,    Hash,   required: true
-      arg :body,    String
-      arg :content, Hash
+      arg :meta,    Hash,   required: true, wire_name: :_meta,
+                            description: "frontmatter; reads back as `_meta` from `get`. Include a 'proposal:' block naming the target_key"
+      arg :body,    String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
       response { |env| { "uid" => env.uid, "etag" => env.etag, "key" => env.key } }
 
       def initialize(container:, call:)

data/lib/textus/write/put.rb

@@ -6,11 +6,16 @@ module Textus
       verb     :put
       summary  "Create or update an entry. Schema-validated. Returns {uid, etag}."
       surfaces :cli, :ruby, :mcp
-      arg :key,     String, required: true, positional: true
-      arg :meta,    Hash, required: true
-      arg :body,    String
-      arg :content, Hash
-      arg :if_etag, String
+      arg :key,     String, required: true, positional: true,
+                            description: "dotted entry key, e.g. 'knowledge.project'; must resolve to a zone the role may write"
+      arg :meta,    Hash, required: true, wire_name: :_meta,
+                          description: "frontmatter; reads back as `_meta` from `get`. Schema-validated — call `schema KEY` first"
+      arg :body,    String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the write is rejected if the entry changed since"
       response { |env| { "uid" => env.uid, "etag" => env.etag } }
 
       def initialize(container:, call:)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.43.0
+  version: 0.43.2
 platform: ruby
 authors:
 - Patrick