textus 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15b2e8bcfb3e83425617ee187705b88ad99c1f96671a7ad04a8394073f98065d
-  data.tar.gz: e0711f287c8739fcc2e5f9507fd5637b9c63159b2d8e364f9d65f338138ff432
+  metadata.gz: 96c684d8a670835fb687a321abb85838ec831e95e8672b7f03453266e2224b65
+  data.tar.gz: d9332836814f977824413a7bc379666cfd830f182d2c44a9ed5a71d1e7336513
 SHA512:
-  metadata.gz: 74ec9edba22fdd7884c7bf1a16b9f73a636524c11f889824a516775857294ea674ebd6f6fe9b0a4d98028d30cf5673b51c376760968baa4d8413c83a33475484
-  data.tar.gz: c097ccd942039828754bd70ae2f457e172ca88166c318c72199138e126301aa4432cec318ff77c456a73de4176c0e6fe65160cca899111dcd27785adc9eff62c
+  metadata.gz: cbfdd6527a26f2e8fb97cdde2cc99c5df4d36839af1f426bf52156335187d4b48ecbe45af1b271031861bc225d100676522082da6f74c171555bd5cf7bd0b227
+  data.tar.gz: 38ac5fff2e9209c8bbbc15745a1ddbd840736ddcc23363c6a61099926b79807a9ccb49630a98b69f6ed41cf2a15d3272bd586f6bc749ea381e4d24158eeb597a

data/CHANGELOG.md

@@ -11,6 +11,58 @@ tracks both additive improvements and breaking protocol bumps independently.
 
 ## Unreleased
 
+## 0.40.0 — 2026-06-02 — `publish_each` owns multi-file leaf subtrees ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md))
+
+No `textus/3` wire-format change — publish is repo-local materialization. The
+publish *unit* is derived from the entry's existing `index_filename`, not a new
+manifest key (SPEC §4, §5.3).
+
+### Added
+
+- **`publish_each` copies a leaf's whole subtree when the entry declares `index_filename` ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md)).** textus can now own a prose-heavy, multi-file artifact (e.g. a Claude Code Agent Skill: `SKILL.md` + `commands.md` + `references/*`) as a single addressable unit. An entry *without* `index_filename` still publishes one file per leaf (unchanged); an entry *with* `index_filename` treats each leaf as a directory and copies the whole subtree — ignore-filtered (ADR 0042), preserving in-leaf layout, one sentinel per file. Siblings ride along at publish time only: they are never enumerated, addressable, or proposable (the key↔path bijection is preserved). On rebuild, managed orphans under a leaf are pruned (file + sentinel); **unmanaged files are never deleted**. The build envelope grows a `pruned` array.
+- **`doctor` flags orphaned publish targets.** A new `orphaned_publish_targets` check reports a published file whose recorded source no longer exists in the store (a renamed or removed whole leaf) — drift that per-entry `build` won't revisit.
+
+### Changed
+
+- **BREAKING (pre-1.0): directory-leaf `publish_each` semantics ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md)).** An entry with `index_filename` + `publish_each` whose leaf directories contain siblings previously published *only the index file*; it now publishes the whole subtree. This breaks no correct usage — it is either the dropped-siblings defect this fixes, or a template that named a file rather than a directory, which the validator now **rejects loudly** at manifest load. **Migration:** a directory-leaf `publish_each` template must name the target *directory* — drop a trailing index filename (`.../{leaf}/SKILL.md` → `.../{leaf}`) or any file extension (`.../{leaf}.md` → `.../{leaf}`), and use `{leaf}` or `{key}` (not `{basename}`/`{ext}`, which are file-only).
+- **Role names are now a closed set `{human, agent, automation}` ([ADR 0045](docs/architecture/decisions/0045-close-role-name-set.md)).** A manifest declaring any other role name is rejected at load with `unknown role name '<x>' (allowed: human, agent, automation)`. `Role::NAMES` is the single source of truth; each role's `can:` capabilities remain fully tunable. Principal multiplicity moves to the `owner:` field (`owner: human:patrick`). Stricter `textus/3` validation in `Schema.validate_roles!` — no protocol bump; all shipped manifests already comply.
+- **Hook event tables consolidated into `Textus::Hooks::Catalog` (single source
+  of truth).** `EventBus` and `RpcRegistry` no longer keep their own event
+  tables; both registries, the Loader DSL router, and internal consumers read
+  `Catalog::PUBSUB` / `Catalog::RPC` directly. This removes the drift-prone
+  `EventBus::RPC_EVENTS` literal that could silently fall out of sync with
+  `RpcRegistry`'s events and weaken the cross-registry guards. Internal
+  refactor — no `textus/3` wire-format change.
+
+## 0.39.1 — 2026-06-01 — Feed ergonomics: `feeds.machine` env snapshot + intake cookbook ([ADR 0043](docs/architecture/decisions/0043-feed-ergonomics-without-breaking-core-purity.md))
+
+No `textus/3` wire-format change. `textus init` scaffolds an additional
+`nested` feed entry; core intake still makes no implicit network calls
+(SPEC §5.4).
+
+### Added
+
+- **`textus init` scaffolds `feeds.machines.*` with a local env snapshot
+  (ADR 0043).** Generated stores get a `nested` feed entry capturing ambient
+  machine context (git HEAD/branch/dirty state, `now`, versions) as an explicit,
+  user-owned snapshot — keeping ambient state out of `boot`/`pulse` (which stay
+  side-effect-free per ADR 0037) and out of `quarantine` (which means external
+  bytes pending validation, where the freshness model does not apply).
+
+### Documentation
+
+- **Multi-machine environment-scan cookbook recipe** demonstrating the nested
+  `feeds.machines.*` pattern.
+- **Examples** updated to use the `feeds.machine` env snapshot, matching
+  `textus init` output.
+- **README flow diagram** redesigned to group writers and colour-code roles.
+- **How-to fixes** for zone-rename drift in the agents-mcp guide and the
+  `:publish` event name.
+
+### Internal
+
+- Removed the legacy `ARCHITECTURE.md` redirect stub.
+
 ## 0.39.0 — 2026-06-01 — Native ignore patterns for entry enumeration ([ADR 0042](docs/architecture/decisions/0042-native-ignore-patterns-for-entry-enumeration.md))
 
 No `textus/3` wire-format change. Manifest schema gains one optional, backward-compatible key (`ignore:`); existing manifests are unaffected.

data/README.md

@@ -27,20 +27,33 @@ Three actors write to your repo today:
 
 ```mermaid
 flowchart LR
-    human(["human"]) -->|author| knowledge["knowledge<br/>(canon)"]
-    agent(["agent"]) -->|keep| notebook["notebook<br/>(workspace)"]
+    subgraph writers["writers — who can write"]
+        direction TB
+        human(["human"])
+        agent(["agent"])
+        automation(["automation"])
+    end
+
+    human -->|author| knowledge["knowledge<br/>(canon)"]
+    agent -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    proposals ==>|human accept| knowledge
-    automation(["automation"]) -->|fetch| feeds["feeds<br/>(quarantine)"]
+    automation -->|fetch| feeds["feeds<br/>(quarantine)"]
     automation -->|build| artifacts["artifacts<br/>(derived)"]
+
+    proposals ==>|human accept| knowledge
     feeds -.->|projection source| artifacts
     knowledge -.->|projection source| artifacts
 
-    classDef anchor fill:#1f6feb,stroke:#1f6feb,color:#fff;
+    classDef actor fill:#238636,stroke:#2ea043,color:#fff;
+    classDef gate fill:#9e6a03,stroke:#bb8009,color:#fff;
+    classDef anchor fill:#1f6feb,stroke:#388bfd,color:#fff;
+    class human,agent,automation actor;
+    class proposals gate;
     class knowledge anchor;
 ```
 
 *Each actor writes only into its own lane; low-trust input climbs to authoritative lanes only by passing a guarded transition (an agent's proposal needs a human `accept`).*
+*Colour legend: **green** = writers · **amber** = the review gate (`proposals`) · **blue** = the trust anchor (`knowledge`).*
 
 The point of those lanes is to **build context you can trust**. Place each lane on two axes — how durable it is, and how much you can rely on it without review — and the value shows up as a climb: the high-trust corner (durable *and* authoritative = `knowledge`) is the one place nothing is *written* directly. It's *earned* by crossing the `accept` gate.
 

data/SPEC.md

@@ -242,7 +242,7 @@ For `nested: true`, the recursive glob matches the format's extension (markdown
 
 A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.textus/zones/skills/ask/references/algorithm.md` is not enumerated. Resolving `skills.ask` returns the `SKILL.md` path. `index_filename:` requires `nested: true`; the value must be a bare basename (no slashes).
 
-**Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to byte-copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
+**Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
 
 | Variable     | Value                                                                                  |
 |--------------|----------------------------------------------------------------------------------------|
@@ -251,7 +251,15 @@ A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.text
 | `{key}`      | Full dotted key.                                                                       |
 | `{ext}`      | Primary extension for the entry's format, without the leading dot (`md`/`json`/`yaml`/`txt`). |
 
-Validation at manifest load: any unknown variable raises `UsageError`; the template MUST reference at least one of `{leaf}`, `{basename}`, `{key}` (otherwise every leaf would clobber the same target). A computed target outside the repo root is refused at build time with `PublishError`. Example:
+The publish *unit* is derived from the entry's shape, which `index_filename:` already declares (ADR 0046) — there is no separate tree-vs-file key:
+
+- **Entry *without* `index_filename`** — a leaf is a *file*. `publish_each:` names a file target and one file is byte-copied per leaf.
+- **Entry *with* `index_filename`** — a leaf is a *directory*. `publish_each:` names a directory target, and the **whole leaf subtree** is copied: every file under the leaf directory (the index plus its siblings) is byte-copied to `<target_dir>/<path-relative-to-leaf>`, preserving in-leaf layout. Siblings are opaque payload — they are never enumerated, addressable, or proposable; only the index is a key. The entry's `ignore:` globs (§4, ADR 0042) filter the copied set. Each copied file gets its own sentinel. On rebuild, files under the target that are textus-managed but no longer produced by the current source are **pruned** (file + sentinel); files with no sentinel are never deleted.
+
+Validation at manifest load: any unknown variable raises `UsageError`; a computed target outside the repo root is refused at build time with `PublishError`. The discriminator requirement depends on the leaf shape:
+
+- **File-leaf** templates MUST reference at least one of `{leaf}`, `{basename}`, `{key}` (otherwise every leaf would clobber the same target).
+- **Directory-leaf** templates (entry has `index_filename`) MUST reference `{leaf}` or `{key}`, and MUST NOT use `{basename}` or `{ext}` (file-only). Because the target is a directory, the template's final segment MUST NOT be the `index_filename` (the `.../{leaf}/SKILL.md` footgun — it would copy the subtree into a directory literally named `SKILL.md/`) and MUST NOT carry a file extension (e.g. `.../{leaf}.md`); both are rejected at load with a fix-the-template message.
 
 ```yaml
 - key: working.skills
@@ -259,10 +267,12 @@ Validation at manifest load: any unknown variable raises `UsageError`; the templ
   zone: working
   schema: skill
   nested: true
-  publish_each: "skills/{basename}/SKILL.md"
+  index_filename: SKILL.md
+  publish_each: "skills/{leaf}"
+  ignore: ["*.tmp", ".DS_Store"]
 ```
 
-A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/working/skills/writing/voice-writer.md`) publishes to `skills/voice-writer/SKILL.md`.
+A leaf at `working.skills.voice-writer` (a directory `.textus/zones/working/skills/voice-writer/` containing `SKILL.md`, `commands.md`, and `references/*`) publishes its whole subtree under `skills/voice-writer/`, preserving layout.
 
 **`inject_boot:`.** A derived entry with a `template:` MAY declare `inject_boot: true`. When `textus build` materializes the entry, it merges the `textus boot` envelope (§9) into the projection data under the key `boot`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus boot` exposes.
 
@@ -468,7 +478,7 @@ When the entry is recomputed, textus copies the in-store file byte-for-byte to e
 
 A sentinel is written for each published file at `<store_root>/sentinels/<target-relative-to-repo>.textus-managed.json`, recording `source`, `target`, the target's sha256, and `mode: "copy"`. Sentinels live under the store rather than beside the consumer file so target directories stay clean. The sentinel exists so out-of-band edits can be detected on the next publish — textus refuses to clobber a destination that is not either missing or marked as managed. Legacy sibling sentinels (`<target>.textus-managed.json`) are still recognised as managed and are migrated to the new location on the next publish.
 
-**Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
+**Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The publish unit follows the entry's `index_filename` (ADR 0046): a file-leaf entry byte-copies one file per leaf; a directory-leaf entry (with `index_filename`) byte-copies the leaf's whole subtree — one row and one sentinel **per file** — applying the entry's `ignore:` filter, and prunes textus-managed files under the target that the current source no longer produces (never touching unmanaged files). The build envelope grows a `published_leaves` array — one row per published file, with `key`, `source`, and `target` — alongside the existing `built` array, plus a `pruned` array listing any orphaned managed files removed on this build. Targets that would resolve outside the repo root are refused.
 
 ### 5.4 Intake (declared, fetched via registered intake handler)
 

data/lib/textus/boot.rb

@@ -236,10 +236,10 @@ module Textus
 
     def self.hooks_for_container_internal(rpc:, events:)
       sections = {}
-      Hooks::RpcRegistry::EVENTS.each_key do |event|
+      Hooks::Catalog::RPC.each_key do |event|
         sections[event.to_s] = rpc.names(event).map(&:to_s).sort
       end
-      Hooks::EventBus::EVENTS.each_key do |event|
+      Hooks::Catalog::PUBSUB.each_key do |event|
         sections[event.to_s] = events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
       end
       sections

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

@@ -7,8 +7,12 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
+          role = store.manifest.policy.actor_for("build") or
+            raise UsageError.new(
+              "no role holds the 'build' capability",
+              hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
+            )
           Textus::Ports::BuildLock.with(root: store.root) do
-            role = store.manifest.policy.roles_with_capability("build").first || "automation"
             ops = store.as(role)
             result = ops.publish(prefix: prefix)
             emit(result)

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

@@ -16,12 +16,12 @@ module Textus
           end
 
           rows = []
-          Textus::Hooks::RpcRegistry::EVENTS.each_key do |event|
+          Textus::Hooks::Catalog::RPC.each_key do |event|
             store.rpc.names(event).each do |name|
               rows << { "event" => event.to_s, "mode" => "rpc", "name" => name.to_s }
             end
           end
-          Textus::Hooks::EventBus::EVENTS.each_key do |event|
+          Textus::Hooks::Catalog::PUBSUB.each_key do |event|
             store.events.pubsub_handlers(event).each do |h|
               row = { "event" => event.to_s, "mode" => "pubsub", "name" => h[:name].to_s }
               row["keys"] = Array(h[:keys]) if h[:keys]
@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "automation"
+                  "key" => e.key, "as" => defn["as"] || Textus::Role::AUTOMATION
                 }
               end
             end

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

@@ -0,0 +1,35 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags published files whose recorded source no longer exists in the
+      # store. Per-leaf prune (ADR 0046) reconciles within a still-present
+      # leaf; a renamed or removed *whole* leaf orphans its entire target
+      # directory, which a per-entry build won't revisit. This check catches
+      # that drift without making `build` scan globally.
+      class OrphanedPublishTargets < Check
+        def call
+          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          return [] unless File.directory?(sdir)
+
+          repo_root = File.dirname(root)
+          store = Textus::Ports::SentinelStore.new
+          glob = File.join(sdir, "**", "*#{Textus::Ports::SentinelStore::SUFFIX}")
+          Dir.glob(glob).filter_map do |spath|
+            sentinel = store.load(spath, repo_root)
+            next nil if sentinel.nil? || sentinel.source.nil?
+            next nil if File.exist?(sentinel.source)
+
+            {
+              "code" => "publish.orphaned_target",
+              "level" => "warning",
+              "subject" => sentinel.target,
+              "message" => "published file #{sentinel.target} has no source in the store " \
+                           "(recorded source #{sentinel.source} is gone) — likely a renamed or removed leaf",
+              "fix" => "remove the stale copy and its sentinel: rm '#{sentinel.target}' '#{spath}'",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -24,6 +24,7 @@ module Textus
       Check::RuleAmbiguity,
       Check::HandlerAllowlist,
       Check::FetchLocks,
+      Check::OrphanedPublishTargets,
       Check::ProposalTargets,
     ].freeze
 

data/lib/textus/hooks/catalog.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    # The single source of truth for hook event names and their required
+    # kwargs. EventBus, RpcRegistry, and the Loader DSL router all read these
+    # tables directly — the registries do not keep their own copies. Catalog
+    # references no other constant, so it has no load-order cycle, which is
+    # what removed the previous drift hazard (EventBus held a hard-coded
+    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
+    module Catalog
+      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
+      PUBSUB = {
+        entry_put: %i[ctx key envelope],
+        entry_deleted: %i[ctx key],
+        entry_fetched: %i[ctx key envelope change],
+        entry_renamed: %i[ctx key from_key to_key envelope],
+        build_completed: %i[ctx key envelope sources],
+        proposal_accepted: %i[ctx key target_key],
+        proposal_rejected: %i[ctx key target_key],
+        file_published: %i[ctx key envelope source target],
+        store_loaded: %i[ctx],
+        fetch_started: %i[ctx key mode],
+        fetch_failed: %i[ctx key error_class error_message],
+        fetch_backgrounded: %i[ctx key started_at budget_ms],
+      }.freeze
+
+      # RPC events: single handler, return value matters, receive `caps:`.
+      RPC = {
+        resolve_intake: %i[caps config args],
+        transform_rows: %i[caps rows config],
+        validate: %i[caps],
+      }.freeze
+    end
+  end
+end

data/lib/textus/hooks/event_bus.rb

@@ -7,23 +7,6 @@ module Textus
 
       class HookTimeout < StandardError; end
 
-      EVENTS = {
-        entry_put: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        build_completed: %i[ctx key envelope sources],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        file_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        fetch_started: %i[ctx key mode],
-        fetch_failed: %i[ctx key error_class error_message],
-        fetch_backgrounded: %i[ctx key started_at budget_ms],
-      }.freeze
-
-      RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
-
       def initialize(error_log: ErrorLog.new)
         @pubsub = Hash.new { |h, k| h[k] = [] }
         @error_handlers = []
@@ -36,9 +19,9 @@ module Textus
 
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if Catalog::RPC.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        required = Catalog::PUBSUB[event_sym] or raise UsageError.new("unknown event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         if missing.any?

data/lib/textus/hooks/loader.rb

@@ -12,7 +12,7 @@ module Textus
         # Pubsub registration — delegates to EventBus.
         # Also handles RPC event names by delegating to RpcRegistry.
         def on(event, name, keys: nil, &)
-          if Hooks::RpcRegistry::EVENTS.key?(event.to_sym)
+          if Hooks::Catalog::RPC.key?(event.to_sym)
             @rpc.register(event, name, &)
           else
             @events.register(event, name, keys: keys, &)

data/lib/textus/hooks/rpc_registry.rb

@@ -3,23 +3,15 @@
 module Textus
   module Hooks
     class RpcRegistry
-      EVENTS = {
-        resolve_intake: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-
-      PUBSUB_EVENTS = EventBus::EVENTS.keys.freeze
-
       def initialize
         @table = Hash.new { |h, k| h[k] = {} }
       end
 
       def register(event, name, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if Catalog::PUBSUB.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
+        required = Catalog::RPC[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
@@ -38,7 +30,7 @@ module Textus
 
       # Invoke a registered callable, injecting `caps:` only if the callable
       # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
-      # `caps:`-alternative) are rejected at registration time, not here.
+      # `store:`) are rejected at registration time, not here.
       def invoke(event, name, caps:, **other)
         blk = callable(event, name)
         sig = Signature.new(blk)

data/lib/textus/init/templates/machine_intake.rb

@@ -0,0 +1,45 @@
+# .textus/hooks/machine_intake.rb
+# Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
+# entry from manifest.yaml if you don't want it.
+# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus fetch` (never
+# on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
+# `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
+# (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
+# ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
+Textus.hook do |reg|
+  reg.on(:resolve_intake, :machines) do |config:, args:, **|
+    machine = args[:leaf_segments].first or
+      raise "fetch a host leaf, e.g. `textus fetch feeds.machines.local`"
+    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
+    unless (spec["via"] || "local").to_s == "local"
+      raise "machine #{machine}: only `via: local` is scaffolded — see " \
+            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
+    end
+
+    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
+    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
+    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
+    { content: {
+      # git_* describe THIS repo on the control host — only meaningful for `local`.
+      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
+      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
+      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
+      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
+      "captured_at"    => Time.now.utc.iso8601,
+      "os"             => RbConfig::CONFIG["host_os"],
+      "arch"           => RbConfig::CONFIG["host_cpu"],
+      "ruby_version"   => RUBY_VERSION,
+      "runtimes"       => {                                 # versions only; nil when not installed
+        "node"   => ver.call("node --version"),
+        "python" => ver.call("python3 --version"),
+        "go"     => ver.call("go version"),
+      },
+      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
+        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
+        "apt"  => count.call("dpkg-query -f '.\n' -W"),
+      },
+      "textus_version" => Textus::VERSION,
+      "protocol"       => Textus::PROTOCOL,
+    } }
+  end
+end

data/lib/textus/init.rb

@@ -1,4 +1,5 @@
 require "fileutils"
+require "pathname"
 
 module Textus
   module Init
@@ -21,6 +22,26 @@ module Textus
         - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
         - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
         - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
+        # A per-host snapshot, pulled by `textus fetch feeds.machines.local --as=automation`.
+        # Nested so it grows to a fleet — add feeds.machines.<host> leaves over SSH
+        # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
+        # gitignored (machine info can be sensitive/noisy) but still protocol-readable
+        # via `textus get feeds.machines.local`. Delete to opt out. (ADR 0043)
+        - key: feeds.machines
+          path: feeds/machines
+          zone: feeds
+          format: yaml
+          nested: true
+          tracked: false
+          kind: intake
+          intake:
+            handler: machines
+            config:
+              machines:
+                local: { via: local }
+      rules:
+        - match: feeds.machines.**
+          fetch: { ttl: 1h, on_stale: warn } # meaningful on a long-running server
     YAML
 
     HOOKS_README = <<~MD
@@ -91,12 +112,31 @@ module Textus
         File.write(File.join(dir, ".gitkeep"), "")
       end
       File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
+      scaffold_dir = File.expand_path("init/templates", __dir__)
+      File.write(File.join(target_root, "hooks", "machine_intake.rb"),
+                 File.read(File.join(scaffold_dir, "machine_intake.rb")))
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
-      File.write(File.join(target_root, ".gitignore"), Textus::Layout::GITIGNORE)
+      File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end
+
+    # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now
+    # derived from the manifest: the run subtree plus every `tracked: false`
+    # entry's resolved path (ADR 0043).
+    def self.derived_gitignore(target_root)
+      manifest = Textus::Manifest.load(target_root)
+      root = Pathname.new(target_root)
+      untracked = manifest.data.entries.reject(&:tracked?).map do |e|
+        if e.nested? # a whole subtree of leaf files (feeds.machines.* → zones/feeds/machines/)
+          "#{File.join("zones", e.path)}/"
+        else
+          Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
+        end
+      end
+      Textus::Layout.gitignore_body(untracked_paths: untracked)
+    end
   end
 end

data/lib/textus/layout.rb

@@ -33,9 +33,22 @@ module Textus
       File.join(audit_dir(root), "audit.log")
     end
 
-    GITIGNORE = <<~GITIGNORE
-      # textus runtime artifacts — safe to delete, never commit
-      #{RUN}/
-    GITIGNORE
+    # The store's `.gitignore` body. Always ignores the runtime subtree
+    # (`.run/`, ADR 0038); when given untracked entry paths (entries marked
+    # `tracked: false`), it also lists those so they stay protocol-readable but
+    # uncommitted (ADR 0043, refining 0038). Generated, never hand-kept — no
+    # drift between the manifest and the ignore file.
+    def self.gitignore_body(untracked_paths: [])
+      lines = ["# textus runtime artifacts — safe to delete, never commit",
+               "#{RUN}/"]
+      unless untracked_paths.empty?
+        lines << "# tracked:false entries — protocol-readable, not committed (sensitive)"
+        lines.concat(untracked_paths)
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    # Back-compat constant: the no-untracked-entries body (just the run subtree).
+    GITIGNORE = gitignore_body
   end
 end

data/lib/textus/manifest/capabilities.rb

@@ -11,9 +11,9 @@ module Textus
       # declares a `kind: workspace` zone is therefore rejected at load (no
       # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
       DEFAULT_MAPPING = {
-        "human" => %w[author propose].freeze,
-        "agent" => %w[propose].freeze,
-        "automation" => %w[fetch build].freeze,
+        Textus::Role::HUMAN => %w[author propose].freeze,
+        Textus::Role::AGENT => %w[propose].freeze,
+        Textus::Role::AUTOMATION => %w[fetch build].freeze,
       }.freeze
 
       # Returns { role_name => [verbs] }. When `roles:` is declared we use

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

@@ -31,6 +31,12 @@ module Textus
         def intake?  = false
         def leaf?    = false
 
+        # Whether git should track this entry's file. Default true; an entry
+        # marked `tracked: false` in the manifest stays protocol-readable but is
+        # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
+        # reads from raw here rather than threading through every constructor.
+        def tracked? = @raw["tracked"] != false
+
         # Nil stubs for cross-cutting optional attrs. Subclasses override the
         # ones they own. Validators and serializers can call these directly
         # without `respond_to?` guards.

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

@@ -41,6 +41,7 @@ module Textus
           return nil if @publish_each.nil?
 
           leaves = []
+          pruned = [] # accumulates orphans removed by prune_orphans below
           pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
             next unless row[:manifest_entry].equal?(self)
             next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
@@ -53,18 +54,57 @@ module Textus
               )
             end
 
-            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published,
-                      key: row[:key],
-                      envelope: pctx.reader.call(row[:key]),
-                      source: row[:path],
-                      target: target_abs)
-            leaves << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+            written = @index_filename ? publish_subtree(row, target_abs, pctx) : [publish_one(row, target_abs, pctx)]
+            pruned.concat(prune_orphans(target_abs, written, pctx)) if @index_filename
+            written.each { |w| leaves << { "key" => row[:key], "source" => w["source"], "target" => w["target"] } }
           end
 
-          { kind: :leaves, value: leaves }
+          { kind: :leaves, value: leaves, pruned: pruned }
         end
 
+        def publish_one(row, target_abs, pctx)
+          Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+          pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                     source: row[:path], target: target_abs)
+          { "source" => row[:path], "target" => target_abs }
+        end
+
+        def publish_subtree(row, target_dir, pctx)
+          base = File.join(pctx.root, "zones", path)
+          leaf_dir = File.dirname(row[:path])
+          # FNM_DOTMATCH includes dotfiles; File.file? below skips dirs (and symlinks-to-dirs). Leaf trees are authored content, not arbitrary symlink graphs.
+          Dir.glob(File.join(leaf_dir, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
+            next nil unless File.file?(src)
+
+            rel_to_base = src.sub(%r{\A#{Regexp.escape(base)}/}, "")
+            next nil if ignored?(rel_to_base)
+
+            rel_to_leaf = src.sub(%r{\A#{Regexp.escape(leaf_dir)}/}, "")
+            dst = File.join(target_dir, rel_to_leaf)
+            Textus::Ports::Publisher.publish(source: src, target: dst, store_root: pctx.root)
+            pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                       source: src, target: dst)
+            { "source" => src, "target" => dst }
+          end
+        end
+
+        # Scoped to this leaf's target_dir only. Safe across leaves because ADR 0046
+        # Decision 5 (shallowest-index-wins) keeps leaf dirs non-nesting, so {leaf}-derived
+        # target dirs never nest and targets_under can't reach another leaf's sentinels.
+        def prune_orphans(target_dir, written, pctx)
+          kept = written.map { |w| File.expand_path(w["target"]) }
+          store = Textus::Ports::SentinelStore.new
+          store.targets_under(target_dir, pctx.root).filter_map do |managed|
+            next nil if kept.include?(File.expand_path(managed))
+
+            Textus::Ports::Publisher.unpublish(target: managed, store_root: pctx.root)
+            managed
+          end
+        end
+
+        # Helpers are private; KIND / self.from_raw / REGISTRY below are intentionally public.
+        private :publish_one, :publish_subtree, :prune_orphans
+
         KIND = :nested
 
         def self.from_raw(common, raw)

data/lib/textus/manifest/entry/validators/events.rb

@@ -4,7 +4,7 @@ module Textus
       module Validators
         module Events
           def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            pubsub_events = Textus::Hooks::EventBus::EVENTS.keys
+            pubsub_events = Textus::Hooks::Catalog::PUBSUB.keys
             events = entry.events
             events.each_key do |evt|
               next if pubsub_events.include?(evt.to_sym)

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -27,13 +27,51 @@ module Textus
               )
             end
 
-            return if used_vars.any? { |v| REQUIRED_DISCRIMINATOR_VARS.include?(v) }
+            validate_discriminator(entry, used_vars, publish_each)
+          end
+
+          def self.validate_discriminator(entry, used_vars, publish_each)
+            if entry.index_filename
+              forbidden = used_vars & %w[basename ext]
+              unless forbidden.empty?
+                raise UsageError.new(
+                  "entry '#{entry.key}': publish_each names a directory " \
+                  "(index_filename: '#{entry.index_filename}'); {basename}/{ext} are file-only — " \
+                  "use {leaf} or {key}.",
+                )
+              end
+              last_segment = publish_each.sub(%r{/\z}, "").split("/").last
+              if last_segment == entry.index_filename
+                raise UsageError.new(
+                  "entry '#{entry.key}': directory-leaf publish_each must name the target DIRECTORY, " \
+                  "not the index file — drop the trailing '/#{entry.index_filename}' " \
+                  "(the whole leaf subtree is copied into the named directory).",
+                )
+              end
+              ext = File.extname(last_segment)
+              unless ext.empty?
+                raise UsageError.new(
+                  "entry '#{entry.key}': directory-leaf publish_each names a DIRECTORY target, but its " \
+                  "final segment '#{last_segment}' looks like a file (extension '#{ext}') — " \
+                  "drop the extension (the whole leaf subtree is copied into the named directory).",
+                )
+              end
+              return if used_vars.intersect?(%w[leaf key])
+
+              raise UsageError.new(
+                "entry '#{entry.key}': directory-leaf publish_each must reference {leaf} or {key} " \
+                "(else every leaf would clobber the same directory).",
+              )
+            end
+
+            return if used_vars.intersect?(REQUIRED_DISCRIMINATOR_VARS)
 
             raise UsageError.new(
               "entry '#{entry.key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
               "(else every leaf would clobber the same target).",
             )
           end
+          private_class_method :validate_discriminator
         end
       end
     end

data/lib/textus/manifest/policy.rb

@@ -34,6 +34,13 @@ module Textus
         (proposers - roles_with_capability("author")).first || proposers.first
       end
 
+      # The role textus acts AS for a system-initiated operation requiring
+      # `verb` (no human passed --as). Capability-derived — a role name that
+      # exists in the manifest, or nil. Never a hardcoded literal (ADR 0044).
+      def actor_for(verb)
+        roles_with_capability(verb).first
+      end
+
       # The roles authorized to write `zone_name`: those holding the verb its
       # kind requires. Raises on an undeclared zone.
       def zone_writers(zone_name)

data/lib/textus/manifest/resolver.rb

@@ -72,8 +72,21 @@ module Textus
         return [] unless File.directory?(base)
 
         entry_index_filename = entry.index_filename
-        glob_pattern = entry_index_filename ? "**/#{entry_index_filename}" : nested_glob(entry.format)
-        Dir.glob(File.join(base, glob_pattern)).filter_map { |path| nested_row_for(entry, base, path) }
+        unless entry_index_filename
+          return Dir.glob(File.join(base, nested_glob(entry.format)))
+                    .filter_map { |path| nested_row_for(entry, base, path) }
+        end
+
+        claimed = []
+        Dir.glob(File.join(base, "**", entry_index_filename))
+           .sort_by { |path| path.count("/") }
+           .filter_map do |path|
+          leaf_dir = File.dirname(path)
+          next nil if claimed.any? { |d| leaf_dir.start_with?("#{d}/") }
+
+          claimed << leaf_dir
+          nested_row_for(entry, base, path)
+        end
       end
 
       def nested_row_for(entry, base, path)

data/lib/textus/manifest/schema.rb

@@ -25,7 +25,7 @@ module Textus
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
         compute template publish_to publish_each
-        intake events inject_boot index_filename ignore
+        intake events inject_boot index_filename ignore tracked
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
@@ -35,6 +35,13 @@ module Textus
       RETENTION_KEYS = %w[expire_after archive_after].freeze
       AUDIT_KEYS = %w[max_size keep].freeze
 
+      # Syntactic shape of an `owner:` subject token (the `patrick` in
+      # `human:patrick`) — the subject half of the owner-validation rule below.
+      # Role supplies the archetype set (Role::NAMES); this pattern is the
+      # owner-specific part, so it lives with the rule that composes them
+      # (ADR 0045 D1). Acting-role *names* are gated by Role::NAMES, not a regex.
+      OWNER_SUBJECT_PATTERN = /\A[a-z][a-z0-9_-]*\z/
+
       def self.validate!(raw)
         raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
@@ -42,6 +49,7 @@ module Textus
         validate_roles!(raw["roles"])
         validate_zones!(raw["zones"])
         validate_entries!(raw["entries"])
+        validate_owners!(raw["zones"], raw["entries"])
         validate_rules!(raw["rules"])
         walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
         validate_single_queue!(raw)
@@ -91,6 +99,12 @@ module Textus
           path = "$.roles[#{i}]"
           walk(r, ROLE_KEYS, path)
           name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
+          unless Textus::Role::NAMES.include?(name)
+            raise BadManifest.new(
+              "unknown role name '#{name}' at '#{path}' " \
+              "(allowed: #{Textus::Role::NAMES.join(", ")})",
+            )
+          end
           Array(r["can"]).each do |verb|
             next if CAPABILITIES.include?(verb)
 
@@ -109,6 +123,47 @@ module Textus
         )
       end
 
+      # Owners are validated against the SAME closed archetype set as role names
+      # (ADR 0045 D1) so attribution can't bypass the closed-name guarantee.
+      # Applies to both zone owners and entry owners; owner is optional, so a
+      # nil owner is not an error.
+      def self.validate_owners!(zones, entries)
+        Array(zones).each_with_index do |z, i|
+          check_owner!(z["owner"], "$.zones[#{i}]")
+        end
+        Array(entries).each_with_index do |e, i|
+          check_owner!(e["owner"], "$.entries[#{i}]")
+        end
+      end
+
+      def self.check_owner!(owner, path)
+        return if owner.nil?
+        return if valid_owner?(owner)
+
+        raise BadManifest.new(
+          "invalid owner '#{owner}' at '#{path}' " \
+          "(expected <archetype> or <archetype>:<subject>, " \
+          "archetype one of: #{Textus::Role::NAMES.join(", ")})",
+        )
+      end
+
+      # The owner-validation rule: an `owner:` token is either a bare archetype
+      # (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is
+      # gated against the closed Role::NAMES set (so attribution can't smuggle in
+      # a name the role side rejects, ADR 0045 D1); the subject is the free-form
+      # principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ':'
+      # only — a subject may not itself contain ':' (the pattern excludes it), so
+      # `human:a:b` is rejected.
+      def self.valid_owner?(token)
+        return false unless token.is_a?(String) && !token.empty?
+
+        archetype, subject = token.split(":", 2)
+        return false unless Textus::Role::NAMES.include?(archetype)
+        return true if subject.nil?
+
+        OWNER_SUBJECT_PATTERN.match?(subject)
+      end
+
       def self.validate_fetch_timeout!(value, path)
         return if value.nil?
         return if value.is_a?(Integer) && value.positive? && value <= FETCH_TIMEOUT_SECONDS_CEILING

data/lib/textus/ports/audit_subscriber.rb

@@ -33,7 +33,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: "automation", verb: "event_error", key: key,
+          role: Textus::Role::AUTOMATION, verb: "event_error", key: key,
           etag_before: nil, etag_after: nil, extras: extras
         )
       end

data/lib/textus/ports/fetch/detached.rb

@@ -8,6 +8,10 @@ module Textus
           Process.respond_to?(:fork)
         end
 
+        def acting_role(store)
+          store.manifest.policy.actor_for("fetch")
+        end
+
         def spawn(store_root:, key:)
           return nil unless supported?
 
@@ -21,7 +25,13 @@ module Textus
 
             begin
               store = Textus::Store.new(store_root)
-              store.as("automation").fetch(key)
+              # No fetch-holder configured — exit the child cleanly. In practice
+              # this is unreachable: the background fork only happens after a
+              # foreground fetch was already authorized (so a fetch-holder
+              # exists). Config-time detection is doctor's job (ADR 0044 Q2).
+              role = acting_role(store)
+              exit(0) unless role
+              store.as(role).fetch(key)
             rescue StandardError
               # Already logged via :fetch_failed; exit cleanly.
             ensure

data/lib/textus/ports/publisher.rb

@@ -18,6 +18,16 @@ module Textus
         Textus::Ports::SentinelStore.new.write!(target: target, source: source, store_root: store_root)
       end
 
+      # Removes a previously-published file and its sentinel. No-op unless the
+      # target is textus-managed — never deletes an unmanaged file.
+      def self.unpublish(target:, store_root:)
+        return unless managed?(target, store_root)
+
+        FileUtils.rm_f(target)
+        sentinel = Textus::Ports::SentinelStore.new.sentinel_path(target, store_root)
+        FileUtils.rm_f(sentinel)
+      end
+
       def self.refuse_if_unmanaged(target, store_root)
         return unless File.exist?(target) || File.symlink?(target)
         return if managed?(target, store_root)

data/lib/textus/ports/sentinel_store.rb

@@ -42,6 +42,21 @@ module Textus
         File.join(store_root, DIR, rel + SUFFIX)
       end
 
+      # Absolute target paths of every sentinel recorded under `target_dir`.
+      def targets_under(target_dir, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target_dir, repo_root) or return []
+        sdir = File.join(store_root, DIR, rel)
+        return [] unless File.directory?(sdir)
+
+        prefix = File.join(store_root, DIR) + "/"
+        Dir.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
+          # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
+          trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)
+          File.join(repo_root, trel)
+        end
+      end
+
       private
 
       def rel_or_abs(path, repo_root)

data/lib/textus/role.rb

@@ -1,15 +1,26 @@
 module Textus
   module Role
-    PATTERN = /\A[a-z][a-z0-9_-]*\z/
-    DEFAULT = "human".freeze
-    # The default acting identity for the MCP transport (ADR 0040): an agent
-    # over stdio proposes; it does not inherit the human's authority. CLI
-    # callers keep the `human` DEFAULT.
-    AGENT = "agent".freeze
+    # The three role archetypes, each string sourced exactly once: human curates
+    # canon, agent proposes, automation fetches/builds (explanation/concepts.md).
+    # Reference these constants instead of bare literals (ADR 0044).
+    HUMAN      = "human".freeze
+    AGENT      = "agent".freeze
+    AUTOMATION = "automation".freeze
+
+    # The closed set of legal role names (ADR 0045), built FROM the archetypes
+    # above so it stays the single source of truth — a manifest declaring any
+    # other name is rejected at load, and DEFAULT ∈ NAMES holds structurally.
+    # Capabilities (`can:`) remain freely tunable per role.
+    NAMES = [HUMAN, AGENT, AUTOMATION].freeze
+
+    # Default acting identity (ADR 0040): a *choice* over the vocabulary, not a
+    # new name. CLI callers act as the human; an agent over stdio proposes and
+    # does not inherit the human's authority (it defaults to AGENT per transport).
+    DEFAULT = HUMAN
 
     def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
       candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
-      raise InvalidRole.new(candidate) unless candidate.match?(PATTERN)
+      raise InvalidRole.new(candidate) unless NAMES.include?(candidate)
 
       candidate
     end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.39.0"
+  VERSION = "0.40.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/publish.rb

@@ -18,6 +18,7 @@ module Textus
       def call(prefix: nil)
         built  = []
         leaves = []
+        pruned = []
         context = build_context
 
         @manifest.data.entries.each do |mentry|
@@ -27,12 +28,14 @@ module Textus
           next if result.nil?
 
           case result[:kind]
-          when :built  then built << result[:value]
-          when :leaves then leaves.concat(result[:value])
+          when :built then built << result[:value]
+          when :leaves
+            leaves.concat(result[:value])
+            pruned.concat(result[:pruned]) if result[:pruned]
           end
         end
 
-        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
+        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves, "pruned" => pruned }
       end
 
       private

data/lib/textus.rb

@@ -17,6 +17,10 @@ loader.inflector.inflect(
 loader.ignore(File.expand_path("textus/errors.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp/errors.rb", __dir__))
+# Scaffold sources copied verbatim into user stores by `textus init`. They are
+# file templates (one calls `Textus.hook` at load time), not gem constants —
+# Zeitwerk must not manage or eager-load them (ADR 0043).
+loader.ignore(File.expand_path("textus/init/templates", __dir__))
 loader.setup
 loader.eager_load
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Patrick
@@ -103,7 +103,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ARCHITECTURE.md
 - CHANGELOG.md
 - README.md
 - SPEC.md
@@ -177,6 +176,7 @@ files:
 - lib/textus/doctor/check/illegal_keys.rb
 - lib/textus/doctor/check/intake_registration.rb
 - lib/textus/doctor/check/manifest_files.rb
+- lib/textus/doctor/check/orphaned_publish_targets.rb
 - lib/textus/doctor/check/proposal_targets.rb
 - lib/textus/doctor/check/protocol_version.rb
 - lib/textus/doctor/check/rule_ambiguity.rb
@@ -226,6 +226,7 @@ files:
 - lib/textus/errors.rb
 - lib/textus/etag.rb
 - lib/textus/hooks/builtin.rb
+- lib/textus/hooks/catalog.rb
 - lib/textus/hooks/context.rb
 - lib/textus/hooks/error_log.rb
 - lib/textus/hooks/event_bus.rb
@@ -234,6 +235,7 @@ files:
 - lib/textus/hooks/rpc_registry.rb
 - lib/textus/hooks/signature.rb
 - lib/textus/init.rb
+- lib/textus/init/templates/machine_intake.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb

data/ARCHITECTURE.md

@@ -1,3 +0,0 @@
-# Architecture
-
-Moved to [`docs/architecture/README.md`](docs/architecture/README.md).