textus 0.30.0 → 0.38.0

data/docs/conventions.md

@@ -1,6 +1,9 @@
 # Conventions
 
-Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build runners. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
+> **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)
+
+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*.
 
 ## Key naming
 
@@ -18,14 +21,14 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   manifest.yaml
   schemas/        # YAML schema definitions
   zones/
-    identity/     # identity, voice, slow-changing facts — humans only
-    working/      # agent-writable working memory
-    intake/       # runner-fed external inputs
-    review/       # AI proposals awaiting accept
-    output/       # generated by build runners — never edit by hand
+    knowledge/    # authored truth: identity, voice, decisions — author-holders write
+    notebook/     # agent's own durable lane (workspace) — keep-holders write
+    feeds/        # automation-fed external inputs (fetch)
+    proposals/    # AI proposals awaiting accept (propose)
+    artifacts/    # generated by build automation — never edit by hand
 ```
 
-Inside `working/`, group by **domain** (people, projects, decisions, runbooks), not by file type or date. Inside `output/`, group by **producer** (`output/catalogs/`, `output/indexes/`) so it's clear which build job owns what.
+Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
 
 ## Schema design
 
@@ -46,75 +49,77 @@ Tooling around `git blame` or audit logs may filter on owner; the gem itself onl
 
 ## Derived entries
 
-textus supports two shapes for derived entries:
+A derived entry declares a `compute:` block with a `kind:` discriminator. Two kinds:
 
-**`projection:`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
+**`compute: { kind: projection }`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
 
 ```yaml
-- key: output.catalogs.people
-  path: output/catalogs/people.md
-  zone: output
+- key: artifacts.catalogs.people
+  path: artifacts/catalogs/people.md
+  zone: artifacts
   schema: null
   owner: build:catalog-people
-  projection:
-    select: working.network.org   # prefix or list of prefixes
+  compute:
+    kind: projection
+    select: knowledge.network.org   # prefix or list of prefixes
     pluck:  [name, relationship, org]
     sort_by: name
-  template: people.mustache       # under .textus/templates/
-  publish_to: [docs/people.md]    # optional repo-relative byte-copy targets
+  template: people.mustache         # under .textus/templates/
+  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
 ```
 
-**`generator:`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`.
+**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
 
 ```yaml
-- key: output.catalogs.skills
-  path: output/catalogs/skills.md
-  zone: output
+- key: artifacts.catalogs.skills
+  path: artifacts/catalogs/skills.md
+  zone: artifacts
   owner: build:catalog-skills
-  generator:
-    command: "rake catalog:skills"   # informational; the runner invokes it
-    sources: [working.projects, working.network]
+  compute:
+    kind: external
+    command: "rake catalog:skills"   # informational; the automation invokes it
+    sources: [knowledge.projects, knowledge.network]
 ```
 
-The build runner is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `generator.sources` — same list, recorded twice so a diff proves what was consumed.
+The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `compute.sources` — same list, recorded twice so a diff proves what was consumed.
 
-Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md). Reducers (`projection.reduce:`) and per-leaf publishing (`publish_each:`) are also covered there.
+Full contract for both shapes is in [`../SPEC.md` §5.2.1 and §5.2.2](../SPEC.md). Transforms (`compute.transform:`) and per-leaf publishing (`publish_each:`) are also covered there.
 
 ## Intake and freshness
 
-External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; refresh is on demand:
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
 
 ```sh
-textus refresh intake.notion.roadmap --as=runner
-textus refresh-stale --zone=intake --as=runner   # everything past its TTL
+textus fetch feeds.notion.roadmap --as=automation
+textus fetch stale --zone=feeds --as=automation   # everything past its TTL
 ```
 
 Freshness budgets live in the top-level `rules:` block, matched by glob:
 
 ```yaml
 rules:
-  - match: intake.notion.**
-    refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
+  - match: feeds.notion.**
+    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
-A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
+A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
 
 ```sh
-textus refresh-stale --zone=intake --as=runner   # in cron / CI
+textus fetch stale --zone=intake --as=automation   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
 
-### Read vs. refresh
+### Read vs. fetch
 
 There are two read operations, and the difference matters in custom code:
 
-| Operation | Triggers refresh? | Use for |
-|-----------|-------------------|---------|
+| Operation | Triggers fetch? | Use for |
+|-----------|-----------------|---------|
 | `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
 
-Build always uses the pure path; injecting refresh into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_refresh` only when you genuinely want side effects on read.
+Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
 
 ## Body content
 

data/lib/textus/boot.rb

@@ -8,46 +8,56 @@ module Textus
   module Boot
     PROTOCOL_ID = PROTOCOL
 
-    # Conventional zone purposes. Unknown zones (declared in the manifest
-    # but not listed here) get no `purpose` field.
-    ZONE_PURPOSES = {
-      "identity" => "slow-changing identity; human-only writes",
-      "working" => "active project state; humans, AI, and scripts share this surface",
-      "intake" => "declared external inputs; script-refreshed via actions",
-      "review" => "AI proposals awaiting human accept",
-      "output" => "build-computed outputs; never hand-edited",
-    }.freeze
-
-    # Per-kind write-flow templates. Each lambda receives the user-facing role
-    # name and returns a guidance string for that role. Roles whose kind has
-    # no template (e.g. unknown future kinds) are omitted from write_flows.
+    # Per-capability write-flow templates. Each lambda receives the user-facing
+    # role name and the manifest, and returns guidance for that verb with the
+    # live zone named by kind (ADR 0034). A role holding multiple verbs gets one
+    # joined string; roles whose verbs have no template are omitted.
     WRITE_FLOW_TEMPLATES = {
-      accept_authority: lambda do |name, _manifest|
-        "edit files in identity/working zones, then 'textus put KEY --as=#{name}'"
+      author: lambda do |name, manifest|
+        "edit files in #{zone_label(manifest, :canon, "your canon zone")}, " \
+          "then 'textus put KEY --as=#{name}'"
       end,
-      proposer: lambda do |name, manifest|
-        authority = manifest.policy.roles_with_kind(:accept_authority).first || "accept_authority"
-        "propose changes by writing review.* entries with --as=#{name} and a 'proposal:' frontmatter block; " \
-          "the #{authority} role runs 'textus accept' to apply"
+      keep: lambda do |name, manifest|
+        "keep durable notes in #{zone_label(manifest, :workspace, "your workspace")}: " \
+          "'textus put KEY --as=#{name}' (no accept needed)"
       end,
-      runner: lambda do |name, _manifest|
-        "refresh intake entries with 'textus refresh KEY --as=#{name}' (uses the entry's declared action)"
+      propose: lambda do |name, manifest|
+        authority = manifest.policy.roles_with_capability("author").first || "the author-holder"
+        "propose changes by writing #{manifest.policy.queue_zone}.* entries with --as=#{name} " \
+          "and a 'proposal:' frontmatter block; the #{authority} role runs 'textus accept' to apply"
       end,
-      generator: lambda do |_name, _manifest|
-        "'textus build' computes output entries from projections; output files are never hand-edited"
+      fetch: lambda do |name, manifest|
+        "fetch #{zone_label(manifest, :quarantine, "quarantine")} entries with " \
+          "'textus fetch KEY --as=#{name}' (uses the entry's declared action)"
+      end,
+      build: lambda do |_name, manifest|
+        derived = zone_label(manifest, :derived, "derived")
+        "'textus build' computes #{derived} entries from projections; " \
+          "#{derived} files are never hand-edited"
       end,
     }.freeze
 
     def self.write_flows_for(manifest)
-      manifest.policy.role_mapping.each_with_object({}) do |(name, kind), acc|
-        tmpl = WRITE_FLOW_TEMPLATES[kind]
-        acc[name] = tmpl.call(name, manifest) if tmpl
+      manifest.data.role_caps.each_with_object({}) do |(name, caps), acc|
+        flows = caps.filter_map do |verb|
+          tmpl = WRITE_FLOW_TEMPLATES[verb.to_sym]
+          tmpl&.call(name, manifest)
+        end
+        acc[name] = flows.join(" / ") unless flows.empty?
       end
     end
 
+    # Human-readable name(s) for the live zone(s) of a given kind, or `fallback`
+    # when the manifest declares none. Lets write-flow guidance name the live
+    # zone by kind instead of a hardcoded instance name (ADR 0034).
+    def self.zone_label(manifest, kind, fallback)
+      zones = manifest.policy.zones_of_kind(kind)
+      zones.empty? ? fallback : zones.join(", ")
+    end
+
     # Static, store-independent parts of the agent-facing protocol. The
-    # `role_resolution` block is derived per-manifest in agent_protocol(...)
-    # because role names are user-configurable.
+    # `recipes` and `role_resolution` blocks are derived per-manifest in
+    # agent_protocol(...) because zone and role names are user-configurable.
     AGENT_PROTOCOL_TEMPLATE = {
       "envelope_shape" => {
         "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
@@ -59,7 +69,76 @@ module Textus
         },
         "ref" => "SPEC.md §8",
       },
-      "recipes" => {
+    }.freeze
+
+    # 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" },
+      { "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" },
+    ].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
+
+      writable_zones = manifest.data.declared_zone_kinds.keys.each_with_object([]) do |zname, acc|
+        acc << zname if agent_role && manifest.policy.zone_writers(zname).include?(agent_role)
+      end
+
+      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"] : [],
+        "writable_zones" => writable_zones,
+        "propose_zone" => propose_zone,
+        "latest_seq" => audit_log.latest_seq,
+      }
+    end
+
+    def self.recipes(manifest)
+      queue = manifest.policy.queue_zone
+      feeds = zone_label(manifest, :quarantine, "the quarantine zone")
+      {
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
@@ -78,73 +157,29 @@ module Textus
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "echo ENVELOPE | textus put review.KEY --as=agent --stdin",
+            "echo ENVELOPE | textus put #{queue}.KEY --as=agent --stdin",
           ],
           "human_steps" => [
-            "textus accept review.KEY --as=human       # promotes the proposal to its target zone",
+            "textus accept #{queue}.KEY --as=human       # promotes the proposal to its target zone",
           ],
         },
-        "refresh" => {
-          "purpose" => "rebuild stale intake-zone caches from their declared actions",
+        "fetch" => {
+          "purpose" => "rebuild stale quarantine-zone caches from their declared actions",
           "steps" => [
-            "textus freshness --zone=intake            # report fresh/stale per entry",
-            "textus refresh stale --zone=intake --as=runner",
+            "textus freshness --zone=#{feeds}            # report fresh/stale per entry",
+            "textus fetch stale --zone=#{feeds} --as=automation",
           ],
         },
-      },
-    }.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" },
-      { "name" => "accept",   "summary" => "apply a review.* proposal; --as=human only" },
-      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
-      { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
-      { "name" => "build",    "summary" => "materialize output entries; publish_to and publish_each fan out copies" },
-      { "name" => "refresh",  "summary" => "run an action for an intake entry" },
-      { "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 review, doctor summary" },
-    ].freeze
-
-    def self.agent_quickstart(manifest, audit_log)
-      proposer_roles = manifest.policy.roles_with_kind(:proposer)
-      agent_role = proposer_roles.first
-
-      writable_zones = manifest.data.zones.each_with_object([]) do |(zname, writers), acc|
-        acc << zname if agent_role && writers.include?(agent_role)
-      end
-
-      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"] : [],
-        "writable_zones" => writable_zones,
-        "propose_zone" => propose_zone,
-        "latest_seq" => audit_log.latest_seq,
       }
     end
 
     def self.agent_protocol(manifest)
       AGENT_PROTOCOL_TEMPLATE.merge(
+        "recipes" => recipes(manifest),
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
-                       "default 'human'",
-          "roles" => manifest.policy.role_mapping.keys,
+                       "then a transport default ('human' for CLI, 'agent' for MCP)",
+          "roles" => manifest.data.role_caps.keys,
           "ref" => "SPEC.md §5",
         },
       )
@@ -162,17 +197,17 @@ 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
 
     def self.zones_for(manifest)
-      manifest.data.zones.map do |name, writers|
-        row = { "name" => name, "writers" => Array(writers) }
+      manifest.data.declared_zone_kinds.keys.map do |name|
+        row = { "name" => name, "writers" => manifest.policy.zone_writers(name) }
         kind = manifest.policy.declared_kind(name)
         row["kind"] = kind.to_s if kind
-        purpose = ZONE_PURPOSES[name]
-        row["purpose"] = purpose if purpose
+        purpose = manifest.data.zone_descs[name]
+        row["purpose"] = purpose if purpose && !purpose.empty?
         row
       end
     end

data/lib/textus/cli/group/{refresh.rb → fetch.rb}

@@ -1,15 +1,15 @@
 module Textus
   class CLI
     class Group
-      class Refresh < Group
-        command_name "refresh"
+      class Fetch < Group
+        command_name "fetch"
 
         def parse(argv)
           if argv.first == "stale"
             argv.shift
-            @sub_klass = Verb::RefreshStale
+            @sub_klass = Verb::FetchStale
           else
-            @sub_klass = Verb::Refresh
+            @sub_klass = Verb::Fetch
           end
           @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
           @sub.parse(argv)

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

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           Textus::Ports::BuildLock.with(root: store.root) do
-            role = store.manifest.policy.roles_with_kind(:generator).first || "builder"
+            role = store.manifest.policy.roles_with_capability("build").first || "automation"
             ops = store.as(role)
             result = ops.publish(prefix: prefix)
             emit(result)

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

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class Fetch < Verb
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("fetch requires a key")
+          emit(session_for(store).fetch(key).to_h_for_wire)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/{refresh_stale.rb → fetch_stale.rb}

@@ -1,16 +1,16 @@
 module Textus
   class CLI
     class Verb
-      class RefreshStale < Verb
+      class FetchStale < Verb
         command_name "stale"
-        parent_group Group::Refresh
+        parent_group Group::Fetch
 
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
         option :as_flag, "--as=ROLE"
 
         def call(store)
-          result = session_for(store).refresh_all(prefix: prefix, zone: zone)
+          result = session_for(store).fetch_all(prefix: prefix, zone: zone)
           emit(result)
           result["ok"] ? 0 : 1
         end

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

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = session_for(store).get_or_refresh(key)
+          result = session_for(store).get_or_fetch(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

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

@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "runner"
+                  "key" => e.key, "as" => defn["as"] || "automation"
                 }
               end
             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/put.rb

@@ -25,7 +25,7 @@ module Textus
               {
                 "_meta" => {
                   "name" => basename,
-                  "last_refreshed_at" => Time.now.utc.iso8601,
+                  "last_fetched_at" => Time.now.utc.iso8601,
                   "fetched_with" => fetch_name,
                 }.merge(result[:_meta] || result["_meta"] || {}),
                 "body" => result[:body] || result["body"] || "",

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

@@ -8,16 +8,16 @@ module Textus
         def call(store)
           policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }
-            if b.refresh
-              row["refresh"] = {
-                "ttl_seconds" => b.refresh.ttl_seconds,
-                "on_stale" => b.refresh.on_stale,
-                "sync_budget_ms" => b.refresh.sync_budget_ms,
-                "fetch_timeout_seconds" => b.refresh.fetch_timeout_seconds,
+            if b.fetch
+              row["fetch"] = {
+                "ttl_seconds" => b.fetch.ttl_seconds,
+                "on_stale" => b.fetch.on_stale,
+                "sync_budget_ms" => b.fetch.sync_budget_ms,
+                "fetch_timeout_seconds" => b.fetch.fetch_timeout_seconds,
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
-            row["promotion"] = { "requires" => b.promote.requires } if b.promote
+            row["guard"] = b.guard if b.guard
             row["retention"] = { "expire_after" => b.retention.expire_after, "archive_after" => b.retention.archive_after } if b.retention
             row
           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