hecks 3.2.0 → 3.3.0

data/lib/hecks/cli/interview_session.rb

@@ -24,36 +24,59 @@ module Hecks
 
       TASK = "You interview a subject matter expert, through the developer who sits beside them, about the " \
              "business domain called %<subject>s, so the developer can model it. Ask one plain-language " \
-             "question at a time about what the business keeps track of, what happens to it, and what must " \
-             "never happen. Use the expert's own words. Do not assume what kind of business it is, or an " \
+             "question at a time about what the business keeps track of, what each thing has, what happens to " \
+             "it and who does it, how it moves from one state to the next, and what must never happen. Use the " \
+             "expert's own words. Do not assume what kind of business it is, or an " \
              "industry, from the name of the domain: learn it from what the expert says. When you interpret " \
              "an answer, propose findings only with the verbs listed under `verbs`, using the argument " \
              "names given there, and nothing else.".freeze
 
       VERBS = {
-        "SME::Interview.ProposeThing"  => {
+        "SME::Interview.ProposeThing"      => {
           "meaning"   => "a thing the business keeps track of, and the field that identifies one of it",
           "arguments" => %w[name identifier]
         },
-        "SME::Interview.ProposeAction" => {
-          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense",
-          "arguments" => %w[name thing event creates]
+        "SME::Interview.ProposeAction"     => {
+          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense; " \
+                         "creates is true for the action that brings the thing into being; takes lists, comma " \
+                         "separated, the fields it needs to be told; by says who does it",
+          "arguments" => %w[name thing event creates takes by]
         },
-        "SME::Interview.ProposeRule"   => {
+        "SME::Interview.ProposeField"      => {
+          "meaning"   => "something a thing has; values lists, comma separated, what it may be when the " \
+                         "expert gave a closed set, and is left out for free text",
+          "arguments" => %w[thing name values]
+        },
+        "SME::Interview.ProposeTransition" => {
+          "meaning"   => "the state an action leaves a thing in, and the state it had to be in before; the " \
+                         "action that creates the thing has no from",
+          "arguments" => %w[thing action to from]
+        },
+        "SME::Interview.ProposeRule"       => {
           "meaning"   => "a rule the expert stated, in their own words",
           "arguments" => %w[statement]
         }
       }.freeze
 
-      # What each finding verb needs, and the SME commands that carry it out and decide it.
+      # What each finding verb needs, the fields it may leave out, and the SME commands that
+      # carry it out and decide it.
       KINDS = {
-        "SME::Interview.ProposeThing"  => { kind: "thing", fields: %w[name identifier], propose: :propose_thing!,
-                                           entity: "ThingFinding", accept: "AcceptThing", reject: "RejectThing" },
-        "SME::Interview.ProposeAction" => { kind: "action", fields: %w[name thing event creates],
-                                            propose: :propose_action!, entity: "ActionFinding",
-                                            accept: "AcceptAction", reject: "RejectAction" },
-        "SME::Interview.ProposeRule"   => { kind: "rule", fields: %w[statement], propose: :propose_rule!,
-                                          entity: "RuleFinding", accept: "AcceptRule", reject: "RejectRule" }
+        "SME::Interview.ProposeThing"      => { kind: "thing", fields: %w[name identifier], optional: [],
+                                           propose: :propose_thing!, entity: "ThingFinding",
+                                           accept: "AcceptThing", reject: "RejectThing" },
+        "SME::Interview.ProposeAction"     => { kind: "action", fields: %w[name thing event creates takes by],
+                                            optional: %w[creates takes by], propose: :propose_action!,
+                                            entity: "ActionFinding", accept: "AcceptAction", reject: "RejectAction" },
+        "SME::Interview.ProposeRule"       => { kind: "rule", fields: %w[statement], optional: [],
+                                          propose: :propose_rule!, entity: "RuleFinding",
+                                          accept: "AcceptRule", reject: "RejectRule" },
+        "SME::Interview.ProposeField"      => { kind: "field", fields: %w[thing name values], optional: %w[values],
+                                          propose: :propose_field!, entity: "FieldFinding",
+                                          accept: "AcceptField", reject: "RejectField" },
+        "SME::Interview.ProposeTransition" => { kind: "transition", fields: %w[thing action to from],
+                                                optional: %w[from], propose: :propose_transition!,
+                                                entity: "TransitionFinding", accept: "AcceptTransition",
+                                                reject: "RejectTransition" }
       }.freeze
 
       TRUE_WORDS = %w[true yes y 1].freeze
@@ -153,7 +176,7 @@ module Hecks
         return say("Ignored a proposal for #{proposal.verb}: not a finding I know.") unless config
 
         fields = fields_of(proposal, config)
-        missing = config[:fields].reject { |f| f == "creates" || fields[f].to_s.strip != "" }
+        missing = config[:fields].reject { |f| config[:optional].include?(f) || fields[f].to_s.strip != "" }
         return say("Ignored a #{config[:kind]} proposal with no #{missing.join(', ')}.") unless missing.empty?
 
         number = propose(config, fields) or return
@@ -166,7 +189,7 @@ module Hecks
         rows = proposal.arguments.to_h { |row| [row[:name].to_s, row[:value]] }
         fields = rows.slice(*config[:fields])
         fields["creates"] = TRUE_WORDS.include?(fields["creates"].to_s.downcase) if fields.key?("creates")
-        fields
+        fields.reject { |key, value| key != "creates" && config[:optional].include?(key) && value.to_s.strip.empty? }
       end
 
       def propose(config, fields)
@@ -192,19 +215,27 @@ module Hecks
         case config[:kind]
         when "thing" then "thing: #{fields['name']}, identified by #{fields['identifier']}"
         when "action" then "action: #{fields['name']} on #{fields['thing']}, announcing #{fields['event']}" \
-                           "#{', creating it' if fields['creates']}"
+                           "#{', creating it' if fields['creates']}#{action_extras(fields)}"
+        when "field" then "field: #{fields['name']} of #{fields['thing']}#{", one of #{fields['values']}" if fields['values']}"
+        when "transition" then "transition: #{fields['action']} leaves #{fields['thing']} #{fields['to']}" \
+                               "#{", from #{fields['from']}" if fields['from']}"
         else "rule: #{fields['statement']}"
         end
       end
 
+      # @api private
+      def action_extras(fields)
+        "#{", taking #{fields['takes']}" if fields['takes']}#{", by #{fields['by']}" if fields['by']}"
+      end
+
       # The plain prompt: findings typed by the developer, accepted as they are entered.
       def manual_findings
         loop do
-          kind = ask("Add a finding from that answer? thing, action or rule (enter to skip): ")
+          kind = ask("Add a finding from that answer? thing, action, rule, field or transition (enter to skip): ")
           kind = kind.to_s.strip.downcase
           break if kind.empty?
 
-          typed = typed_finding(kind) or next say("  I only know thing, action and rule.")
+          typed = typed_finding(kind) or next say("  I only know thing, action, rule, field and transition.")
           config = KINDS["SME::Interview.Propose#{kind.capitalize}"]
           number = propose(config, typed) or next
           decide(config, number, true)
@@ -216,6 +247,11 @@ module Hecks
         when "thing" then named("Name" => "name", "Identified by" => "identifier")
         when "action" then typed_action
         when "rule" then named("The rule, in the expert's words" => "statement")
+        when "field" then named({ "On which thing" => "thing", "Name" => "name",
+                                  "Values it may take, comma separated (enter for any)" => "values" }, %w[values])
+        when "transition" then named({ "On which thing" => "thing", "Caused by which action" => "action",
+                                       "Leaves it in the state" => "to",
+                                       "From the state (enter if it starts there)" => "from" }, %w[from])
         end
       end
 
@@ -224,9 +260,11 @@ module Hecks
         fields.merge("creates" => TRUE_WORDS.include?(ask("  Does it create the thing? [y/N] ").to_s.strip.downcase))
       end
 
-      def named(prompts)
+      def named(prompts, optional = [])
         fields = prompts.to_h { |label, key| [key, ask("  #{label}: ").to_s.strip] }
-        fields.values.all? { |v| !v.empty? } ? fields : nil
+        return nil unless fields.all? { |key, value| optional.include?(key) || !value.empty? }
+
+        fields.reject { |key, value| optional.include?(key) && value.empty? }
       end
 
       def suggest_enough
@@ -271,9 +309,11 @@ module Hecks
       end
 
       def accepted_state(plain)
-        { things:  InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
-          actions: InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates) },
-          rules:   InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
+        { things:      InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
+          actions:     InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates, :takes, :by) },
+          fields:      InterviewDraft.accepted(plain, :fields).map { |f| f.slice(:thing, :name, :values) },
+          transitions: InterviewDraft.accepted(plain, :transitions).map { |f| f.slice(:thing, :action, :to, :from) },
+          rules:       InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
       end
 
       # What the interview has not yet pinned down, in words a model can act on.
@@ -283,7 +323,18 @@ module Hecks
         gaps = things.reject { |t| actions.any? { |a| a[:thing] == t } }.map { |t| "nothing is yet said to happen to #{t}" }
         gaps += things.reject { |t| actions.any? { |a| a[:thing] == t && a[:creates] } }.map { |t| "nothing yet creates #{t}" }
         unplaced = actions.reject { |a| things.include?(a[:thing].to_s) }
-        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" }
+        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" } + shape_gaps(plain, things, actions)
+      end
+
+      # What a thing is not yet said to have, and how it moves from one state to the next.
+      def shape_gaps(plain, things, actions)
+        fields = InterviewDraft.accepted(plain, :fields)
+        steps = InterviewDraft.accepted(plain, :transitions)
+        bare = things.reject { |t| fields.any? { |f| f[:thing] == t } }
+        gaps = bare.map { |t| "nothing is yet said #{t} has, beyond its identifier" }
+        changing = things.select { |t| actions.count { |a| a[:thing] == t && !a[:creates] } > 1 }
+        unmoved = changing.reject { |t| steps.any? { |s| s[:thing] == t } }
+        gaps + unmoved.map { |t| "nothing yet says how #{t} moves from one state to the next" }
       end
 
       def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip

data/lib/hecks/cli/interview_shape.rb

@@ -0,0 +1,179 @@
+require_relative "../naming"
+
+module Hecks
+  module CLI
+    # What an interview's fields, command inputs and state changes become in a drafted aggregate
+    # (ADR 0088): its attributes and their value objects, the fields a command is told, a note of
+    # who does it, and the lifecycle.
+    #
+    # Pure, like `InterviewDraft`, which calls it: each method answers lines of bluebook text and
+    # writes none. A name is written as `InterviewDraft.word` writes it.
+    module InterviewShape
+      module_function
+
+      # The accepted fields of one thing, each with the type it will be written under. The
+      # identifier is already a field, and a lifecycle owns `status`, so neither is repeated.
+      #
+      # @param found [Array<Hash>] the accepted field findings that name the thing
+      # @param name [String] the thing's name, which no type may repeat
+      # @param identifier [String] the identifying field, snake-cased
+      # @param identifier_type [String] the type the identifier is written under
+      # @param lifecycle [Boolean] whether the thing has a lifecycle
+      # @return [Array<Hash>] each field's `name`, `type` and `values`
+      def fields(found, name, identifier, identifier_type, lifecycle:)
+        taken = [name, identifier_type]
+        found.filter_map { |finding| field_row(finding, taken, identifier, lifecycle) }.uniq { |row| row[:name] }
+      end
+
+      # The attribute lines of the fields: required when the creating action takes one, else
+      # optional.
+      #
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @param required [Array<String>] the field names the creating actions take
+      # @return [Array<String>] one line per field
+      def attributes(fields, required)
+        fields.map do |field|
+          suffix = required.include?(field[:name]) ? "" : ", optional: true"
+          "    attribute :#{field[:name]}, #{field[:type]}#{suffix}"
+        end
+      end
+
+      # The value object of each field, a blank line before each: a closed set when the expert
+      # listed two or more values, and free text otherwise.
+      #
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @return [Array<String>] the lines
+      def value_objects(fields)
+        fields.flat_map do |field|
+          rule = field[:values].size > 1 ? ", one_of: #{field[:values].inspect}" : ""
+          ["", "    value_object #{field[:type].inspect} do", "      attribute :value, String#{rule}", "    end"]
+        end
+      end
+
+      # The field names an action says it is told.
+      #
+      # @param action [Hash] an accepted action
+      # @return [Array<String>] snake-cased field names
+      def takes(action)
+        action[:takes].to_s.split(/\s*,\s*/).map { |text| Naming.snake(InterviewDraft.word(text)) }.reject(&:empty?)
+      end
+
+      # What an action is told that the thing has as a field, and what it names that the thing
+      # does not. The identifier is never counted: a command already carries it.
+      #
+      # @param action [Hash] an accepted action
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @param identifier [String] the identifying field, snake-cased
+      # @return [Array(Array<Hash>, Array<String>)] the fields it is told, and the names that have
+      #   no field
+      def inputs(action, fields, identifier)
+        known, unknown = (takes(action) - [identifier]).partition { |text| fields.any? { |field| field[:name] == text } }
+        [known.map { |text| fields.find { |field| field[:name] == text } }, unknown]
+      end
+
+      # @param inputs [Array<Hash>] the fields a command is told
+      # @return [Array<String>] a blank line and an attribute line for each, or none
+      def input_lines(inputs)
+        inputs.empty? ? [] : ["", *inputs.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }]
+      end
+
+      # @param inputs [Array<Hash>] the fields a command is told
+      # @return [Array<String>] a blank line and a `sets` line for each, or none
+      def assignment_lines(inputs)
+        inputs.empty? ? [] : ["", *inputs.map { |f| "      sets :#{f[:name]}" }]
+      end
+
+      # @param unknown [Array<String>] names an action is told that no accepted field has
+      # @return [Array<String>] a note for each
+      def unknown_lines(unknown)
+        unknown.map { |text| "      # TODO: takes #{text}, but no accepted field of that name." }
+      end
+
+      # Who may do an action, as the expert said it. It is a note, not a role: a role is only
+      # checked once the domain attaches Governance.
+      #
+      # @param action [Hash] an accepted action
+      # @return [Array<String>] the note, or none
+      def who_lines(action)
+        by = action[:by].to_s.strip
+        by.empty? ? [] : ["      # Who: #{by}. Declare it as a role once Governance is attached."]
+      end
+
+      # The lifecycle the accepted transitions describe. The state a creating action's step
+      # leads to is where a thing starts; a step for an action the thing does not have is kept
+      # as a comment.
+      #
+      # @param steps [Array<Hash>] the thing's accepted transitions
+      # @param creating [Array<Hash>] the accepted actions that create it
+      # @param rest [Array<Hash>] its other accepted actions
+      # @return [Array<String>] the lines, or none when no step and start state can be placed
+      def lifecycle(steps, creating, rest)
+        births = creating.map { |action| InterviewDraft.word(action[:name]) }
+        has = ->(names, step) { names.include?(InterviewDraft.word(step[:action])) }
+        starts, moves = steps.partition { |step| has.call(births, step) }
+        heres = rest.map { |action| InterviewDraft.word(action[:name]) }
+        placed, loose = moves.partition { |step| has.call(heres, step) }
+        placed = merged(placed)
+        start = beginning(starts, placed)
+        return [] if start.empty? || placed.empty?
+
+        ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
+         "    end", *loose.map { |step| loose_line(step) }]
+      end
+
+      # @api private
+      def field_row(finding, taken, identifier, lifecycle)
+        field = Naming.snake(InterviewDraft.word(finding[:name]))
+        return if field == identifier || (lifecycle && field == "status")
+
+        type = Naming.pascal(field)
+        type = "#{type}Value" while taken.include?(type)
+        taken << type
+        { name: field, type: type, values: finding[:values].to_s.split(/\s*,\s*|\s+or\s+/).map(&:strip).reject(&:empty?).uniq }
+      end
+
+      # One step for each action and state it leads to: the states it starts from are joined, and a
+      # step with no state to start from means it may be taken from any.
+      # @api private
+      def merged(steps)
+        steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
+          froms = group.map { |step| step[:from].to_s.strip }
+          group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
+        end
+      end
+
+      # The state a thing starts in: where its creating action's step leads, else the first state a
+      # change is said to start from.
+      # @api private
+      def beginning(starts, placed)
+        from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
+        state_word(starts.first&.fetch(:to) || from)
+      end
+
+      # @api private
+      def transition_line(step)
+        "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
+          "#{from_clause(step)}"
+      end
+
+      # @api private
+      def loose_line(step)
+        "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
+          "no accepted action has that name."
+      end
+
+      # The states a step may start from: none, one, or several.
+      # @api private
+      def from_clause(step)
+        states = step[:from].to_s.split(/\s*,\s*/).map { |text| state_word(text) }.reject(&:empty?)
+        return "" if states.empty?
+
+        states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(' ')}]"
+      end
+
+      # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
+      # @api private
+      def state_word(text) = text.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, "")
+    end
+  end
+end

data/lib/hecks/doors/cli_runner.rb

@@ -188,6 +188,7 @@ module Hecks
       # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted in
       def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
         rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
+        wait ||= LauncherOptions.settled?(launcher, spec)
         args = CliDoor.arguments(spec, rest)
 
         return answer_query(runtime, spec, args, wait) if spec[:kind] == :query
@@ -252,11 +253,23 @@ module Hecks
                       events: (events.empty? ? handle.events : events).map(&:name) }.merge(extra)
         if LauncherOptions.failed?(aggregate, state, launcher)
           field = aggregate.lifecycle.field
-          why  += ["#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"]
+          why  += [failure_sentence(aggregate, state, field)]
         end
         finish(JSON.pretty_generate(answer), why)
       end
 
+      # The sentence for a record that ended in a failure state: the state, then the record's own
+      # `refusal` when it keeps one, without the class name an adapter's failure carries.
+      def failure_sentence(aggregate, state, field)
+        sentence = "#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"
+        refusal  = state[:refusal]
+        refusal  = refusal.value if refusal.respond_to?(:value)
+        refusal  = refusal[:value] if refusal.is_a?(Hash)
+        return sentence if refusal.to_s.strip.empty?
+
+        "#{sentence}: #{refusal.to_s.strip.sub(/\A(\w+::)+\w+: /, '')}"
+      end
+
       # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
       def finish(text, reasons)
         reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]

data/lib/hecks/doors/launcher_options.rb

@@ -10,11 +10,10 @@ module Hecks
     # A `.world` that declares a `launcher` setting switches these on for that chapter; a
     # domain without one keeps the launcher's plain forms exactly:
     #
-    #     launcher "Launcher", run_keys: true, failure_states: %w[flagged failed],
-    #                          names: { "mcp" => "serve_mcp" }
-    #
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
+    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait` was
+    #   given, so a script gets their outcome in its exit status.
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
     # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
     module LauncherOptions
@@ -87,6 +86,17 @@ module Hecks
         [rest, wait]
       end
 
+      # Whether a command always waits for its reactions, as if `--wait` had been given.
+      #
+      # @param launcher [Hash, nil] the chapter's `launcher` setting
+      # @param spec [Hash] the command's projected spec
+      # @return [Boolean] true for a command the setting lists under `settled`
+      def settled?(launcher, spec)
+        return false unless launcher && spec[:kind] == :command
+
+        Array(launcher[:settled]).map(&:to_s).include?(spec[:short].to_s)
+      end
+
       # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists it
       # under `streams`, by the question's own name.
       #

data/lib/hecks/doors/mcp_door.rb

@@ -343,7 +343,20 @@ module Hecks
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
-        call_tool(name, args)
+        call_tool(name, scope.with_default_domain(args))
+      end
+
+      # One line per allowed command: what it takes and the role it declares, read from the booted
+      # domain the door serves. Nil when the door serves no single domain or it will not boot, so
+      # `tools/list` still answers, with the commands as a bare list.
+      def command_guide
+        return unless scope.commands_mode? && scope.default_domain
+
+        McpGuideCache.remember(scope.default_domain, scope.allowed_commands) do
+          Storehouse.command_guide(boot(scope.default_domain), scope.allowed_commands)
+        end
+      rescue StandardError
+        nil
       end
 
       def tool_result(payload)
@@ -374,7 +387,8 @@ module Hecks
           nil # a notification — no id, no response
         when "tools/list"
           served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
-          send_response(id, { tools: served.map { |tool| scope.present(tool) } })
+          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"

data/lib/hecks/doors/mcp_door_scope.rb

@@ -28,7 +28,8 @@ module Hecks
       # switch to, or flips a command from a preview to a change of state.
       DENIED_ARGUMENTS = %w[
         adapter artifact confirm expected from gem_only header health_path host no_wait npm_local
-        npm_only output path payload payload_file port rust_binary scheme state_path stdio url write
+        npm_only output path payload payload_file port rust_binary scheme stage_dir state_path stdio url
+        write
       ].freeze
 
       # Argument names whose values are paths (a comma-separated list for some). A restricted door
@@ -201,18 +202,40 @@ module Hecks
         end
       end
 
-      # The tool as `tools/list` shows it: on a commands door, `dispatch` names the commands it
-      # serves, so a caller sees them as an enum instead of finding out by being refused.
+      # The one domain a restricted door serves, when it serves exactly one: a call may leave
+      # `domain:` out and get it. Nil for an unrestricted door and for one that names several.
+      #
+      # @return [String, nil] the domain path as `HECKS_DOOR_DOMAINS` named it, resolved
+      def default_domain
+        @allowed_domains.first if restricted? && @allowed_domains.size == 1
+      end
+
+      # The arguments with the default domain filled in when the caller left it out.
+      #
+      # @param args [Hash] a tool call's arguments
+      # @return [Hash] `args`, with `"domain"` set when the door has a default and none was given
+      def with_default_domain(args)
+        return args unless default_domain && args["domain"].to_s.strip.empty?
+
+        args.merge("domain" => default_domain)
+      end
+
+      # 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 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(tool)
+      def present(tool, guide = nil)
+        tool = domain_optional(tool) if default_domain
         return tool unless commands_mode? && tool[:name] == "dispatch"
 
         properties = tool[:inputSchema][:properties]
         narrowed = properties.merge(command: with_enum(properties[:command]),
                                     steps:   properties[:steps].merge(items: step_items(properties[:steps][:items])))
-        tool.merge(description: "#{tool[:description]} This door dispatches only: #{allowed_commands.join(', ')}.",
+        tool.merge(description: dispatch_description(tool[:description], guide),
                    inputSchema: tool[:inputSchema].merge(properties: narrowed))
       end
 
@@ -287,6 +310,23 @@ module Hecks
         File.join(File.realpath(current), *missing)
       end
 
+      def domain_optional(tool)
+        schema = tool[:inputSchema]
+        return tool unless schema[:properties].key?(:domain)
+
+        note = "Optional: this door serves one domain, #{default_domain}, 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)
+        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? ? allowed_commands : guide
+        ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
+      end
+
       def with_enum(property)
         property.merge(enum: allowed_commands)
       end

data/lib/hecks/doors/mcp_guide_cache.rb

@@ -0,0 +1,75 @@
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../cache_dir"
+require_relative "../storehouse"
+require_relative "../bluebook/meta_validator/verdict_cache"
+
+module Hecks
+  module Doors
+    # Remembers the command guide a commands door builds for `tools/list`, so a door that starts
+    # again does not boot its domain to describe its commands. A client waits only a moment for a
+    # server's tools, and a boot at that point costs more than the wait.
+    #
+    # An entry is keyed by the domain directory's files, a digest of the hecks code, and the
+    # allowed commands, so a change to any of them builds a new guide. The file is JSON, read only
+    # from a directory and a file that only this user can write (the verdict cache's own check),
+    # and only when it is a list of strings: a guide is text an agent reads as instructions.
+    module McpGuideCache
+      module_function
+
+      # The guide for a domain and its allowed commands, from the cache or else from the block,
+      # which is then remembered. A cache that cannot be written is not an error: the next start
+      # builds the guide again.
+      #
+      # @param domain [String] the domain directory the guide describes
+      # @param commands [Array<String>] the allowed command names
+      # @yieldreturn [Array<String>, nil] the guide, built when none is remembered
+      # @return [Array<String>, nil] the guide
+      def remember(domain, commands)
+        file = File.join(dir, "#{key(domain, commands)}.json")
+        cached = read(file)
+        return cached if cached
+
+        guide = yield
+        write(file, guide) if guide.is_a?(Array) && guide.any?
+        guide
+      end
+
+      # @return [String] the directory entries live in
+      def dir = Hecks::CacheDir.path("mcp_door_guides")
+
+      # @param domain [String] the domain directory
+      # @param commands [Array<String>] the allowed command names
+      # @return [String] a hex SHA-256 over the domain's files, the hecks code and the commands
+      def key(domain, commands)
+        parts = [Storehouse.fingerprint(domain), Bluebook::MetaValidator::VerdictCache.code_digest,
+                 commands.sort.join(",")]
+        Digest::SHA256.hexdigest(parts.join("\0"))
+      end
+
+      # @param file [String] an entry's path
+      # @return [Array<String>, nil] the guide, or nil when absent, untrusted or malformed
+      def read(file)
+        return unless File.file?(file) && Bluebook::MetaValidator::VerdictCache.trusted?(file)
+
+        guide = JSON.parse(File.read(file))
+        guide if guide.is_a?(Array) && guide.all?(String)
+      rescue StandardError
+        nil
+      end
+
+      # @param file [String] an entry's path
+      # @param guide [Array<String>] the guide to remember
+      # @return [void]
+      def write(file, guide)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        temp = "#{file}.#{Process.pid}.tmp"
+        File.write(temp, JSON.generate(guide), perm: 0o600)
+        File.rename(temp, file)
+      rescue StandardError
+        FileUtils.rm_f(temp) if temp
+      end
+    end
+  end
+end

data/lib/hecks/doors.rb

@@ -2,7 +2,7 @@ module Hecks
   # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
   module Doors
     # The removal release of the `Facade` and `install_facade:` spellings.
-    REMOVAL = "3.2.0".freeze
+    REMOVAL = "3.4.0".freeze
 
     module_function