textus 0.10.4 → 0.12.1

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

@@ -0,0 +1,47 @@
+require "yaml"
+
+module Textus
+  module Doctor
+    class Check
+      # Runs as a standalone module (Check::ProtocolVersion.run(root:)) and also
+      # as a class-based doctor check (ProtocolVersion.new(store).call).
+      class ProtocolVersion < Check
+        # Standalone interface: root is the project root (parent of .textus/).
+        def self.run(root:)
+          path = File.join(root, ".textus/manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "severity" => "error",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "hint" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+
+        # Doctor check interface: store.root is the .textus/ directory itself,
+        # so manifest.yaml lives directly inside it.
+        def call
+          path = File.join(store.root, "manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "level" => "error",
+            "subject" => path,
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "fix" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/{policy_ambiguity.rb → rule_ambiguity.rb}

@@ -1,18 +1,18 @@
 module Textus
   module Doctor
     class Check
-      # Flags entries whose key is matched by two or more policy blocks of the
+      # Flags entries whose key is matched by two or more rule blocks of the
       # SAME specificity in the same slot (refresh / handler_allowlist /
       # promote). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
-      class PolicyAmbiguity < Check
+      class RuleAmbiguity < Check
         SLOTS = %i[refresh handler_allowlist promote].freeze
 
         def call
           out = []
-          policies = store.manifest.policies
+          rules = store.manifest.rules
           store.manifest.entries.each do |mentry|
-            matches = policies.explain(mentry.key)
+            matches = rules.explain(mentry.key)
             next if matches.length < 2
 
             SLOTS.each { |slot| out.concat(ambiguities_for(mentry, slot, matches)) }
@@ -34,10 +34,10 @@ module Textus
         def issue_for(mentry, slot, group)
           globs = group.map(&:match).sort
           {
-            "code" => "policy.ambiguity",
+            "code" => "rule.ambiguity",
             "level" => "warning",
             "subject" => mentry.key,
-            "message" => "entry '#{mentry.key}' matches #{group.length} policy blocks at the same " \
+            "message" => "entry '#{mentry.key}' matches #{group.length} rule blocks at the same " \
                          "specificity for #{slot}: #{globs.join(", ")}",
             "fix" => "narrow one of the conflicting match: globs in .textus/manifest.yaml so a single " \
                      "block wins for this key",

data/lib/textus/doctor.rb

@@ -9,6 +9,7 @@ module Textus
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
     CHECKS = [
+      Check::ProtocolVersion,
       Check::ManifestFiles,
       Check::Schemas,
       Check::SchemaParseError,
@@ -20,7 +21,7 @@ module Textus
       Check::AuditLog,
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
-      Check::PolicyAmbiguity,
+      Check::RuleAmbiguity,
       Check::HandlerAllowlist,
     ].freeze
 
@@ -53,8 +54,8 @@ module Textus
     def run_registered_checks(store)
       out = []
       view = Application::Context.new(store: store, role: "human")
-      store.registry.rpc_names(:check).each do |name|
-        callable = store.registry.rpc_callable(:check, name)
+      store.registry.rpc_names(:validate).each do |name|
+        callable = store.registry.rpc_callable(:validate, name)
         begin
           result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
           if result.is_a?(Array)
@@ -71,7 +72,7 @@ module Textus
         rescue StandardError => e
           out << fail_issue(name, code: "doctor_check.failed",
                                   message: "#{e.class}: #{e.message}",
-                                  fix: "fix the :check hook in .textus/hooks/")
+                                  fix: "fix the :validate hook in .textus/hooks/")
         end
       end
       out

data/lib/textus/domain/permission.rb

@@ -1,14 +1,14 @@
 module Textus
   module Domain
-    Permission = Data.define(:zone, :writable_by, :readable_by) do
+    Permission = Data.define(:zone, :write_policy, :read_policy) do
       def allows_write?(role)
-        writable_by.include?(role.to_s)
+        write_policy.include?(role.to_s)
       end
 
       def allows_read?(role)
-        return true if readable_by == :all
+        return true if [:all, ["all"]].include?(read_policy)
 
-        readable_by.include?(role.to_s)
+        read_policy.include?(role.to_s)
       end
     end
   end

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

@@ -0,0 +1,31 @@
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        class HumanAccept
+          attr_reader :reason
+
+          def name
+            "human_accept"
+          end
+
+          # The role is passed via `store` (an Application::Context-like object
+          # with a `role` reader) or through the entry metadata. In practice,
+          # Accept already enforces role == "human" before reaching the
+          # promotion gate, so this predicate trivially passes. It documents
+          # intent and future-proofs multi-actor accept flows.
+          def call(store:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
+            role = store.respond_to?(:role) ? store.role.to_s : nil
+            # If we cannot determine the role (e.g. store doesn't expose it),
+            # we trust that Accept has already checked — allow through.
+            return true if role.nil?
+
+            ok = (role == "human")
+            @reason = "current role is '#{role}', expected 'human'" unless ok
+            ok
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        class SchemaValid
+          attr_reader :reason
+
+          def name
+            "schema_valid"
+          end
+
+          def call(entry:, store:)
+            return true if entry.nil? || store.nil?
+
+            target_key = entry.dig("_meta", "proposal", "target_key")
+            return true unless target_key
+
+            mentry, = store.manifest.resolve(target_key)
+            schema_ref = mentry&.schema
+            return true unless schema_ref
+
+            schema = store.schema_for(schema_ref)
+            return true unless schema
+
+            frontmatter = entry.dig("_meta", "frontmatter") || {}
+            begin
+              schema.validate!(frontmatter)
+            rescue Textus::SchemaViolation => e
+              @reason = e.message.dup
+              d = e.details
+              if d.is_a?(Hash)
+                if d["missing"]
+                  @reason = "missing required fields: #{Array(d["missing"]).join(", ")}"
+                elsif d["field"]
+                  @reason = "field '#{d["field"]}': #{d["reason"]}"
+                end
+              end
+              return false
+            end
+
+            true
+          rescue StandardError => e
+            @reason = "schema validation error: #{e.message}"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/promotion.rb

@@ -0,0 +1,45 @@
+module Textus
+  module Domain
+    module Policy
+      # Promotion evaluates a list of named predicates against a pending-proposal
+      # entry and returns a Result indicating whether all requirements are met.
+      class Promotion
+        Result = Struct.new(:ok?, :reasons, keyword_init: true)
+
+        REGISTRY = {
+          "schema_valid" => -> { Predicates::SchemaValid.new },
+          "human_accept" => -> { Predicates::HumanAccept.new },
+        }.freeze
+
+        def self.from_names(names)
+          predicates = Array(names).map do |n|
+            ctor = REGISTRY[n.to_s] or raise Textus::UsageError.new(
+              "unknown promotion predicate: '#{n}' (known: #{REGISTRY.keys.join(", ")})",
+            )
+            ctor.call
+          end
+          new(predicates: predicates)
+        end
+
+        attr_reader :predicates
+
+        def initialize(predicates:)
+          @predicates = predicates
+        end
+
+        def predicate_names
+          @predicates.map(&:name)
+        end
+
+        def evaluate(entry:, store:)
+          reasons = []
+          @predicates.each do |pred|
+            ok = pred.call(entry: entry, store: store)
+            reasons << "#{pred.name}: #{pred.reason || "predicate failed"}" unless ok
+          end
+          Result.new(ok?: reasons.empty?, reasons: reasons)
+        end
+      end
+    end
+  end
+end

data/lib/textus/errors.rb

@@ -34,7 +34,7 @@ module Textus
       msg += "; did you mean: #{@suggestions.join(", ")}" unless @suggestions.empty?
       hint =
         if @suggestions.empty?
-          "run 'textus list --format=json' to see all keys"
+          "run 'textus list --output=json' to see all keys"
         else
           "did you mean: #{@suggestions.join(", ")}"
         end
@@ -61,6 +61,12 @@ module Textus
     end
   end
 
+  class BadManifest < Error
+    def initialize(m, hint: nil)
+      super("bad_manifest", m, hint: hint)
+    end
+  end
+
   class BadContent < Error
     def initialize(path, m)
       super(
@@ -89,7 +95,7 @@ module Textus
         if writers && !writers.empty?
           writers.join(", ")
         else
-          "the role(s) listed in the manifest 'writable_by:'"
+          "the role(s) listed in the manifest 'write_policy:'"
         end
       details = { "key" => k, "zone" => z }
       details["writers"] = writers if writers
@@ -121,11 +127,12 @@ module Textus
   end
 
   class InvalidRole < Error
-    def initialize(r)
+    def initialize(r, message: nil)
       super(
-        "invalid_role", "role '#{r}' is not declared in any zone",
+        "invalid_role",
+        message || "role '#{r}' is not declared in any zone",
         details: { "role" => r },
-        hint: "valid roles are declared in .textus/manifest.yaml under zones[].writable_by",
+        hint: message ? nil : "valid roles are declared in .textus/manifest.yaml under zones[].write_policy",
       )
     end
   end
@@ -165,4 +172,16 @@ module Textus
   class ProposalError < Error
     def initialize(m) = super("proposal_error", m)
   end
+
+  class FlagRenamed < Error
+    def initialize(old_flag, new_flag)
+      super(
+        "flag_renamed",
+        "#{old_flag} was renamed in textus/3 — use #{new_flag}",
+        details: { "old" => old_flag, "new" => new_flag },
+        hint: "Use #{new_flag} instead.",
+        exit_code: 2,
+      )
+    end
+  end
 end

data/lib/textus/hooks/builtin.rb

@@ -8,21 +8,21 @@ module Textus
     module Builtin
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def self.register_all
-        Textus.hook(:intake, :json) do |store:, config:, args:|
+        Textus.on(:resolve_intake, :json) do |store:, config:, args:|
           _ = store
           _ = args
           data = JSON.parse(config["bytes"].to_s)
           { _meta: {}, body: YAML.dump(data) }
         end
 
-        Textus.hook(:intake, :csv) do |store:, config:, args:|
+        Textus.on(:resolve_intake, :csv) do |store:, config:, args:|
           _ = store
           _ = args
           rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
           { _meta: {}, body: YAML.dump(rows) }
         end
 
-        Textus.hook(:intake, :"markdown-links") do |store:, config:, args:|
+        Textus.on(:resolve_intake, :"markdown-links") do |store:, config:, args:|
           _ = store
           _ = args
           links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
@@ -31,7 +31,7 @@ module Textus
           { _meta: {}, body: YAML.dump(links) }
         end
 
-        Textus.hook(:intake, :"ical-events") do |store:, config:, args:|
+        Textus.on(:resolve_intake, :"ical-events") do |store:, config:, args:|
           _ = store
           _ = args
           events = []
@@ -50,7 +50,7 @@ module Textus
           { _meta: {}, body: YAML.dump(events) }
         end
 
-        Textus.hook(:intake, :rss) do |store:, config:, args:|
+        Textus.on(:resolve_intake, :rss) do |store:, config:, args:|
           _ = store
           _ = args
           doc = REXML::Document.new(config["bytes"].to_s)

data/lib/textus/hooks/dispatcher.rb

@@ -35,7 +35,7 @@ module Textus
         extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
         extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
         @audit_log.append(
-          role: "script", verb: "event_error", key: key,
+          role: "runner", verb: "event_error", key: key,
           etag_before: nil, etag_after: nil, extras: extras
         )
       end

data/lib/textus/hooks/dsl.rb

@@ -1,17 +1,10 @@
 module Textus
   module Hooks
     module Dsl
-      EVENTS = %i[
-        intake reduce check
-        put deleted refreshed built published accepted
-        mv reject loaded
-        refresh_began refresh_failed refresh_detached
-      ].freeze
+      def on(event, name, **, &blk)
+        raise UsageError.new("hook needs a block") unless blk
 
-      EVENTS.each do |event|
-        define_method(event) do |name, **opts, &blk|
-          Loader.current_registry.register(event, name, **opts, &blk)
-        end
+        Loader.current_registry.register(event, name, **, &blk)
       end
     end
   end

data/lib/textus/hooks/loader.rb

@@ -19,8 +19,7 @@ module Textus
     end
   end
 
-  # Public DSL — unchanged surface
+  # Public DSL
   def self.with_registry(registry, &) = Hooks::Loader.with_registry(registry, &)
   def self.current_registry           = Hooks::Loader.current_registry
-  def self.hook(event, name, **, &)   = Hooks::Loader.current_registry.register(event, name, **, &)
 end

data/lib/textus/hooks/registry.rb

@@ -3,23 +3,23 @@ module Textus
     class Registry
       EVENTS = {
         # RPC: exactly 1 handler per name; return value flows into store; failure aborts.
-        intake: { mode: :rpc, args: %i[store config args] },
-        reduce: { mode: :rpc, args: %i[store rows config] },
-        check: { mode: :rpc, args: %i[store] },
+        resolve_intake: { mode: :rpc, args: %i[store config args] },
+        transform_rows: { mode: :rpc, args: %i[store rows config] },
+        validate: { mode: :rpc, args: %i[store] },
 
         # Pub-sub: 0..N handlers per event; return discarded; failure logged to audit.
-        put: { mode: :pubsub, args: %i[store key envelope] },
-        deleted: { mode: :pubsub, args: %i[store key] },
-        refreshed: { mode: :pubsub, args: %i[store key envelope change] },
-        built: { mode: :pubsub, args: %i[store key envelope sources] },
-        accepted: { mode: :pubsub, args: %i[store key target_key] },
-        published: { mode: :pubsub, args: %i[store key envelope source target] },
-        mv: { mode: :pubsub, args: %i[store key from_key to_key envelope] },
-        reject: { mode: :pubsub, args: %i[store key target_key] },
-        loaded: { mode: :pubsub, args: %i[store] },
-        refresh_began: { mode: :pubsub, args: %i[store key mode] },
+        entry_put: { mode: :pubsub, args: %i[store key envelope] },
+        entry_deleted: { mode: :pubsub, args: %i[store key] },
+        entry_refreshed: { mode: :pubsub, args: %i[store key envelope change] },
+        entry_renamed: { mode: :pubsub, args: %i[store key from_key to_key envelope] },
+        build_completed: { mode: :pubsub, args: %i[store key envelope sources] },
+        proposal_accepted: { mode: :pubsub, args: %i[store key target_key] },
+        proposal_rejected: { mode: :pubsub, args: %i[store key target_key] },
+        file_published: { mode: :pubsub, args: %i[store key envelope source target] },
+        store_loaded: { mode: :pubsub, args: %i[store] },
+        refresh_started: { mode: :pubsub, args: %i[store key mode] },
         refresh_failed: { mode: :pubsub, args: %i[store key error_class error_message] },
-        refresh_detached: { mode: :pubsub, args: %i[store key started_at budget_ms] },
+        refresh_backgrounded: { mode: :pubsub, args: %i[store key started_at budget_ms] },
       }.freeze
 
       def initialize(dispatcher: nil)
@@ -29,20 +29,21 @@ module Textus
       end
 
       def register(event, name, keys: nil, &blk)
-        spec = EVENTS[event.to_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event, spec, blk)
+        event_sym = event.to_sym
+        spec = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        shape_check!(event_sym, spec, blk)
         name = name.to_sym
 
         case spec[:mode]
         when :rpc
-          raise UsageError.new("#{event} '#{name}' already registered") if @rpc[event.to_sym].key?(name)
+          raise UsageError.new("#{event_sym} '#{name}' already registered") if @rpc[event_sym].key?(name)
 
-          @rpc[event.to_sym][name] = blk
+          @rpc[event_sym][name] = blk
         when :pubsub
-          raise UsageError.new("#{event} hook '#{name}' already registered") if @pubsub[event.to_sym].any? { |h| h[:name] == name }
+          raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
 
-          @pubsub[event.to_sym] << { name: name, callable: blk, keys: keys }
-          @dispatcher&.subscribe(event, name, keys: keys, &blk)
+          @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
+          @dispatcher&.subscribe(event_sym, name, keys: keys, &blk)
         end
       end
 

data/lib/textus/infra/refresh/detached.rb

@@ -21,7 +21,7 @@ module Textus
 
             begin
               store = Textus::Store.new(store_root)
-              Textus::Refresh.call(store, key, as: "script")
+              Textus::Refresh.call(store, key, as: "runner")
             rescue StandardError
               # Already logged via :refresh_failed; exit cleanly.
             ensure

data/lib/textus/init.rb

@@ -2,16 +2,16 @@ require "fileutils"
 
 module Textus
   module Init
-    ZONES = %w[identity working inbox review output].freeze
+    ZONES = %w[identity working intake review output].freeze
 
     DEFAULT_MANIFEST = <<~YAML
-      version: textus/2
+      version: textus/3
       zones:
-        - { name: identity, writable_by: [human] }
-        - { name: working,  writable_by: [human, ai, script] }
-        - { name: inbox,    writable_by: [script] }
-        - { name: review,   writable_by: [ai, human] }
-        - { name: output,   writable_by: [build] }
+        - { name: identity, write_policy: [human],               read_policy: [all] }
+        - { name: working,  write_policy: [human, agent, runner], read_policy: [all] }
+        - { name: intake,   write_policy: [runner],              read_policy: [all] }
+        - { name: review,   write_policy: [agent, human],        read_policy: [all] }
+        - { name: output,   write_policy: [builder],             read_policy: [all] }
       entries:
         - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self }
         - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true }
@@ -25,56 +25,47 @@ module Textus
       startup in alphabetical order by full path. Subdirectory names are organizational
       only — the registered event and name come from the DSL call, not the file path.
 
-      ## Per-event sugar (preferred)
+      ## DSL
 
       ```ruby
-      Textus.intake(:my_source) do |config:, args:, **|
+      Textus.on(:resolve_intake, :my_source) do |config:, args:, **|
         { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
       end
 
-      Textus.reduce(:my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-      Textus.check(:my_check)   { |store:, **| { ok: true } }
-      Textus.put(:my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
+      Textus.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
+      Textus.on(:validate,       :my_check)  { |store:, **| [] }
+      Textus.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
 
       # Run a side-effect every time textus writes a file to your repo:
-      Textus.published(:notify) do |key:, target:, **|
+      Textus.on(:file_published, :notify) do |key:, target:, **|
         warn "wrote \#{target} (from \#{key})"
       end
       ```
 
       The intake handler above is paired with a manifest entry plus a
-      top-level `policies:` block for freshness (ttl/on_stale live in
-      policies, not in the entry):
+      top-level `rules:` block for freshness (ttl/on_stale live in
+      rules, not in the entry):
 
       ```yaml
       entries:
-        - key: inbox.foo
-          path: inbox/foo.md
-          zone: inbox
+        - key: intake.foo
+          path: intake/foo.md
+          zone: intake
           intake:
             handler: my_source
 
-      policies:
-        - match: inbox.foo
+      rules:
+        - match: intake.foo
           refresh:
             ttl: 10m
             on_stale: timed_sync   # warn | sync | timed_sync (default: warn)
       ```
 
-      ## Low-level primitive (always available)
-
-      ```ruby
-      Textus.hook(:intake, :name) { |store:, config:, args:|  ... }   # bring bytes in
-      Textus.hook(:reduce, :name) { |store:, rows:, config:|  ... }   # transform rows
-      Textus.hook(:check,  :name) { |store:|                  ... }   # doctor check
-      Textus.hook(:put,    :name, keys: ["..."])                      # lifecycle listener
-                                  { |store:, key:, envelope:| ... }
-      ```
-
-      Events: :intake, :reduce, :check (rpc — return value used)
-              :put, :deleted, :refreshed, :built, :accepted, :published,
-              :mv, :reject, :loaded,
-              :refresh_began, :refresh_failed, :refresh_detached (pub-sub — return discarded)
+      Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)
+              :entry_put, :entry_deleted, :entry_refreshed, :entry_renamed,
+              :build_completed, :proposal_accepted, :proposal_rejected,
+              :file_published, :store_loaded,
+              :refresh_started, :refresh_failed, :refresh_backgrounded (pub-sub — return discarded)
 
       See SPEC.md §5.10 for the full table.
     MD

data/lib/textus/intro.rb

@@ -13,17 +13,17 @@ module Textus
     ZONE_PURPOSES = {
       "identity" => "slow-changing identity; human-only writes",
       "working" => "active project state; humans, AI, and scripts share this surface",
-      "inbox" => "declared external inputs; script-refreshed via actions",
+      "intake" => "declared external inputs; script-refreshed via actions",
       "review" => "AI proposals awaiting human accept",
       "output" => "build-computed outputs; never hand-edited",
     }.freeze
 
     WRITE_FLOWS = {
       "human" => "edit files in identity/working zones, then 'textus put KEY --as=human'",
-      "ai" => "propose changes by writing 'review.*' entries with --as=ai and a 'proposal:' frontmatter block; " \
-              "a human runs 'textus accept' to apply",
-      "script" => "refresh inbox entries with 'textus refresh KEY --as=script' (uses the entry's declared action)",
-      "build" => "'textus build' computes output entries from projections; output files are never hand-edited",
+      "agent" => "propose changes by writing 'review.*' entries with --as=agent and a 'proposal:' frontmatter block; " \
+                 "a human runs 'textus accept' to apply",
+      "runner" => "refresh intake entries with 'textus refresh KEY --as=runner' (uses the entry's declared action)",
+      "builder" => "'textus build' computes output entries from projections; output files are never hand-edited",
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
@@ -37,14 +37,14 @@ module Textus
       { "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', 'key migrate'" },
+      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid', 'key normalize'" },
       { "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 inbox entry" },
+      { "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" => "policy", "summary" => "inspect effective policies: 'policy list', 'policy explain KEY'" },
+      { "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'" },
@@ -74,7 +74,7 @@ module Textus
 
     def self.entries_for(store)
       store.manifest.entries.map do |e|
-        derived = store.manifest.zone_writers(e.zone).include?("build")
+        derived = store.manifest.zone_writers(e.zone).include?("builder")
         {
           "key" => e.key,
           "zone" => e.zone,