textus 0.43.2 → 0.46.0

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

@@ -7,8 +7,8 @@ module Textus
     REDUCER_TIMEOUT_SECONDS = 2
 
     # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
-    #   semantics: pure read (`ops.get`) for materialization paths;
-    #   `ops.get_or_fetch` if you want fetch-on-stale.
+    #   semantics: pure read (`Read::Get.new(...).call(key)`, fetch:false default) for
+    #   materialization paths; `ops.get` (read-through, fetch:true injected) for fetch-on-stale.
     # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
     # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
     # `transform_context` — capability object handed to transform reducers as `caps:`.
@@ -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

@@ -30,6 +30,25 @@ module Textus
         end
       end
 
+      extend Textus::Contract::DSL
+
+      verb     :audit
+      summary  "Query the audit log with optional filters."
+      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"
+      arg :zone,           String,  required: false, description: "filter to keys in this zone"
+      arg :role,           String,  required: false, description: "filter to rows written under this role"
+      arg :verb,           String,  required: false, description: "filter to rows for this verb"
+      arg :since,          String,  required: false,
+                                    coerce: ->(s) { Textus::Read::Audit.parse_since(s, now: Time.now) },
+                                    description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
+      arg :seq_since,      Integer, required: false, description: "return rows with seq > this cursor value"
+      arg :correlation_id, String,  required: false, description: "filter to rows with this correlation_id"
+      arg :limit,          Integer, required: false, description: "maximum number of rows to return"
+      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest  = container.manifest
         @root      = container.root

data/lib/textus/read/blame.rb

@@ -7,13 +7,23 @@ module Textus
     # row. Falls back to `git => nil` when not in a git repo or when the
     # file is untracked.
     class Blame
+      extend Textus::Contract::DSL
+
+      verb     :blame
+      summary  "Annotate audit rows for a key with the git commit that introduced each file state."
+      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"
+      view(:cli) { |rows, inputs| { "verb" => "blame", "key" => inputs[:key], "rows" => rows } }
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @container = container
         @manifest  = container.manifest
         @root      = container.root
       end
 
-      def call(key:, limit: nil)
+      def call(key, limit: nil)
         audit_rows = Textus::Read::Audit.new(container: @container).call(key: key, limit: limit)
         path = resolve_path(key)
         return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)

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

@@ -1,12 +1,26 @@
 module Textus
   module Read
     class Deps
+      extend Textus::Contract::DSL
+
+      verb     :deps
+      summary  "List the keys a derived entry depends on (its projection/external sources)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key of the derived entry whose source keys you want"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end
 
       def call(key)
-        entry = @manifest.data.entries.find { |e| e.key == key } or return []
+        { "key" => key, "deps" => sources_for(key) }
+      end
+
+      private
+
+      def sources_for(key)
+        entry = @manifest.data.entries.find { |e| e.key == key }
         return [] unless entry.is_a?(Textus::Manifest::Entry::Derived)
 
         src = entry.source

data/lib/textus/read/doctor.rb

@@ -6,6 +6,14 @@ module Textus
     # The acting role is irrelevant to a read-only health check, so `call`
     # is not consulted.
     class Doctor
+      extend Textus::Contract::DSL
+
+      verb     :doctor
+      summary  "Run health checks on the textus store and report any issues."
+      surfaces :cli
+      cli      "doctor"
+      arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/freshness.rb

@@ -7,6 +7,16 @@ module Textus
     # current status. Status is one of :fresh, :stale, :never_fetched, or
     # :no_policy.
     class Freshness
+      extend Textus::Contract::DSL
+
+      verb     :freshness
+      summary  "Report the fetch-freshness status of every entry with a fetch policy."
+      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"
+      view(:cli) { |rows| { "verb" => "freshness", "rows" => rows } }
+
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
         @container  = container
         @call       = call

data/lib/textus/read/get.rb

@@ -1,54 +1,103 @@
 module Textus
   module Read
-    # Pure read: returns the on-disk envelope annotated with a freshness
-    # verdict. Never triggers fetch; never invokes the orchestrator.
+    # The one read path. `fetch:` controls behavior:
+    #   fetch: false (default) — pure read: the on-disk envelope annotated with
+    #     a freshness verdict. NEVER builds the orchestrator (no threads/forks/
+    #     locks/events). This is the safe default for direct (in-process)
+    #     callers — accept/reject/publish, materializer, uid, validate_all/
+    #     validator, schema tooling, and the hook context — that must read
+    #     persisted truth without triggering a fetch.
+    #   fetch: true — read-through: after a stale verdict, hands off to the
+    #     fetch orchestrator per the entry's fetch rule (degrades to the pure
+    #     result when the key has no rule).
     #
-    # For interactive reads that want fetch-on-stale, use
-    # `Read::GetOrFetch`, which composes this with the orchestrator.
+    # The public `get` verb is read-through because the contract declares
+    # `arg :fetch, default: true`, injected on every verb surface (RoleScope +
+    # MCP map_args, ADR 0062 amendment). Direct construction bypasses that
+    # injection and so gets the safe `fetch: false` method default.
     class Get
       extend Textus::Contract::DSL
 
       verb     :get
-      summary  "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness)."
-      surfaces :cli, :ruby, :mcp
+      summary  "Read one entry. Read-through by default — fetches on stale per " \
+               "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, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted entry key to read, e.g. 'knowledge.project'"
-      response(&:to_h_for_wire)
+      arg :fetch, :boolean, default: true,
+                            description: "read-through (fetch on stale per the " \
+                                         "entry's fetch rule) when true, the default; " \
+                                         "false returns the on-disk envelope without ever fetching"
+      view { |v, _i| v.to_h_for_wire }
 
-      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator, orchestrator: nil)
         @container  = container
         @call       = call
         @manifest   = container.manifest
         @file_store = container.file_store
         @evaluator  = evaluator
+        @orchestrator = orchestrator # nil → built lazily on first fetch only
       end
 
-      def call(key)
+      def call(key, fetch: false)
+        envelope = annotated_envelope(key)
+        return envelope if envelope.nil?
+        return envelope unless fetch && envelope.freshness&.stale
+
+        fetch_policy = fetch_policy_for(key)
+        return envelope if fetch_policy.nil?
+
+        policy  = fetch_policy.to_freshness_policy
+        verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
+        outcome = orchestrator.execute(policy.decide(verdict), key: key)
+        resolve(outcome, envelope)
+      end
+
+      # Strict variant: raises UnknownKey when the entry is missing.
+      # Used by consumers (e.g. uid, Validator) that distinguish absence.
+      def get(key, fetch: false)
+        call(key, fetch: fetch) ||
+          raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      end
+
+      private
+
+      # Pure read + freshness verdict; no orchestrator dependency.
+      def annotated_envelope(key)
         envelope = read_raw_envelope(key)
         return nil if envelope.nil?
 
-        policy_set = @manifest.rules.for(key)
-        fetch_policy = policy_set.fetch
+        fetch_policy = fetch_policy_for(key)
         return annotate_fresh(envelope) if fetch_policy.nil?
 
-        policy = fetch_policy.to_freshness_policy
+        policy  = fetch_policy.to_freshness_policy
         verdict = @evaluator.call(policy, envelope, now: @call.now)
-
         envelope.with(freshness: Textus::Domain::Freshness.build(
-          stale: verdict.stale?,
-          reason: verdict.reason,
-          fetching: false,
+          stale: verdict.stale?, reason: verdict.reason, fetching: false,
         ))
       end
 
-      # Strict variant: raises UnknownKey when the entry is missing.
-      # Used by consumers (e.g. Validator) that need to distinguish absence
-      # from emptiness.
-      def get(key)
-        call(key) || raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      def fetch_policy_for(key)
+        @manifest.rules.for(key).fetch
       end
 
-      private
+      def resolve(outcome, envelope)
+        case outcome
+        when Textus::Domain::Outcome::Skipped
+          envelope
+        when Textus::Domain::Outcome::Fetched
+          outcome.envelope.with(
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, fetching: false),
+          )
+        when Textus::Domain::Outcome::Detached
+          envelope.with(freshness: envelope.freshness.with(fetching: true))
+        when Textus::Domain::Outcome::Failed
+          envelope.with(freshness: envelope.freshness.with(fetch_error: outcome.error.message))
+        else raise "unexpected fetch outcome: #{outcome.class}"
+        end
+      end
 
       def read_raw_envelope(key)
         res = @manifest.resolver.resolve(key)
@@ -70,6 +119,22 @@ module Textus
           stale: false, reason: nil, fetching: false,
         ))
       end
+
+      def orchestrator
+        @orchestrator ||= build_orchestrator
+      end
+
+      def build_orchestrator
+        worker = Textus::Write::FetchWorker.new(container: @container, call: @call)
+        Textus::Write::FetchOrchestrator.new(
+          worker: worker, store_root: @container.root, events: @container.events,
+          hook_context: hook_context
+        )
+      end
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
     end
   end
 end

data/lib/textus/read/list.rb

@@ -5,9 +5,10 @@ module Textus
 
       verb     :list
       summary  "List keys filtered by zone and/or prefix."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
       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"
+      view(:cli) { |rows| { "entries" => rows } }
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest

data/lib/textus/read/published.rb

@@ -1,6 +1,13 @@
 module Textus
   module Read
     class Published
+      extend Textus::Contract::DSL
+
+      verb     :published
+      summary  "List all entries that declare a publish_to target."
+      surfaces :cli
+      cli      "published"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end

data/lib/textus/read/pulse.rb

@@ -11,7 +11,8 @@ module Textus
 
       verb     :pulse
       summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
-      surfaces :cli, :ruby, :mcp
+      surfaces :cli, :mcp
+      around   :cursor
       arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
 
       def initialize(container:, call:)

data/lib/textus/read/rdeps.rb

@@ -1,11 +1,25 @@
 module Textus
   module Read
     class Rdeps
+      extend Textus::Contract::DSL
+
+      verb     :rdeps
+      summary  "List the derived entries that depend on a key (reverse deps / impact set)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose dependents (what would be stranded if it moved) you want"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end
 
       def call(key)
+        { "key" => key, "rdeps" => dependents_of(key) }
+      end
+
+      private
+
+      def dependents_of(key)
         @manifest.data.entries.each_with_object([]) do |e, acc|
           next unless e.is_a?(Textus::Manifest::Entry::Derived)
 

data/lib/textus/read/rule_explain.rb

@@ -0,0 +1,84 @@
+module Textus
+  module Read
+    # Effective rules for a key, at two depths (ADR 0059). Lean by default —
+    # `{ fetch, guard }`, the agent-cheap read that was the `rules` verb. With
+    # `detail: true` it returns the verbose explanation — every matching policy
+    # block plus the per-transition guard predicate names — that was
+    # `policy_explain`. One verb, one name across CLI/MCP/method; the audience
+    # split is a parameter, not two tools.
+    class RuleExplain
+      extend Textus::Contract::DSL
+
+      verb     :rule_explain
+      summary  "Effective rules for a key. Lean {fetch, guard} by default; detail: true adds matched blocks + guard predicates."
+      surfaces :cli, :mcp
+      cli      "rule explain"
+      arg :key,    String, required: true, positional: true,
+                           description: "dotted key whose effective rules you want (fetch ttl/action, write guard, ...)"
+      arg :detail, :boolean,
+          description: "defaults false: lean {fetch, guard}. detail: true adds matched blocks + guard predicates per transition."
+      view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+        @schemas  = container.schemas
+      end
+
+      def call(key, detail: false)
+        detail ? explain(key) : effective(key)
+      end
+
+      private
+
+      # Lean: the effective winners only (formerly Read::Rules / the `rules` verb).
+      def effective(key)
+        set = @manifest.rules.for(key)
+        {
+          "fetch" => set.fetch && {
+            "ttl_seconds" => set.fetch.ttl_seconds,
+            "on_stale" => set.fetch.on_stale,
+            "sync_budget_ms" => set.fetch.sync_budget_ms,
+            "fetch_timeout_seconds" => set.fetch.fetch_timeout_seconds,
+          },
+          "guard" => set.guard,
+        }.compact
+      end
+
+      # Verbose: every matching block, per-slot effective value, and the
+      # effective guard predicate names for each write transition (formerly
+      # Read::PolicyExplain, ADR 0031).
+      def explain(key)
+        matching = @manifest.rules.explain(key)
+        winners  = @manifest.rules.for(key)
+        factory  = Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
+
+        {
+          key: key,
+          matched_blocks: matching.map do |b|
+            {
+              match: b.match,
+              fetch: !b.fetch.nil?,
+              handler_allowlist: !b.handler_allowlist.nil?,
+              guard: !b.guard.nil?,
+              retention: !b.retention.nil?,
+            }
+          end,
+          effective: {
+            fetch: winners.fetch && {
+              ttl_seconds: winners.fetch.ttl_seconds,
+              on_stale: winners.fetch.on_stale,
+            },
+            handler_allowlist: winners.handler_allowlist&.handlers,
+            retention: winners.retention && {
+              expire_after: winners.retention.expire_after,
+              archive_after: winners.retention.archive_after,
+            },
+          },
+          guards: Textus::Domain::Policy::BaseGuards::BASE.keys.to_h do |transition|
+            [transition, factory.for(transition, key).predicates.map(&:name)]
+          end,
+        }
+      end
+    end
+  end
+end

data/lib/textus/read/rule_list.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Read
+    # Enumerate every declared rule block in the manifest, in order. This is
+    # the whole-manifest view; `rule_explain` is the for-key view. Extracted
+    # from the CLI verb so the rule family is fully use-case-backed (ADR 0059);
+    # CLI-only (no MCP contract) — an agent reasons per-key via rule_explain.
+    class RuleList
+      extend Textus::Contract::DSL
+
+      verb     :rule_list
+      summary  "List every rule block in the manifest."
+      surfaces :cli
+      cli      "rule list"
+      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call
+        @manifest.rules.blocks.map do |b|
+          row = { "match" => b.match }
+          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["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
+      end
+    end
+  end
+end

data/lib/textus/read/schema_envelope.rb

@@ -3,9 +3,10 @@ module Textus
     class SchemaEnvelope
       extend Textus::Contract::DSL
 
-      verb     :schema
+      verb     :schema_show
       summary  "Return the schema (field shape) for an entry's family, by key."
-      surfaces :ruby, :mcp
+      surfaces :cli, :mcp
+      cli      "schema show"
       arg :key, String, required: true, positional: true,
                         description: "any key in the family whose schema you want; returns required/optional fields and their types"
 

data/lib/textus/read/uid.rb

@@ -1,6 +1,15 @@
 module Textus
   module Read
     class Uid
+      extend Textus::Contract::DSL
+
+      verb     :uid
+      summary  "Return the stable UID of an entry without reading its body."
+      surfaces :cli
+      cli      "key uid"
+      arg :key, String, required: true, positional: true, description: "entry key"
+      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/where.rb

@@ -1,6 +1,14 @@
 module Textus
   module Read
     class Where
+      extend Textus::Contract::DSL
+
+      verb     :where
+      summary  "Resolve a key to its zone, owner, and path without reading the body."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end