textus 0.43.1 → 0.45.1

data/lib/textus/cli/verb/get.rb

@@ -1,14 +1,15 @@
 module Textus
   class CLI
     class Verb
-      class Get < Verb
-        command_name "get"
-
+      class Get < Runner::Base
+        self.spec = Textus::Read::Get.contract
         option :as_flag, "--as=ROLE"
+        option :no_fetch, "--no-fetch"
 
-        def call(store)
+        def invoke(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = session_for(store).get_or_fetch(key)
+          kw = no_fetch.nil? ? {} : { fetch: false }
+          result = session_for(store).get(key, **kw)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

data/lib/textus/cli/verb/put.rb

@@ -1,14 +1,14 @@
 module Textus
   class CLI
     class Verb
-      class Put < Verb
-        command_name "put"
+      class Put < Runner::Base
+        self.spec = Textus::Write::Put.contract
 
         option :as_flag, "--as=ROLE"
         option :use_stdin, "--stdin"
         option :fetch_name, "--fetch=NAME"
 
-        def call(store)
+        def invoke(store)
           key = positional.shift or raise UsageError.new("put requires a key")
           raise UsageError.new("put requires --stdin in v1") unless use_stdin
 

data/lib/textus/cli/verb.rb

@@ -108,6 +108,9 @@ module Textus
       def session_for(store)
         store.as(resolved_role(store))
       end
+
+      # The input stream — the source for a `cli_stdin` envelope (ADR 0068).
+      attr_reader :stdin
     end
   end
 end

data/lib/textus/cli.rb

@@ -7,9 +7,15 @@ module Textus
     # declares `command_name "X"` and has no `parent_group` is a top-level
     # verb. Sorted alphabetically for stable help output. Adding a new
     # verb requires only a new file declaring its `command_name`.
+    #
+    # `k.name` gates out anonymous (Class.new) subclasses: real verbs are always
+    # named constants (generated Gen* or hand-authored classes), so this is a
+    # no-op in production but keeps throwaway test fixtures from leaking into the
+    # registry (and tripping the reconciliation guards order-dependently).
     def self.verbs
+      Runner.install!
       Verb.descendants
-          .select { |k| k.command_name && k.parent_group.nil? }
+          .select { |k| k.name && k.command_name && k.parent_group.nil? }
           .sort_by(&:command_name)
           .to_h { |k| [k.command_name, k] }
     end
@@ -91,7 +97,7 @@ module Textus
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
           textus fetch KEY
-          textus fetch stale [--prefix=KEY] [--zone=Z]
+          textus fetch all [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor

data/lib/textus/contract/around.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Contract
+    # Registry of named, stateful wrappers a verb may declare via `around :name`.
+    # A resource implements
+    #   `wrap(scope:, inputs:, session:) { |effective_inputs| ... }`:
+    # it may adjust the inputs before the call and post-process the result after
+    # — exactly what build's lock and pulse's cursor need, without a hand-authored
+    # CLI class (ADR 0068). `session:` is the dispatching session (nil for the
+    # sessionless CLI/Ruby surfaces, present for MCP), so a session-aware resource
+    # like the cursor can defer to the session's own state instead of its file.
+    module Around
+      @registry = {}
+
+      module_function
+
+      def register(name, resource)
+        @registry[name] = resource
+      end
+
+      def fetch(name)
+        @registry.fetch(name) { raise "no around resource registered: #{name.inspect}" }
+      end
+
+      def with(name, scope:, inputs:, session: nil, &call)
+        fetch(name).wrap(scope: scope, inputs: inputs, session: session, &call)
+      end
+    end
+  end
+end

data/lib/textus/contract/binder.rb

@@ -0,0 +1,88 @@
+module Textus
+  module Contract
+    # Raised when a required arg is absent from the bound input. Surface
+    # adapters translate this to their native error (MCP ToolError, CLI
+    # UsageError); a direct Ruby call lets it surface as-is.
+    class MissingArgs < Textus::Error
+      attr_reader :spec, :missing
+
+      def initialize(spec, missing)
+        @spec = spec
+        @missing = missing
+        super("missing_args", "#{spec.verb}: missing #{missing.map(&:wire).join(", ")}")
+      end
+    end
+
+    # The single argument binder for every surface (spike: collapses the three
+    # historical implementations — MCP::Catalog.map_args, CLI::Runner.call_args,
+    # and RoleScope's default-injection loop — into one algorithm).
+    #
+    # Input is a uniform `inputs` hash keyed by arg NAME (the use-case kwarg
+    # name, never the wire name): each surface normalizes its own raw transport
+    # shape (MCP JSON keyed by wire-name, CLI argv+flags, Ruby args+kwargs) into
+    # this hash. Binder owns the shared algorithm and nothing transport-specific:
+    #
+    #   1. validate every required arg is present in `inputs`;
+    #   2. for absentees, fall back to session_default (when a session is given)
+    #      then to the literal default; otherwise omit the arg entirely;
+    #   3. split into the (positional, keyword) pair to splat into the use-case,
+    #      routing by `arg.positional`.
+    #
+    # Returns `[positional_array, keyword_hash]` — exactly what
+    # `RoleScope#<verb>(*pos, **kw)` expects.
+    module Binder
+      module_function
+
+      # Validation is unconditional: a `required:` arg absent from `inputs` is a
+      # contract violation on every surface (ADR 0069). `required:` is now an
+      # honest contract invariant, not a surface policy — args the use-case
+      # treats as optional (e.g. `meta`, whose real requiredness lives in schema
+      # validation downstream) are declared `required: false`, so this check
+      # never fires spuriously and never needs an opt-out.
+      def bind(spec, inputs, session: nil)
+        missing = spec.required_args.reject { |a| inputs.key?(a.name) }
+        raise MissingArgs.new(spec, missing) unless missing.empty?
+
+        pos = []
+        kw  = {}
+        spec.args.each do |a|
+          if inputs.key?(a.name)
+            value = inputs[a.name]
+          elsif a.session_default && session
+            value = session.public_send(a.session_default)
+          elsif !a.default.nil?
+            value = a.default
+          else
+            next
+          end
+
+          if a.positional
+            pos << value
+          else
+            kw[a.name] = value
+          end
+        end
+        [pos, kw]
+      end
+
+      # Normalize an ordered positional list + a by-name keyword hash (the shape
+      # CLI argv+flags and Ruby args+kwargs both arrive in) into the uniform
+      # by-name `inputs` hash bind expects. Positionals beyond what was supplied
+      # are dropped so bind's required-check sees them as absent.
+      def inputs_from_ordered(spec, ordered_positionals, by_name_keywords)
+        names = spec.args.select(&:positional).map(&:name)
+        names.zip(ordered_positionals).to_h.compact.merge(by_name_keywords)
+      end
+
+      # Normalize a raw transport hash keyed by WIRE name (the shape MCP JSON
+      # arrives in) into the uniform by-name `inputs` hash bind expects. Keys
+      # not declared on the contract are ignored.
+      def inputs_from_wire(spec, raw)
+        raw ||= {}
+        spec.args.each_with_object({}) do |a, h|
+          h[a.name] = raw[a.wire.to_s] if raw.key?(a.wire.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/contract/resources/cursor.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Contract
+    module Resources
+      # Reads the persisted file cursor as the `since` default when the caller
+      # did not supply one, runs pulse, then persists the returned cursor.
+      # Replaces CLI::Verb::Pulse's hand-coded CursorStore read/write (ADR 0068).
+      #
+      # A session-bearing surface (MCP) carries its own cursor via the contract's
+      # `session_default: :cursor`, so this defers entirely when a session is
+      # present — it is the sessionless CLI/Ruby surfaces that need the file.
+      class Cursor
+        def wrap(scope:, inputs:, session:)
+          return yield(inputs) if session
+
+          store = Textus::CursorStore.new(root: scope.container.root, role: scope.role)
+          effective = inputs.key?(:since) ? inputs : inputs.merge(since: store.read)
+          result = yield(effective)
+          store.write(result["cursor"]) if result.is_a?(Hash) && result["cursor"]
+          result
+        end
+      end
+    end
+  end
+end
+
+Textus::Contract::Around.register(:cursor, Textus::Contract::Resources::Cursor.new)

data/lib/textus/contract/sources.rb

@@ -0,0 +1,39 @@
+require "json"
+
+module Textus
+  module Contract
+    # CLI-only input acquisition. Transforms entries of the uniform `inputs`
+    # hash that declare a `source:`/`coerce:`, and builds `inputs` from a
+    # `cli_stdin` envelope — so put/propose/migrate/rule_lint/audit need no
+    # hand-authored CLI class (ADR 0068). MCP receives typed JSON, so these
+    # never run there.
+    module Sources
+      module_function
+
+      # Apply per-arg :file sources (value is a path -> file contents) and
+      # :coerce callables to a by-name inputs hash. Returns a new hash.
+      def acquire(spec, inputs)
+        spec.args.each_with_object(inputs.dup) do |a, h|
+          next unless h.key?(a.name)
+
+          h[a.name] = File.read(h[a.name]) if a.source == :file
+          h[a.name] = a.coerce.call(h[a.name]) if a.coerce
+        end
+      end
+
+      # Parse a cli_stdin :json envelope into a by-name inputs hash, mapping
+      # envelope keys (wire-names) to arg names.
+      def from_stdin(spec, stream)
+        return {} unless spec.cli_stdin == :json
+
+        raw = stream.read.to_s
+        return {} if raw.strip.empty? # no envelope piped -> required args surface as missing
+
+        envelope = JSON.parse(raw)
+        spec.args.each_with_object({}) do |a, h|
+          h[a.name] = envelope[a.wire.to_s] if envelope.key?(a.wire.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/contract/view.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Contract
+    # Renders a use-case result for a surface, using the verb's declared view
+    # (falling back to the default). The single replacement for the old
+    # response/cli_response split and the Proc#arity sniff: views are always
+    # called as (result, inputs); a one-parameter view ignores inputs.
+    module View
+      module_function
+
+      def render(spec, surface, result, inputs)
+        spec.view(surface).call(result, inputs)
+      end
+    end
+  end
+end

data/lib/textus/contract.rb

@@ -8,7 +8,21 @@ module Textus
     # use-case as a positional (e.g. `get(key)`); otherwise as a keyword.
     # `session_default` names a zero-arg method on `Textus::Session` (Symbol)
     # that supplies the value when the wire arg is absent; `nil` means no default.
-    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description)
+    # `wire_name` is the name the arg carries on the wire (MCP JSON property / CLI
+    # envelope key) when it must differ from the use-case kwarg `name` — e.g. `put`
+    # takes the `meta:` kwarg but exposes `_meta` on the wire to match what `get`
+    # returns and what the CLI `--stdin` envelope already speaks (ADR 0057).
+    # `source: :file` (CLI only) reads the arg's value as a path -> file
+    # contents; `coerce:` is a callable applied to the raw value (CLI only);
+    # `cli_default:` supplies a CLI-specific default that diverges from the
+    # contract `default` the agent surfaces use (`:__unset` sentinel = none).
+    Arg = Data.define(
+      :name, :type, :required, :positional, :session_default,
+      :description, :wire_name, :default, :source, :coerce, :cli_default
+    ) do
+      # The name used on the wire (defaults to the kwarg name).
+      def wire = wire_name || name
+    end
 
     JSON_TYPES = {
       String => "string", Integer => "integer", Hash => "object",
@@ -19,8 +33,21 @@ module Textus
       JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
     end
 
-    Spec = Data.define(:verb, :summary, :args, :surfaces, :response) do
+    Spec = Data.define(:verb, :summary, :args, :surfaces, :views, :cli, :around, :cli_stdin) do
       def mcp? = surfaces.include?(:mcp)
+      def cli? = surfaces.include?(:cli)
+
+      # The output shaper for a surface; falls back to the default view. Every
+      # view is invoked uniformly as `view.call(result, inputs)` — a view that
+      # declares one parameter ignores `inputs` (procs tolerate extra args).
+      def view(surface = :default) = views[surface] || views.fetch(:default)
+
+      # Operator-facing command path. Defaults to the verb token; grouped verbs
+      # declare e.g. `cli "schema show"`.
+      def cli_path = cli || verb.to_s
+      def cli_words = cli_path.split
+      def cli_group = cli_words.size > 1 ? cli_words.first : nil
+      def cli_leaf  = cli_words.last
 
       def required_args = args.select(&:required)
 
@@ -31,9 +58,9 @@ module Textus
         props = args.to_h do |a|
           h = { "type" => Contract.json_type(a.type) }
           h["description"] = a.description if a.description
-          [a.name.to_s, h]
+          [a.wire.to_s, h]
         end
-        { type: "object", properties: props, required: required_args.map { |a| a.name.to_s } }
+        { type: "object", properties: props, required: required_args.map { |a| a.wire.to_s } }
       end
     end
 
@@ -70,18 +97,56 @@ module Textus
         end
       end
 
-      def arg(name, type, required: false, positional: false, session_default: nil, description: nil)
+      def cli(path = nil)
+        if path
+          raise "contract already built; declare cli before reading .contract" if defined?(@__contract) && @__contract
+
+          @__cli = path.to_s
+        else
+          @__cli
+        end
+      end
+
+      # Declare a stateful wrapper resource (Contract::Around) to run around
+      # dispatch — e.g. `around :cursor` (pulse) or `around :build_lock` (build).
+      def around(name = nil)
+        return @__around unless name
+
+        raise "contract already built; declare around before reading .contract" if defined?(@__contract) && @__contract
+
+        @__around = name
+      end
+
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil, default: nil, source: nil, coerce: nil, cli_default: :__unset) # rubocop:disable Metrics/ParameterLists,Layout/LineLength
         raise "contract already built; declare args before reading .contract" if defined?(@__contract) && @__contract
 
         (@__args ||= []) << Arg.new(
           name: name, type: type, required: required,
-          positional: positional, session_default: session_default, description: description
+          positional: positional, session_default: session_default,
+          description: description, wire_name: wire_name, default: default,
+          source: source, coerce: coerce, cli_default: cli_default
         )
       end
 
-      def response(&blk)
-        @__response = blk if blk
-        @__response || ->(v) { v }
+      # Verb-level: the CLI reads its inputs from a stdin envelope of this mode.
+      # `:json` parses stdin as a JSON object and distributes its keys to args
+      # by wire-name. nil means no stdin acquisition.
+      def cli_stdin(mode = :__read)
+        return @__cli_stdin if mode == :__read
+
+        raise "contract already built; declare cli_stdin before reading .contract" if defined?(@__contract) && @__contract
+
+        @__cli_stdin = mode
+      end
+
+      # Declare an output shaper. `view { ... }` is the default (MCP + Ruby);
+      # `view(:cli) { ... }` overrides for the CLI. Both receive (result, inputs).
+      def view(surface = :default, &blk)
+        return (@__views ||= {})[surface] unless blk
+
+        raise "contract already built; declare view before reading .contract" if defined?(@__contract) && @__contract
+
+        (@__views ||= {})[surface] = blk
       end
 
       def contract?
@@ -97,7 +162,10 @@ module Textus
           summary: @__summary,
           args: (@__args || []).freeze,
           surfaces: (@__surfaces || []).freeze,
-          response: response,
+          views: ((@__views ||= {})[:default] ||= ->(v, _i) { v }) && @__views,
+          cli: @__cli,
+          around: @__around,
+          cli_stdin: @__cli_stdin,
         )
       end
       # rubocop:enable Naming/MemoizedInstanceVariableName

data/lib/textus/dispatcher.rb

@@ -11,14 +11,13 @@ module Textus
       mv: Textus::Write::Mv,
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
-      publish: Textus::Write::Publish,
+      build: Textus::Write::Build,
       fetch: Textus::Write::FetchWorker,
       fetch_all: Textus::Write::FetchAll,
-      retention_sweep: Textus::Write::RetentionSweep,
+      retain: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
-      get_or_fetch: Textus::Read::GetOrFetch,
       list: Textus::Read::List,
       where: Textus::Read::Where,
       uid: Textus::Read::Uid,
@@ -29,14 +28,14 @@ module Textus
       deps: Textus::Read::Deps,
       rdeps: Textus::Read::Rdeps,
       pulse: Textus::Read::Pulse,
-      policy_explain: Textus::Read::PolicyExplain,
+      rule_explain: Textus::Read::RuleExplain,
+      rule_list: Textus::Read::RuleList,
       published: Textus::Read::Published,
-      schema: Textus::Read::SchemaEnvelope,
+      schema_show: Textus::Read::SchemaEnvelope,
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       retainable: Textus::Read::Retainable,
-      rules: Textus::Read::Rules,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

data/lib/textus/hooks/context.rb

@@ -28,8 +28,17 @@ module Textus
         @scope
       end
 
-      # read
-      def get(key)                = @scope.get(key)
+      # read — a deliberately pure-observation surface: NOTHING here fetches
+      # (`list`/`deps`/`freshness` don't either). The invariant is that a hook
+      # observes current state and never triggers an I/O cascade. `get` bypasses
+      # the read-through behavior (ADR 0062) and reads with fetch:false directly,
+      # because read-through inside a hook would: (1) fire fetch events → hooks →
+      # unbounded reentrancy; (2) spawn the orchestrator's threads/fork from
+      # inside a hook callback; (3) probe the single-flight fetch lock its own
+      # enclosing fetch may hold (deadlock); (4) inject network latency into
+      # every hook read. With the merged Read::Get class, `fetch:false` (the
+      # method default) guarantees no orchestrator is built.
+      def get(key)                = pure_reader.call(key)
       def list(**)                = @scope.list(**)
       def deps(key)               = @scope.deps(key)
       def freshness(key)          = @scope.freshness(key)
@@ -50,6 +59,19 @@ module Textus
       def inspect
         "#<Textus::Hooks::Context role=#{@role} correlation_id=#{@correlation_id}>"
       end
+
+      private
+
+      def pure_reader
+        @pure_reader ||= Textus::Read::Get.new(
+          container: @scope.container,
+          call: Textus::Call.build(
+            role: @scope.role,
+            correlation_id: @scope.correlation_id,
+            dry_run: @scope.dry_run?,
+          ),
+        )
+      end
     end
   end
 end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -7,16 +7,18 @@ module Textus
       verb     :key_delete_prefix
       summary  "Bulk-delete every leaf key under prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix,  String, required: true
-      arg :dry_run, :boolean
-      response(&:to_h)
+      cli      "key delete-prefix"
+      arg :prefix,  String, required: true, positional: true, description: "every leaf key under this dotted prefix is deleted"
+      arg :dry_run, :boolean, default: true, cli_default: false,
+                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(prefix:, dry_run: false)
+      def call(prefix, dry_run: true)
         raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
 
         leaves = Read::List.new(container: @container)

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -8,17 +8,19 @@ module Textus
       verb     :key_mv_prefix
       summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
       surfaces :cli, :ruby, :mcp
-      arg :from_prefix, String, required: true
-      arg :to_prefix,   String, required: true
-      arg :dry_run,     :boolean
-      response(&:to_h)
+      cli      "key mv-prefix"
+      arg :from_prefix, String, required: true, positional: true, description: "dotted prefix whose leaf keys are renamed"
+      arg :to_prefix,   String, required: true, positional: true, description: "dotted prefix the keys are renamed to"
+      arg :dry_run,     :boolean, default: true, cli_default: false,
+                                  description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(from_prefix:, to_prefix:, dry_run: false)
+      def call(from_prefix, to_prefix, dry_run: true)
         raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
 
         leaves = list_leaves_under(from_prefix)

data/lib/textus/maintenance/migrate.rb

@@ -10,16 +10,18 @@ module Textus
       verb     :migrate
       summary  "Run a YAML migration plan (multi-op)."
       surfaces :cli, :ruby, :mcp
-      arg :plan_yaml, String, required: true
-      arg :dry_run,   :boolean
-      response(&:to_h)
+      arg :plan_yaml, String, required: true, positional: true, source: :file,
+                              description: "path to the YAML migration plan (zone_mv, key_mv_prefix, key_delete_prefix ops run in order)"
+      arg :dry_run, :boolean, default: true, cli_default: false,
+                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(plan_yaml:, dry_run: false)
+      def call(plan_yaml, dry_run: true)
         raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
         raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
 
@@ -40,11 +42,13 @@ module Textus
       private
 
       def invoke_op(op_name, op_hash, dry_run:)
-        kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
         klass = op_class(op_name)
-        klass.new(
-          container: @container, call: @call,
-        ).call(**kwargs)
+        inputs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+        # Each op now carries positional args (from/to, from_prefix/to_prefix,
+        # prefix); split the YAML fields into (positional, keyword) via the op's
+        # own contract so we call its #call signature correctly (ADR 0066/0068).
+        args, kwargs = Textus::Contract::Binder.bind(klass.contract, inputs)
+        klass.new(container: @container, call: @call).call(*args, **kwargs)
       end
 
       def op_class(op_name)

data/lib/textus/maintenance/rule_lint.rb

@@ -11,8 +11,10 @@ module Textus
       verb     :rule_lint
       summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
       surfaces :cli, :ruby, :mcp
-      arg :candidate_yaml, String, required: true
-      response(&:to_h)
+      cli      "rule lint"
+      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
+                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container = container

data/lib/textus/maintenance/zone_mv.rb

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

data/lib/textus/manifest/entry/base.rb

@@ -86,7 +86,7 @@ module Textus
         end
 
         # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Write::Publish, or nil to skip.
+        # Write::Build, or nil to skip.
         def publish_via(pctx, prefix: nil)
           publish_mode.publish(pctx, prefix: prefix)
         end