textus 0.45.1 → 0.47.0

data/lib/textus/doctor/check/orphaned_publish_targets.rb

@@ -8,7 +8,7 @@ module Textus
       # that drift without making `build` scan globally.
       class OrphanedPublishTargets < Check
         def call
-          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          sdir = Textus::Layout.sentinels(root)
           return [] unless File.directory?(sdir)
 
           repo_root = File.dirname(root)

data/lib/textus/doctor/check/sentinels.rb

@@ -5,7 +5,7 @@ module Textus
         def call
           store      = Textus::Ports::SentinelStore.new
           file_stat  = Textus::Ports::Storage::FileStat.new
-          dir        = File.join(root, "sentinels")
+          dir        = Textus::Layout.sentinels(root)
           return [] unless file_stat.directory?(dir)
 
           repo_root = File.dirname(root)

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -35,13 +35,14 @@ module Textus
           private
 
           # Domain-pure: reads the stored write timestamp from the envelope's
-          # freshness (checked_at) or meta (last_fetched_at/generated_at) and
-          # parses the stored ISO-8601 string. Parsing a stored string is not
-          # I/O (allowed in domain, ADR 0024).
+          # freshness (checked_at) or meta (last_fetched_at) and parses the
+          # stored ISO-8601 string. Parsing a stored string is not I/O (allowed
+          # in domain, ADR 0024). `generated_at` is intentionally NOT consulted:
+          # build-generation time is no longer carried in the artifact (ADR
+          # 0070), and fetch-freshness is a fetch concept, not a build one.
           def written_at(envelope)
             raw = envelope.freshness&.checked_at ||
-                  envelope.meta&.dig("last_fetched_at") ||
-                  envelope.meta&.dig("generated_at")
+                  envelope.meta&.dig("last_fetched_at")
             return raw if raw.is_a?(Time)
             return nil if raw.nil?
 

data/lib/textus/envelope/io/writer.rb

@@ -82,6 +82,7 @@ module Textus
           raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
 
           @file_store.delete(path)
+          prune_empty_parents(path)
           @audit_log.append(
             role: @call.role, verb: "delete", key: key,
             etag_before: etag_before, etag_after: nil,
@@ -99,6 +100,7 @@ module Textus
 
           FileUtils.mkdir_p(File.dirname(to_path))
           FileUtils.mv(from_path, to_path)
+          prune_empty_parents(from_path)
           basename = to_key.split(".").last
           Entry.for_format(new_mentry.format).rewrite_name(to_path, basename)
           etag_after = Etag.for_file(to_path)
@@ -129,6 +131,38 @@ module Textus
 
         private
 
+        # After a file leaves a directory (delete or move-source), remove any
+        # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
+        # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
+        # declared, first-class container, so its own dir is preserved even when
+        # momentarily empty; only the sub-dirs the bulk op carved out are
+        # pruned. Stops at the first non-empty ancestor, so a dir holding a
+        # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
+        # non-empty dir is silently fine, never fatal to the write.
+        def prune_empty_parents(path)
+          floor = zone_floor(path)
+          return unless floor
+
+          dir = File.dirname(path)
+          while dir.start_with?("#{floor}/") && Dir.empty?(dir)
+            Dir.rmdir(dir)
+            dir = File.dirname(dir)
+          end
+        rescue SystemCallError
+          nil
+        end
+
+        # The zone directory under which `path` lives (`<root>/zones/<zone>`),
+        # or nil if `path` is not under the store's zones tree.
+        def zone_floor(path)
+          zones_root = File.join(@manifest.data.root, "zones")
+          prefix = "#{zones_root}/"
+          return nil unless path.start_with?(prefix)
+
+          zone_seg = path.delete_prefix(prefix).split("/").first
+          zone_seg && File.join(zones_root, zone_seg)
+        end
+
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end

data/lib/textus/etag.rb

@@ -9,5 +9,28 @@ module Textus
     def self.for_file(path)
       for_bytes(File.binread(path))
     end
+
+    # The fingerprint of everything an agent's boot orientation depends on:
+    # the manifest PLUS the executable contract — hooks and schemas. A
+    # mid-session edit to any of these makes the cached orientation stale, so
+    # the session must re-boot (ADR 0074). The composite is one digest over the
+    # sorted per-file listing, so it is order-stable.
+    def self.for_contract(root)
+      listing = contract_files(root).map do |path|
+        rel = path.delete_prefix(root).delete_prefix("/")
+        "#{rel}:#{for_file(path)}"
+      end.join("\n")
+      for_bytes(listing)
+    end
+
+    # manifest.yaml, then every hook and schema file. Dir.glob already returns
+    # sorted paths (Ruby 3.0+), keeping the digest independent of FS order.
+    def self.contract_files(root)
+      [
+        File.join(root, "manifest.yaml"),
+        *Dir.glob(File.join(root, "hooks", "**", "*.rb")),
+        *Dir.glob(File.join(root, "schemas", "**", "*")).select { |f| File.file?(f) },
+      ]
+    end
   end
 end

data/lib/textus/hooks/catalog.rb

@@ -20,6 +20,7 @@ module Textus
         proposal_rejected: %i[ctx key target_key],
         file_published: %i[ctx key envelope source target],
         store_loaded: %i[ctx],
+        session_opened: %i[ctx role cursor],
         fetch_started: %i[ctx key mode],
         fetch_failed: %i[ctx key error_class error_message],
         fetch_backgrounded: %i[ctx key started_at budget_ms],

data/lib/textus/init/templates/orientation_reducer.rb

@@ -0,0 +1,17 @@
+# Reducer that reshapes the raw projection rows into the keys the
+# orientation.mustache template references. Without this, the template
+# would only have access to the flat rows list.
+Textus.hook do |reg|
+  reg.on(:transform_rows, :orientation_reducer) do |rows:, **|
+    project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
+    runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
+
+    {
+      "project" => {
+        "name" => project_row["name"],
+        "description" => project_row["description"]
+      },
+      "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
+    }
+  end
+end

data/lib/textus/init.rb

@@ -94,13 +94,36 @@ module Textus
       Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)
               :entry_put, :entry_deleted, :entry_fetched, :entry_renamed,
               :build_completed, :proposal_accepted, :proposal_rejected,
-              :file_published, :store_loaded,
+              :file_published, :store_loaded, :session_opened,
               :fetch_started, :fetch_failed, :fetch_backgrounded (pub-sub — return discarded)
 
       See SPEC.md §5.10 for the full table.
     MD
 
-    def self.run(target_root)
+    AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
+      # --with-agent profile: project facts + runbooks feed the orientation
+      # projection below, which `textus build` renders to CLAUDE.md/AGENTS.md.
+      - { key: knowledge.project, path: knowledge/project.md, zone: knowledge, schema: project, owner: human:self, kind: leaf }
+      - { key: knowledge.runbooks, path: knowledge/runbooks, zone: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
+      - key: artifacts.orientation
+        path: artifacts/orientation.md
+        zone: artifacts
+        template: orientation.mustache
+        inject_boot: true
+        publish:
+          to:
+          - CLAUDE.md
+          - AGENTS.md
+        compute:
+          kind: projection
+          select:
+          - knowledge.project
+          - knowledge.runbooks
+          transform: orientation_reducer
+        kind: derived
+    YAML
+
+    def self.run(target_root, with_agent: false)
       raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
 
       FileUtils.mkdir_p(File.join(target_root, "schemas"))
@@ -115,12 +138,52 @@ module Textus
       scaffold_dir = File.expand_path("init/templates", __dir__)
       File.write(File.join(target_root, "hooks", "machine_intake.rb"),
                  File.read(File.join(scaffold_dir, "machine_intake.rb")))
-      File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
+      File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
+      mcp_status = nil
+      if with_agent
+        scaffold_agent_profile(target_root, scaffold_dir)
+        mcp_status = write_mcp_config(target_root, scaffold_dir)
+      end
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
       File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
-      { "protocol" => PROTOCOL, "initialized" => target_root }
+      result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
+      result["mcp_config"] = mcp_status if with_agent
+      result
+    end
+
+    # Composes the agent profile by inserting AGENT_ENTRIES immediately before the
+    # top-level `rules:` block of DEFAULT_MANIFEST — that block is load-bearing for
+    # this `.sub`; removing it from DEFAULT_MANIFEST would silently drop the entries.
+    def self.manifest_yaml(with_agent:)
+      return DEFAULT_MANIFEST unless with_agent
+
+      DEFAULT_MANIFEST.sub(/^rules:/, "#{AGENT_ENTRIES}rules:")
+    end
+
+    # Copies the proven orientation bundle into a freshly-init'd store.
+    def self.scaffold_agent_profile(target_root, scaffold_dir)
+      {
+        "project.schema.yaml" => File.join("schemas", "project.yaml"),
+        "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
+        "orientation.mustache" => File.join("templates", "orientation.mustache"),
+        "orientation_reducer.rb" => File.join("hooks", "orientation_reducer.rb"),
+      }.each do |src, dest|
+        File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
+      end
+    end
+
+    # The one file init writes outside .textus/: a starter .mcp.json at the
+    # project root. Write-once — never clobber a hand-authored config. The
+    # command form assumes a gem-installed `textus` on PATH; the user owns
+    # the file after this first write.
+    def self.write_mcp_config(target_root, scaffold_dir)
+      dest = File.join(File.dirname(target_root), ".mcp.json")
+      return "skipped" if File.exist?(dest)
+
+      File.write(dest, File.read(File.join(scaffold_dir, "mcp.json")))
+      "written"
     end
 
     # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now

data/lib/textus/layout.rb

@@ -29,6 +29,14 @@ module Textus
       File.join(run(root), "audit")
     end
 
+    # Sentinels are machine-generated (the published target's sha), not authored
+    # source, so they live on the runtime side under `.run/` — git-ignored,
+    # regenerated by the next build via content-identical adoption (ADR 0070,
+    # superseding ADR 0038's `:config` classification).
+    def self.sentinels(root)
+      File.join(run(root), "sentinels")
+    end
+
     def self.audit_log(root)
       File.join(audit_dir(root), "audit.log")
     end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -6,11 +6,12 @@ module Textus
 
       verb     :key_delete_prefix
       summary  "Bulk-delete every leaf key under prefix."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli      "key delete-prefix"
       arg :prefix,  String, required: true, positional: true, description: "every leaf key under this dotted prefix is deleted"
-      arg :dry_run, :boolean, default: true, cli_default: false,
-                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the keys that would be deleted without deleting them; " \
+                                           "defaults to false, so omitting it deletes immediately"
       view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
@@ -18,7 +19,7 @@ module Textus
         @call         = call
       end
 
-      def call(prefix, dry_run: true)
+      def call(prefix, dry_run: false)
         raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
 
         leaves = Read::List.new(container: @container)

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -7,12 +7,13 @@ 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
+      surfaces :cli, :mcp
       cli      "key mv-prefix"
       arg :from_prefix, String, required: true, positional: true, description: "dotted prefix whose leaf keys are renamed"
       arg :to_prefix,   String, required: true, positional: true, description: "dotted prefix the keys are renamed to"
-      arg :dry_run,     :boolean, default: true, cli_default: false,
-                                  description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      arg :dry_run,     :boolean, default: false,
+                                  description: "when true, returns the planned moves without applying them; " \
+                                               "defaults to false, so omitting it applies the rename immediately"
       view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
@@ -20,10 +21,19 @@ module Textus
         @call         = call
       end
 
-      def call(from_prefix, to_prefix, dry_run: true)
+      def call(from_prefix, to_prefix, dry_run: false)
         raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
 
         leaves = list_leaves_under(from_prefix)
+
+        # When from_prefix is itself a leaf, `delete_prefix("#{from_prefix}.")`
+        # finds no trailing dot to strip, so the tail keeps the whole key and the
+        # move silently targets "to_prefix.<full-from_prefix>". Refuse it — a
+        # single-key rename is `mv`'s job, not the bulk prefix verb's.
+        if leaves.include?(from_prefix)
+          raise UsageError.new("from_prefix '#{from_prefix}' is itself a leaf — use `mv` to rename a single key")
+        end
+
         warnings = []
         warnings << "no keys under #{from_prefix}" if leaves.empty?
 

data/lib/textus/maintenance/migrate.rb

@@ -9,11 +9,12 @@ module Textus
 
       verb     :migrate
       summary  "Run a YAML migration plan (multi-op)."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :plan_yaml, String, required: true, positional: true, source: :file,
                               description: "path to the YAML migration plan (zone_mv, key_mv_prefix, key_delete_prefix ops run in order)"
-      arg :dry_run, :boolean, default: true, cli_default: false,
-                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the planned ops without applying them; " \
+                                           "defaults to false, so omitting it runs the migration immediately"
       view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
@@ -21,7 +22,7 @@ module Textus
         @call         = call
       end
 
-      def call(plan_yaml, dry_run: true)
+      def call(plan_yaml, dry_run: false)
         raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
         raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
 

data/lib/textus/maintenance/rule_lint.rb

@@ -10,7 +10,7 @@ module Textus
 
       verb     :rule_lint
       summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli      "rule lint"
       arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
                                    description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"

data/lib/textus/maintenance/zone_mv.rb

@@ -10,12 +10,13 @@ module Textus
 
       verb     :zone_mv
       summary  "Rename a zone — manifest + files. Refuses if destination exists."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       cli      "zone mv"
       arg :from,    String, required: true, positional: true, description: "current zone name"
       arg :to,      String, required: true, positional: true, description: "new zone name; refused if a zone by this name already exists"
-      arg :dry_run, :boolean, default: true, cli_default: false,
-                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the planned zone move without applying it; " \
+                                           "defaults to false, so omitting it applies the move immediately"
       view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
@@ -25,7 +26,7 @@ module Textus
         @root      = container.root
       end
 
-      def call(from, to, dry_run: true)
+      def call(from, to, dry_run: false)
         raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
         raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.declared_zone_kinds.key?(from)
 

data/lib/textus/mcp/server.rb

@@ -59,7 +59,17 @@ module Textus
           role: @role,
           cursor: @store.audit_log.latest_seq,
           propose_zone: propose_zone,
-          manifest_etag: manifest_etag,
+          contract_etag: contract_etag,
+        )
+
+        # ADR 0075: announce the connection to connect-time hooks with the
+        # resolved role. Distinct from :store_loaded (fired at Store.new under
+        # the default role, before any connection's role is known).
+        @store.events.publish(
+          :session_opened,
+          ctx: Hooks::Context.new(scope: @store.as(@role)),
+          role: @role,
+          cursor: @session.cursor,
         )
 
         emit_result(rid, {
@@ -79,7 +89,7 @@ module Textus
           return
         end
 
-        @session.check_etag!(manifest_etag)
+        @session.check_etag!(contract_etag)
 
         name = params["name"]
         args = params["arguments"] || {}
@@ -100,8 +110,8 @@ module Textus
         emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
       end
 
-      def manifest_etag
-        @store.file_store.etag(File.join(@store.root, "manifest.yaml"))
+      def contract_etag
+        Textus::Etag.for_contract(@store.root)
       end
 
       def emit_result(rid, result)

data/lib/textus/ports/publisher.rb

@@ -7,8 +7,9 @@ module Textus
     # artifact; no parsing or stripping.
     #
     # Sentinel I/O is delegated to Textus::Ports::SentinelStore. Sentinels live
-    # under `<store_root>/sentinels/` and mirror the target's repo-relative layout
-    # so consumer directories aren't polluted with `.textus-managed.json` siblings.
+    # under `<store_root>/.run/sentinels/` (runtime, git-ignored — ADR 0070) and
+    # mirror the target's repo-relative layout so consumer directories aren't
+    # polluted with `.textus-managed.json` siblings.
     module Publisher
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))

data/lib/textus/ports/sentinel_store.rb

@@ -5,12 +5,12 @@ require "fileutils"
 module Textus
   module Ports
     # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
-    # path layout (<store_root>/sentinels/<target-rel-to-repo>.textus-managed.json),
-    # and all File/FileUtils I/O. Domain::Sentinel is a pure value object that
-    # depends on this port for reads and writes.
+    # path layout (<store_root>/.run/sentinels/<target-rel-to-repo>.textus-managed.json
+    # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
+    # Domain::Sentinel is a pure value object that depends on this port for
+    # reads and writes.
     class SentinelStore
       SUFFIX = ".textus-managed.json".freeze
-      DIR    = "sentinels".freeze
 
       def write!(target:, source:, store_root:)
         path = sentinel_path(target, store_root)
@@ -39,17 +39,18 @@ module Textus
       def sentinel_path(target, store_root)
         repo_root = File.dirname(store_root)
         rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(store_root, DIR, rel + SUFFIX)
+        File.join(Textus::Layout.sentinels(store_root), rel + SUFFIX)
       end
 
       # Absolute target paths of every sentinel recorded under `target_dir`.
       def targets_under(target_dir, store_root)
         repo_root = File.dirname(store_root)
         rel = relative_to(target_dir, repo_root) or return []
-        sdir = File.join(store_root, DIR, rel)
+        root = Textus::Layout.sentinels(store_root)
+        sdir = File.join(root, rel)
         return [] unless File.directory?(sdir)
 
-        prefix = File.join(store_root, DIR) + "/"
+        prefix = root + "/"
         Dir.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
           # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
           trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)

data/lib/textus/projection.rb

@@ -33,15 +33,16 @@ module Textus
       reduced = apply_reducer(rows)
       # Reducers may return either an Array of rows (legacy / templated builds)
       # or a Hash that becomes the structured-format payload base. In the Hash
-      # case, downstream sort/limit/position markers don't apply, and the
-      # builder owns `_meta.generated_at` so we don't stamp it here.
+      # case, downstream sort/limit/position markers don't apply.
       return reduced if reduced.is_a?(Hash)
 
       rows = reduced
       rows = sort(rows)
       rows = rows.first(@limit)
       mark_positions(rows)
-      { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
+      # No `generated_at` in the payload — the built artifact is content-addressed
+      # (ADR 0070); volatile build time is kept out of the tracked output.
+      { "entries" => rows, "count" => rows.length }
     end
 
     private

data/lib/textus/read/audit.rb

@@ -34,7 +34,7 @@ module Textus
 
       verb     :audit
       summary  "Query the audit log with optional filters."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "audit"
       # #call(**filters) — args map to Query.build keyword params (ADR 0063)
       arg :key,            String,  required: false, description: "filter to rows for this key"

data/lib/textus/read/blame.rb

@@ -11,7 +11,7 @@ module Textus
 
       verb     :blame
       summary  "Annotate audit rows for a key with the git commit that introduced each file state."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "blame"
       arg :key,   String,  required: true, positional: true, description: "entry key to blame"
       arg :limit, Integer, required: false, description: "maximum number of audit rows to return"

data/lib/textus/read/boot.rb

@@ -9,7 +9,7 @@ module Textus
 
       verb     :boot
       summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
 
       def initialize(container:, call:)
         @container = container

data/lib/textus/read/capabilities.rb

@@ -0,0 +1,70 @@
+module Textus
+  module Read
+    # A machine-readable projection of the contract surface: every verb, the
+    # transports it reaches, and its full argument schema — sourced from the
+    # same Contract DSL the CLI/MCP/boot already project from (ADR 0039/0063).
+    #
+    # Integrators assert their docs against this in CI so they can't drift
+    # (#161 F4 — patrick-nexus docs claimed "MCP exposes 3 verbs" while ~20 are
+    # surfaced). It also makes the per-surface `dry_run` default asymmetry
+    # (#161 F6) self-documenting: each arg carries both `default` (agent wire)
+    # and `cli_default` (CLI), so the divergence is visible, not folklore.
+    #
+    # Pure contract introspection — it reads no store data; `container` is
+    # accepted only for the uniform use-case constructor.
+    class Capabilities
+      extend Textus::Contract::DSL
+
+      verb     :capabilities
+      summary  "Machine-readable contract surface: every verb, its transports, and arg schema."
+      surfaces :cli, :mcp
+      arg :verb, String, required: false, description: "filter to a single verb by name"
+      view { |result, _i| result }
+
+      def initialize(container: nil, call: nil); end
+
+      def call(verb: nil)
+        klasses = Textus::Dispatcher::VERBS.values.select { |k| contract?(k) }
+        rows = klasses.map { |k| project(k.contract) }
+        rows.select! { |r| r["verb"] == verb } if verb
+        { "verbs" => rows.sort_by { |r| r["verb"] } }
+      end
+
+      private
+
+      def contract?(klass)
+        klass.respond_to?(:contract?) && klass.contract?
+      end
+
+      def project(spec)
+        {
+          "verb" => spec.verb.to_s,
+          "summary" => spec.summary,
+          "surfaces" => spec.surfaces.map(&:to_s) + ["ruby"],
+          "cli" => spec.cli? ? spec.cli_path : nil,
+          "args" => spec.args.map { |a| project_arg(a) },
+        }
+      end
+
+      def project_arg(arg)
+        out = {
+          "name" => arg.wire.to_s,
+          "type" => json_type(arg.type),
+          "required" => arg.required,
+          "positional" => arg.positional,
+        }
+        out["description"] = arg.description if arg.description
+        out["default"] = arg.default unless arg.default.nil?
+        out["cli_default"] = arg.cli_default unless arg.cli_default == :__unset
+        out["session_default"] = arg.session_default.to_s if arg.session_default
+        out
+      end
+
+      def json_type(type)
+        Textus::Contract.json_type(type)
+      rescue ArgumentError
+        "string"
+      end
+    end
+  end
+end

data/lib/textus/read/deps.rb

@@ -5,7 +5,7 @@ module Textus
 
       verb     :deps
       summary  "List the keys a derived entry depends on (its projection/external sources)."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted key of the derived entry whose source keys you want"
 

data/lib/textus/read/doctor.rb

@@ -10,7 +10,7 @@ module Textus
 
       verb     :doctor
       summary  "Run health checks on the textus store and report any issues."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "doctor"
       arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
 

data/lib/textus/read/freshness.rb

@@ -11,7 +11,7 @@ module Textus
 
       verb     :freshness
       summary  "Report the fetch-freshness status of every entry with a fetch policy."
-      surfaces :cli, :ruby
+      surfaces :cli
       cli      "freshness"
       arg :prefix, String, required: false, description: "filter to keys with this prefix"
       arg :zone,   String, required: false, description: "filter to entries in this zone"

data/lib/textus/read/get.rb

@@ -23,7 +23,7 @@ module Textus
                "the entry's fetch rule, degrading to a pure read when the key " \
                "has no rule. Pass fetch:false for a guaranteed pure on-disk " \
                "read. Returns the envelope (uid, etag, _meta, body, freshness)."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted entry key to read, e.g. 'knowledge.project'"
       arg :fetch, :boolean, default: true,