hecks 3.5.0 → 3.6.0

data/lib/hecks/doors/mcp_door.rb

@@ -1,6 +1,8 @@
 require "json"
 require_relative "../../hecks"
 require_relative "../cli/mcp"
+require_relative "mcp_door/tool_definitions"
+require_relative "mcp_door/tool_calls"
 
 module Hecks
   module Doors
@@ -18,211 +20,7 @@ module Hecks
     module McpDoor
       PROTOCOL_VERSION = "2024-11-05".freeze
 
-      SUMMARY_PROPERTY = {
-        type:        "string",
-        description: "One line: why this call is happening. Required — it is what makes the audit trail legible later."
-      }.freeze
-
-      DOMAIN_PROPERTY = {
-        type:        "string",
-        description: "The domain directory, containing a .hecksagon (e.g. \"examples/banking\"). The `domains` tool " \
-                     "lists what's available."
-      }.freeze
-
-      ARGS_PROPERTY = {
-        type:        "object",
-        description: "The command/query's declared arguments, nested value-object literals included " \
-                     "(e.g. {\"reference\":{\"value\":\"BUG#1\"}})."
-      }.freeze
-
-      SOURCE_PROPERTY = {
-        type:        "string",
-        enum:        Hecks::Storehouse::SOURCE_TAGS,
-        description: "Optional: who is calling, for the audit log `follow` reads back."
-      }.freeze
-
-      ROLE_PROPERTY = {
-        type:        "string",
-        description: "Bind a caller identity for the call's duration, so a role-gated command's authorization is " \
-                     "checked rather than merely documented. Required by `dispatch` for any command that declares a " \
-                     "role — omitting it refuses the call rather than running it unchecked. Also required if " \
-                     "`actor_id` is given."
-      }.freeze
-
-      ACTOR_ID_PROPERTY = {
-        type:        "string",
-        description: "Optional, alongside `role`: WHO holds that role — once the domain attaches Governance, checked " \
-                     "against a real Governance::RoleAssignment instead of a bare string match. Requires `role`."
-      }.freeze
-
-      TOOLS = [
-        {
-          name:        "dispatch",
-          description: "Issue a command against a booted domain — or, with `steps`, several in one call. `command` is " \
-                       "the short or qualified verb name (the catalog/describe tools show what's available). Set " \
-                       "`dry_run: true` to check whether it WOULD succeed without committing anything. Answers the " \
-                       "record's id, its resulting state, and the events it announced — or a structured refusal, " \
-                       "never a crash.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain:   DOMAIN_PROPERTY,
-              command:  { type: "string", description: "The command's short or qualified name, e.g. \"open_account\". " \
-                                                       "Ignored when `steps` is given." },
-              args:     ARGS_PROPERTY,
-              summary:  SUMMARY_PROPERTY,
-              source:   SOURCE_PROPERTY,
-              role:     ROLE_PROPERTY,
-              actor_id: ACTOR_ID_PROPERTY,
-              dry_run:  { type: "boolean", description: "Preview only — check the command would succeed, commit nothing. " \
-                                                        "Ignored when `steps` is given." },
-              steps:    {
-                type:        "array",
-                description: "Run several commands in one call, in order. Each item: {command, args}. When given, " \
-                             "`command`/`args`/`dry_run` above are ignored.",
-                items:       {
-                  type:       "object",
-                  properties: { command: { type: "string" }, args: ARGS_PROPERTY },
-                  required:   %w[command]
-                }
-              }
-            },
-            required:   %w[domain summary]
-          }
-        },
-        {
-          name:        "query",
-          description: "Ask a declared question of a booted domain. `question` is the short or qualified query name. " \
-                       "Answers the row array the query itself declares.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain:   DOMAIN_PROPERTY,
-              question: { type: "string", description: "The query's short or qualified name." },
-              args:     ARGS_PROPERTY,
-              summary:  SUMMARY_PROPERTY,
-              source:   SOURCE_PROPERTY,
-              role:     ROLE_PROPERTY,
-              actor_id: ACTOR_ID_PROPERTY
-            },
-            required:   %w[domain question summary]
-          }
-        },
-        {
-          name:        "events",
-          description: "What actually HAPPENED, with payloads, to one aggregate/record — events THIS DOOR witnessed " \
-                       "(every real dispatch ever routed through it, sourced from its own audit log — not a full " \
-                       "domain-wide event-sourcing replay). Distinct from `state` (what's stored now) and `history` " \
-                       "(append-only operation snapshots, no payload). Narrow with `aggregate` and (requires " \
-                       "`aggregate`) `id`; `limit` keeps only the most recent.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain:    DOMAIN_PROPERTY,
-              aggregate: { type: "string", description: "Narrow to one aggregate, e.g. \"Account\"." },
-              id:        { type: "string", description: "Narrow to one record's own events. Requires `aggregate`." },
-              limit:     { type: "integer", description: "Keep only the most recent N events. Omit for all of them." }
-            },
-            required:   %w[domain]
-          }
-        },
-        {
-          name:        "state",
-          description: "Read what an aggregate actually has stored, no verb involved. Pass `id` for one record; " \
-                       "omit it to list every record the aggregate currently holds.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain:    DOMAIN_PROPERTY,
-              aggregate: { type: "string", description: "The aggregate's name, e.g. \"Account\"." },
-              id:        { type: "string", description: "A specific record's id. Omit to list every record." },
-              summary:   SUMMARY_PROPERTY
-            },
-            required:   %w[domain aggregate summary]
-          }
-        },
-        {
-          name:        "catalog",
-          description: "Zoom level one: every aggregate a domain declares, and every command/query name each " \
-                       "answers to. No summary needed — this changes nothing and commits nothing to any log.",
-          inputSchema: {
-            type:       "object",
-            properties: { domain: DOMAIN_PROPERTY },
-            required:   %w[domain]
-          }
-        },
-        {
-          name:        "describe",
-          description: "Zoom level two: one aggregate's full contract — every command's arguments, the states it " \
-                       "may be issued from, and every way it can refuse. Omit `aggregate` for the whole domain.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain:    DOMAIN_PROPERTY,
-              aggregate: { type: "string", description: "Narrow to one aggregate. Omit for the whole domain." }
-            },
-            required:   %w[domain]
-          }
-        },
-        {
-          name:        "validate",
-          description: "Zoom level three: is this domain's wiring sound — every bind names a declared aggregate, " \
-                       "every adapter satisfies its port, the default adapter is usable. {valid:false, error:…} " \
-                       "on a real wiring defect, never a bare crash. Set `deep: true` to also model-check the IR " \
-                       "for dead lifecycle transitions, unreachable saga states, and dispatches to nowhere.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain: DOMAIN_PROPERTY,
-              deep:   { type: "boolean", description: "Also run the static model checker (lifecycle/saga/policy IR)." }
-            },
-            required:   %w[domain]
-          }
-        },
-        {
-          name:        "domains",
-          description: "Zoom level zero: every domain directory found under a root (default \"examples\"), so a " \
-                       "caller who doesn't already know a path can find one.",
-          inputSchema: {
-            type:       "object",
-            properties: { under: { type: "string", description: "Root directory to scan. Defaults to \"examples\"." } }
-          }
-        },
-        {
-          name:        "history",
-          description: "The full write history for every aggregate in a domain — every operation an append-only " \
-                       "adapter ever recorded, not just current state. An aggregate on a non-append-only adapter " \
-                       "answers an empty history honestly.",
-          inputSchema: {
-            type:       "object",
-            properties: { domain: DOMAIN_PROPERTY },
-            required:   %w[domain]
-          }
-        },
-        {
-          name:        "behaviors",
-          description: "Run a domain's hand-curated `.behaviors` example tests and report pass/fail/error per test. " \
-                       "`target` is a single `.behaviors` file or a directory to sweep.",
-          inputSchema: {
-            type:       "object",
-            properties: { target: { type: "string", description: "A .behaviors file, or a directory to sweep." } },
-            required:   %w[target]
-          }
-        },
-        {
-          name:        "follow",
-          description: "Tail this door's own audit log for a domain — the last `limit` dispatch/query/state/dry-run " \
-                       "calls made through it, each carrying its summary, source, and outcome.",
-          inputSchema: {
-            type:       "object",
-            properties: {
-              domain: DOMAIN_PROPERTY,
-              limit:  { type: "integer", description: "How many recent entries to return. Defaults to 20." }
-            },
-            required:   %w[domain]
-          }
-        }
-      ].freeze
+      TOOLS = ToolDefinitions::TOOLS
 
       NOTES = [
         "Identity is self-asserted: role:/actor_id: are claims made by the caller and are not verified.",
@@ -230,6 +28,14 @@ module Hecks
         "domain: boots real Ruby under #{Storehouse::BOOT_ROOT}; anyone who can write to stdin can run it."
       ].freeze
 
+      # The method that answers each JSON-RPC method that has a response.
+      REPLIES = {
+        "initialize" => :initialize_result,
+        "tools/list" => :tools_list,
+        "tools/call" => :tools_call,
+        "ping"       => :ping_result
+      }.freeze
+
       module_function
 
       # Read once, so a bad setting refuses to start the door before anything is
@@ -247,23 +53,23 @@ module Hecks
         McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
         $stdout.sync = true
 
-        $stdin.each_line do |line|
-          line = line.strip
-          next if line.empty?
+        $stdin.each_line { |line| answer_line(line.strip) }
+      end
 
-          begin
-            request = JSON.parse(line)
-          rescue JSON::ParserError => e
-            send_error(nil, -32_700, "Parse error: #{e.message}")
-            next
-          end
+      # Answers one request line; a line that is not JSON is a parse error, not a crash.
+      def answer_line(line)
+        return if line.empty?
 
-          begin
-            handle(request)
-          rescue StandardError => e
-            send_error(request["id"], -32_603, "Internal error: #{e.class}: #{e.message}")
-          end
-        end
+        handle_safely(JSON.parse(line))
+      rescue JSON::ParserError => e
+        send_error(nil, -32_700, "Parse error: #{e.message}")
+      end
+
+      # Handles a request, answering an internal error rather than ending the door.
+      def handle_safely(request)
+        handle(request)
+      rescue StandardError => e
+        send_error(request["id"], -32_603, "Internal error: #{e.class}: #{e.message}")
       end
 
       # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a restricted
@@ -274,7 +80,12 @@ module Hecks
         path = Storehouse.confine!(scope.admit_domain!(domain), "domain")
         return Hecks.boot(path, install_doors: false) unless scope.restricted?
 
-        resident = (@resident ||= {})
+        resident_boot(path)
+      end
+
+      # The runtime a restricted door keeps for `path`, booted again once its files change.
+      def resident_boot(path)
+        resident    = (@resident ||= {})
         fingerprint = Storehouse.fingerprint(path)
         return resident[path][:runtime] if resident[path] && resident[path][:fingerprint] == fingerprint
 
@@ -282,68 +93,10 @@ module Hecks
         resident[path][:runtime]
       end
 
-      # One `when` per tool, so the shared `rescue` catches every branch's escape
-      # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
-      def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
-        case name
-        when "dispatch" then dispatch_tool(args)
-        when "query" then query_tool(args)
-        when "events"
-          Storehouse.events(runtime: boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
-                            limit: args["limit"])
-        when "state"
-          Storehouse.state(runtime: boot(args["domain"]), aggregate: args["aggregate"],
-                           summary: args["summary"], id: args["id"])
-        when "catalog"
-          Storehouse.catalog(runtime: boot(args["domain"]))
-        when "describe"
-          Storehouse.describe(runtime: boot(args["domain"]), aggregate: args["aggregate"])
-        when "validate"
-          Storehouse.validate(domain: scope.admit_domain!(args["domain"]), deep: args["deep"] == true)
-        when "domains"
-          Storehouse.domains(under: args["under"] || "examples")
-        when "history"
-          Storehouse.history(runtime: boot(args["domain"]))
-        when "behaviors"
-          Storehouse.behaviors(target: args["target"])
-        when "follow"
-          Storehouse.follow(runtime: boot(args["domain"]), limit: args["limit"] || 20)
-        else
-          { ok: false, error: "no such tool: #{name.inspect} — known: #{TOOLS.map { |t| t[:name] }.join(', ')}" }
-        end
-      rescue StandardError => e
-        # A defect, not a refusal: reaching here means a bad domain path or an
-        # argument shape `Doors::JsonDoor` could not symbolize.
-        { ok: false, error: "#{e.class}: #{e.message}" }
-      end
-
-      # A question, once the scope has admitted its arguments.
-      def query_tool(args)
-        scope.admit_arguments!(args["args"])
-        Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
-                         summary: args["summary"], args: args["args"] || {}, source: args["source"],
-                         role: args["role"], actor_id: args["actor_id"])
-      end
-
-      # A single command or a batch, once the scope has admitted every command in it.
-      def dispatch_tool(args)
-        runtime = boot(args["domain"])
-        if args["steps"]
-          scope.admit_steps!(runtime, args["steps"])
-          Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
-                                    source: args["source"], role: args["role"], actor_id: args["actor_id"])
-        else
-          scope.admit_command!(runtime, args["command"], args["args"])
-          Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
-                              args: args["args"] || {}, source: args["source"],
-                              dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
-        end
-      end
-
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
-        call_tool(name, scope.with_default_domain(args))
+        ToolCalls.call(name, scope.with_default_domain(args))
       end
 
       # One line per allowed command: what it takes and the role it declares, read from the booted
@@ -371,32 +124,33 @@ module Hecks
         puts JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
       end
 
+      # Answers one JSON-RPC request. A notification has no id and gets no response.
       def handle(request)
         id     = request["id"]
         method = request["method"]
-        params = request["params"] || {}
+        reply  = REPLIES[method]
+        return send_response(id, public_send(reply, request["params"] || {})) if reply
 
-        case method
-        when "initialize"
-          send_response(id, {
-                          protocolVersion: PROTOCOL_VERSION,
-                          capabilities:    { tools: {} },
-                          serverInfo:      { name: CLI::Mcp::SERVER, version: "1.1.0" }
-                        })
-        when "notifications/initialized"
-          nil # a notification — no id, no response
-        when "tools/list"
-          served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
-          guide = command_guide
-          send_response(id, { tools: served.map { |tool| scope.present(tool, guide) } })
-        when "tools/call"
-          send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
-        when "ping"
-          send_response(id, {})
-        else
-          send_error(id, -32_601, "Method not found: #{method}") unless id.nil?
-        end
+        send_error(id, -32_601, "Method not found: #{method}") unless id.nil? || method == "notifications/initialized"
       end
+
+      def initialize_result(_params)
+        { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },
+          serverInfo: { name: CLI::Mcp::SERVER, version: "1.1.0" } }
+      end
+
+      # The tools this door's scope permits, each presented with the command guide.
+      def tools_list(_params)
+        served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
+        guide  = command_guide
+        { tools: served.map { |tool| scope.present(tool, guide) } }
+      end
+
+      def tools_call(params)
+        tool_result(answer_tool(params["name"], params["arguments"] || {}))
+      end
+
+      def ping_result(_params) = {}
     end
   end
 end

data/lib/hecks/doors/mcp_door_scope/argument_policy.rb

@@ -0,0 +1,92 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Doors
+    class McpDoorScope
+      # What a restricted door lets an argument say: a denied name is refused, a path must resolve
+      # inside the root with symlinks followed, and a git ref must be a plain name.
+      module ArgumentPolicy
+        module_function
+
+        # Checks every argument in `args`, nested or not, and refuses the first one the policy
+        # forbids.
+        #
+        # @param args [Hash, Array, nil] the arguments as the caller gave them
+        # @param label [String] how the door describes its mode, for the refusal
+        # @raise [Runtime::TypeMismatch] on the first argument refused
+        def admit!(args, label)
+          each_argument(args) do |name, value|
+            if DENIED_ARGUMENTS.include?(name)
+              refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
+            end
+            admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
+            admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
+          end
+        end
+
+        # Yields every argument name with its value, descending into nested objects and lists, so
+        # `{"file" => {"value" => "x"}}` is checked the way `{"file" => "x"}` is.
+        def each_argument(args, &visit)
+          case args
+          when Hash
+            args.each do |name, value|
+              yield(name.to_s, value)
+              each_argument(value, &visit)
+            end
+          when Array
+            args.each { |item| each_argument(item, &visit) }
+          end
+        end
+
+        # A value written as an object of one field (`{"value" => "x"}`) is that field's value.
+        def scalar(value)
+          return value unless value.is_a?(Hash)
+
+          value.fetch("value") { value.fetch(:value, value) }
+        end
+
+        def refuse!(name, label, why)
+          raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this door runs in #{label} and #{why}"
+        end
+
+        def admit_path!(name, value, label)
+          Array(scalar(value)).flat_map { |item| item.to_s.split(",") }.reject(&:empty?).each do |path|
+            next if !path.include?(":") && inside_root?(path)
+
+            refuse!(name, label, "passes a path only when it resolves inside #{Storehouse::BOOT_ROOT} " \
+                                 "and holds no colon: #{path.inspect}")
+          end
+        end
+
+        def admit_ref!(name, value, label)
+          ref = scalar(value).to_s
+          return if ref.match?(PLAIN_REF) && !ref.include?("..")
+
+          refuse!(name, label, "passes only a plain git ref: #{ref.inspect}")
+        end
+
+        def inside_root?(path)
+          root = resolve_real(Storehouse::BOOT_ROOT)
+          resolved = resolve_real(File.expand_path(path, Storehouse::BOOT_ROOT))
+          resolved == root || resolved.start_with?("#{root}#{File::SEPARATOR}")
+        end
+
+        # The real path of `path`, symlinks followed: of the whole path when it exists, else of its
+        # deepest existing parent with the missing names put back, so a link above a file that does
+        # not exist yet still shows where the file would land.
+        def resolve_real(path)
+          missing = []
+          current = File.expand_path(path)
+          until File.exist?(current)
+            parent = File.dirname(current)
+            break if parent == current
+
+            missing.unshift(File.basename(current))
+            current = parent
+          end
+          File.join(File.realpath(current), *missing)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door_scope/env_problems.rb

@@ -0,0 +1,55 @@
+module Hecks
+  module Doors
+    class McpDoorScope
+      # What is wrong with the `HECKS_DOOR_*` variables a door was spawned with, as the sentences
+      # that refuse to start it.
+      module EnvProblems
+        module_function
+
+        # Every problem in `env`: a variable the door does not take, then those of the mode.
+        def setting_problems(env)
+          known = [TOOLS_VARIABLE, DOMAINS_VARIABLE, COMMANDS_VARIABLE]
+          problems = (env.keys.select { |name| name.start_with?(ENV_PREFIX) } - known).map do |name|
+            "environment #{name} is not accepted; the door takes only #{known.join(", ")}"
+          end
+          problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE], env[COMMANDS_VARIABLE])
+        end
+
+        def mode_problems(tools, domains, commands)
+          return stray_problems(domains, commands) if tools.nil?
+          unless MODES.include?(tools)
+            return ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the values are #{MODES.map(&:inspect).join(" and ")}"]
+          end
+
+          problems = []
+          if split_paths(domains.to_s).empty?
+            problems << "#{TOOLS_VARIABLE}=#{tools} needs #{DOMAINS_VARIABLE}, the domains this door may read"
+          end
+          problems + command_problems(tools, commands)
+        end
+
+        def stray_problems(domains, commands)
+          stray = { DOMAINS_VARIABLE => domains, COMMANDS_VARIABLE => commands }.compact.keys
+          return [] if stray.empty?
+
+          ["#{stray.join(" and ")} set without #{TOOLS_VARIABLE}=#{READERS} or #{TOOLS_VARIABLE}=#{COMMANDS}; " \
+           "they only narrow a restricted door"]
+        end
+
+        def command_problems(tools, commands)
+          if tools == COMMANDS && split_names(commands).empty?
+            ["#{TOOLS_VARIABLE}=#{COMMANDS} needs #{COMMANDS_VARIABLE}, the commands this door may dispatch"]
+          elsif tools == READERS && !commands.nil?
+            ["#{COMMANDS_VARIABLE} is set in reader mode; it only narrows a commands door"]
+          else
+            []
+          end
+        end
+
+        def split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
+
+        def split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+      end
+    end
+  end
+end

data/lib/hecks/doors/mcp_door_scope/presenter.rb

@@ -0,0 +1,78 @@
+module Hecks
+  module Doors
+    class McpDoorScope
+      # A tool definition as `tools/list` shows it to one door, and the notes the door starts with.
+      module Presenter
+        module_function
+
+        # The tool as `tools/list` shows it. A door that serves one domain makes `domain:` optional.
+        # On a commands door, `dispatch` also names the commands it serves as an enum, so a caller
+        # sees them as typed choices instead of finding out by being refused, and says what each
+        # takes and which role it declares.
+        #
+        # @param scope [McpDoorScope] the door's scope
+        # @param tool [Hash] a tool definition from `McpDoor::TOOLS`
+        # @param guide [Array<String>, nil] one line per allowed command
+        #   (`Storehouse.command_guide`)
+        # @return [Hash] the definition, narrowed for this door
+        def present(scope, tool, guide)
+          tool = domain_optional(tool, scope.default_domain) if scope.default_domain
+          return tool unless scope.commands_mode? && tool[:name] == "dispatch"
+
+          narrow_dispatch(tool, guide, scope.allowed_commands)
+        end
+
+        # `dispatch`, with the commands the door serves as typed choices.
+        def narrow_dispatch(tool, guide, commands)
+          properties = tool[:inputSchema][:properties]
+          steps      = properties[:steps]
+          narrowed   = properties.merge(command: with_enum(properties[:command], commands),
+                                        steps:   steps.merge(items: step_items(steps[:items], commands)))
+          tool.merge(description: dispatch_description(tool[:description], guide, commands),
+                     inputSchema: tool[:inputSchema].merge(properties: narrowed))
+        end
+
+        def domain_optional(tool, default)
+          schema = tool[:inputSchema]
+          return tool unless schema[:properties].key?(:domain)
+
+          note = "Optional: this door serves one domain, #{default}, and uses it when you leave this out."
+          properties = schema[:properties].merge(domain: schema[:properties][:domain].merge(description: note))
+          tool.merge(inputSchema: schema.merge(properties: properties, required: schema[:required] - ["domain"]))
+        end
+
+        def dispatch_description(base, guide, commands)
+          intro = "#{base} This door dispatches only the commands below, each with the role it declares: pass " \
+                  "that role as `role`. A command that takes `run` takes a key you choose, and the call answers " \
+                  "the record as it stands once its reactions have run; an argument marked * is required."
+          entries = Array(guide).empty? ? commands : guide
+          ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
+        end
+
+        def with_enum(property, commands)
+          property.merge(enum: commands)
+        end
+
+        def step_items(items, commands)
+          items.merge(properties: items[:properties].merge(command: with_enum(items[:properties][:command], commands)))
+        end
+
+        # What a reader door says about itself when it starts.
+        def reader_notes(domains)
+          ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(", ")}; " \
+           "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+           "domain: boots only #{DOMAINS_VARIABLE}: #{domains.join(", ")}.",
+           "Reader mode limits reach and identifies no one; it is not authentication."]
+        end
+
+        # What a commands door says about itself when it starts.
+        def commands_notes(domains, commands)
+          ["Commands mode (#{TOOLS_VARIABLE}=#{COMMANDS}): serves #{READER_TOOLS.join(", ")} and dispatch of only " \
+           "#{COMMANDS_VARIABLE}: #{commands.join(", ")}; refuses behaviors and every other tool.",
+           "domain: boots only #{DOMAINS_VARIABLE}: #{domains.join(", ")}.",
+           "Commands mode limits reach and identifies no one; role: stays self-asserted and it is not authentication."]
+        end
+      end
+    end
+  end
+end