textus 0.43.1 → 0.43.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c26661afb6c59f813ccdb737e56666be242a14e3315a100348dd8514a41e78a
-  data.tar.gz: 26ff3e7e8cd94a545cdcabe964c6e8c7311fe0179a24a13b0ab298eab7f2bf34
+  metadata.gz: d352b5ae1e1274a454c6488497c8bad60659b9c4f70ceb86da822f883b1559c5
+  data.tar.gz: fca73540d82d4a0e7ae9d527bdae43451c8a13a89f0da486e049232754a6b6d4
 SHA512:
-  metadata.gz: db6b8047ba7d7c79ad78a653944709d7cc7cfd5c22a4baae116e97c8d6fea48c409788c835e1c1f83c7684a58da089b08a0525a44791de92875d1d2bb0c26a76
-  data.tar.gz: 26e9d74398110f4d34dd59c837901170e5d80a847268f5edee45010f4793c51e1f47737d5d3c85b0098fa06b1334e00bf1038330a12a1061c9957d045e07638c
+  metadata.gz: 7559e8f9b1c49a2ddbf0a3bf83c5653fa951f3f575a53113274a3b1f857fabfb709649720d6137963f9b411aa87b1178f296ae4a9f907963250920e28a77880e
+  data.tar.gz: 60dea75e32ccdae818a6da8a4303ff7e14fd248e4230e0b7f54af45c24ea9539eaf0103707820e006e1e0ed925c030179b8e3483eb889a5120eb67afd030e9f7

data/CHANGELOG.md

@@ -9,6 +9,19 @@ 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.

data/lib/textus/boot.rb

@@ -127,11 +127,15 @@ module Textus
       propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
-        # Derived from the MCP catalog (ADR 0056): the agent's real read surface,
-        # so the quickstart can neither advertise a verb the agent cannot call
-        # (audit/freshness/doctor are CLI-only) nor omit one it can (schema/rules).
+        # 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 ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        "write_verbs" => agent_role ? Textus::MCP::Catalog.write_verbs : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
         "latest_seq" => audit_log.latest_seq,

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

@@ -35,6 +35,17 @@ module Textus
           .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
@@ -59,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.1"
+  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.1
+  version: 0.43.2
 platform: ruby
 authors:
 - Patrick