textus 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96c684d8a670835fb687a321abb85838ec831e95e8672b7f03453266e2224b65
-  data.tar.gz: d9332836814f977824413a7bc379666cfd830f182d2c44a9ed5a71d1e7336513
+  metadata.gz: 4991eadd244e9ced0531683c7a40f27b88b825e23e8d0bd5ad5be7f91716e4c9
+  data.tar.gz: d3e8d18c1e360455aef19bd7168b0ffb4516c54d0004253f34af78940752120d
 SHA512:
-  metadata.gz: cbfdd6527a26f2e8fb97cdde2cc99c5df4d36839af1f426bf52156335187d4b48ecbe45af1b271031861bc225d100676522082da6f74c171555bd5cf7bd0b227
-  data.tar.gz: 38ac5fff2e9209c8bbbc15745a1ddbd840736ddcc23363c6a61099926b79807a9ccb49630a98b69f6ed41cf2a15d3272bd586f6bc749ea381e4d24158eeb597a
+  metadata.gz: f0f63a06265e280a8424476dff4941dfc0de016f68a9530ed53799429115416fea50f9f9479266baecd8d34c96e3bece97e1d97ab35446dd0dcb4cb2c7f61771
+  data.tar.gz: 4cbfee016952dcc19312097018b18b63b8515d59786fddafc81d4a696737cbd3bd32f1d3dd45beae6d8660495c631defe70d324344c274ce02d505a3285ae8df

data/CHANGELOG.md

@@ -9,7 +9,19 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
-## Unreleased
+## 0.41.0 — 2026-06-02 — `publish_tree` subtree mirror + content-identical publish adoption ([ADR 0047](docs/architecture/decisions/0047-publish-tree-keyless-subtree-mirror.md), [0050](docs/architecture/decisions/0050-native-authoring-and-content-identical-adoption.md))
+
+No `textus/3` wire-format change — every change here is repo-local publish behaviour or internal re-layering. Headlines: a key-less `publish_tree:` subtree mirror (ADR 0047), and publish now *adopts* a byte-identical pre-existing target instead of refusing (ADR 0050), so an artifact tree already on disk onboards without a manual delete. Internals were re-cut along the way (fetch subsystem, ADR 0048; publish modes as a sum type, ADR 0049) with no contract change.
+
+### Added
+
+- **`publish_tree:`** — a key-less, path-driven subtree mirror for `nested` entries: copies a whole stored directory to one target dir (layout preserved, per-file sentinels, `ignore`-filtered, whole-target prune). Unblocks publishing the sibling tree of a leaf whose index file is *derived* (issue #132 item #4). Additive; no protocol change. New `doctor` check `publish.tree_index_overlap`. See [ADR 0047](docs/architecture/decisions/0047-publish-tree-keyless-subtree-mirror.md).
+
+### Changed
+
+- **Fetch subsystem re-layered so its three concerns each have one home ([ADR 0048](docs/architecture/decisions/0048-fetch-subsystem-three-concerns.md)).** Internal refactor, no wire or hook-contract change: the before-etag now routes through the `FileStore` port (a guard spec keeps `read/`+`write/` from regressing); a single `IntakeFetch` kernel owns "invoke the intake handler under a deadline" and always passes a uniform `caps: <Container>` to `:resolve_intake`; the fetch lifecycle event vocabulary moves into one `FetchEvents` seam shared by `FetchWorker` and `FetchOrchestrator`. Public verbs, hook events, and the `textus/3` wire contract are unchanged.
+- **Publish modes re-cut into a resolved sum type ([ADR 0049](docs/architecture/decisions/0049-publish-modes-as-sum-type.md)).** Internal refactor, no manifest key, wire, event, or `doctor` change: each entry now resolves once to one `Manifest::Entry::Publish::*` mode (`None` / `ToPaths` / `EachFile` / `EachDir` / `Tree`) that owns its publish algorithm, replacing the nil-cascade selector on `Nested`. Mode exclusivity is structural — one `UsageError` naming the conflicting keys, in place of the four scattered pairwise guards across two validators. `EachDir` and `Tree` share one `SubtreeMirror` (one walk, one prune) whose `ignore`-in-prune difference (ADR 0047 D4) is now the explicit `prune_honors_ignore:` parameter. The three manifest keys and every published-leaf / `:file_published` shape are unchanged.
+- **Publish adopts a byte-identical pre-existing target instead of refusing ([ADR 0050](docs/architecture/decisions/0050-native-authoring-and-content-identical-adoption.md)).** The clobber guard now fires only when an unmanaged target's content **differs** from the source (or it's an unmanaged symlink); an identical target is *adopted* — its sentinel is written, the file is untouched — so an artifact tree already on disk (e.g. an Agent Skill authored in its native shape, issue #132) onboards to textus without a manual delete. Narrows `SPEC.md` §491; reuses the sha already stored in the sentinel; no new manifest key, CLI flag, hook event, or build-envelope field, and no protocol change.
 
 ## 0.40.0 — 2026-06-02 — `publish_each` owns multi-file leaf subtrees ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md))
 

data/SPEC.md

@@ -274,6 +274,18 @@ Validation at manifest load: any unknown variable raises `UsageError`; a compute
 
 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.
 
+**Subtree mirror (`publish_tree:`).** A nested manifest entry MAY declare `publish_tree:` to mirror its entire stored subtree (`zones/<path>/**`) to a single target directory, preserving relative layout (case and extension preserved). Unlike `publish_each:`, it is **path-driven, not key-driven**: no keys are enumerated, no template variables are interpreted, and the mirrored files are opaque payload (never addressable). The entry's `ignore:` globs (§4, ADR 0042) filter the walk; each mirrored file gets its own sentinel; and on every build the whole target directory is pruned of textus-managed files the current source no longer produces (unmanaged files are never touched). `publish_tree:` is mutually exclusive with `publish_to:` and `publish_each:`, and incompatible with `index_filename:`. When a `publish_tree:` target directory overlaps a `derived` entry's `publish_to:` (e.g. a derived `SKILL.md` written into the mirrored dir), the `publish_tree:` entry **must** `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap`. See ADR 0047.
+
+```yaml
+- key: working.skills
+  path: working/skills
+  zone: working
+  schema: skill
+  nested: true
+  publish_tree: "skills"
+  ignore: ["*.tmp", ".DS_Store"]
+```
+
 **`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.
 
 **Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/zones/<entry.path>[/<remaining>...].md` — implementations MUST prepend `zones/` to the manifest `path:` when constructing the filesystem location.
@@ -476,10 +488,12 @@ publish_to:
 
 When the entry is recomputed, textus copies the in-store file byte-for-byte to each destination. The in-store artifact under `.textus/zones/<output-zone>/…` is already the consumer-shaped output (per the format strategy — see §5.x), so publish is a verbatim file copy with no parsing or stripping.
 
-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.
+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, marked as managed, or **byte-identical to the source being published**. An identical destination is *adopted*: its sentinel is written and management proceeds (the copy is a content no-op), so an artifact tree already on disk onboards without a manual delete. An unmanaged destination whose content **differs**, or any unmanaged symlink, is still refused (ADR 0050). 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 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.
 
+**Subtree mirror.** A nested entry MAY declare `publish_tree:` instead of `publish_to:` or `publish_each:` (see §4). On every build, textus walks the entry's full stored subtree (`zones/<path>/**`), applies the entry's `ignore:` filter, and byte-copies each file to the target directory, preserving relative layout — one sentinel per file under `<store_root>/sentinels/`. The mirror is path-driven: no keys are enumerated, no template variables are interpreted, and mirrored files are opaque payload (never addressable). On rebuild, the entire target directory is pruned of textus-managed files the current source no longer produces; unmanaged files are never touched. `publish_tree:` is mutually exclusive with `publish_to:` and `publish_each:`, and incompatible with `index_filename:`. When a `publish_tree:` target overlaps a `derived` entry's `publish_to:` (e.g. a derived `SKILL.md` written into the mirrored dir), the `publish_tree:` entry must `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap` (ADR 0047).
+
 ### 5.4 Intake (declared, fetched via registered intake handler)
 
 Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus fetch KEY --as=automation` (or by `textus fetch stale`). The declaration is data only:
@@ -998,7 +1012,7 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 ## 10.2 `textus doctor`
 
-`textus doctor` returns a health-check envelope: `{ "protocol": "textus/3", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `protocol_version`, `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `intake_registration`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `handler_allowlist`, `fetch_locks`, `proposal_targets`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/3", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `protocol_version`, `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `intake_registration`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `handler_allowlist`, `fetch_locks`, `proposal_targets`, `publish.tree_index_overlap`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 

data/docs/architecture/README.md

@@ -0,0 +1,256 @@
+# Textus architecture
+
+> **Explanation** · for contributors · **read this first** for orientation before SPEC
+> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-05 (v0.35)
+
+```mermaid
+flowchart TD
+    interface["Interface — CLI verbs · MCP gate (JSON-RPC)"]
+    application["Application — Call · Container · Dispatcher · RoleScope<br/>read/ · write/ · maintenance/ use cases · envelope IO"]
+    domain["Domain — Permission · Freshness · Staleness<br/>Policy (Guard · GuardFactory · BaseGuards · Evaluation · Fetch · Matcher · Predicates)"]
+    infra["Infrastructure — Store · FileStore · Manifest · Schemas<br/>Ports · Hooks · Entry format strategies"]
+    interface --> application
+    application --> domain
+    application --> infra
+    domain -.->|implemented by| infra
+```
+
+*Dependency rule: arrows point down.* Domain performs no direct `File`/`Dir`/`Time.now` I/O — all disk and clock access is routed through injected ports; pure path math is allowed. Application imports Domain + Ports. Use cases are plain classes on `(container:, call:)`. Verbs are looked up in the static `Dispatcher::VERBS` table.
+
+### What lives in each layer
+
+**Interface**
+
+```
+CLI verbs:  store.<verb>(..., role:)
+            store.as(role).<verb>(...)    # (put/get/fetch/…)
+
+MCP gate:   textus mcp serve — same use cases, JSON-RPC.
+```
+
+**Application**
+
+```
+Call             (slim Data: role, correlation_id, now,
+                  dry_run — request state only)
+Container        (single record — wired ports + manifest)
+Dispatcher       (static VERBS table: verb → use-case)
+RoleScope        (Store#as(role) — forwards verb calls)
+
+read/{get,get_or_fetch,list,where,uid,schema_envelope,
+      deps,rdeps,published,stale,validate_all,boot,doctor,
+      freshness,audit,blame,policy_explain,pulse}.rb
+write/{put,delete,mv,accept,reject,publish,
+       materializer,intake_fetch,retention_sweep,
+       fetch_worker,fetch_orchestrator,fetch_all}
+maintenance/{migrate,key_mv_prefix,key_delete_prefix,
+             zone_mv,rule_lint}.rb
+envelope/io/{reader,writer}.rb  (split: parse vs persist)
+projection.rb
+```
+
+**Domain**
+
+```
+Permission         (write predicate per zone)
+Freshness::{Policy,Verdict,Evaluator}
+Staleness          (Generator/Intake checks)
+Action  Outcome  Sentinel
+Policy::{Guard,GuardFactory,BaseGuards,Evaluation,Fetch,Matcher,HandlerAllowlist,
+         Predicates::{ZoneWritableBy,SchemaValid,AuthorHeld,TargetIsCanon,EtagMatch,FreshWithin}}
+```
+
+**Infrastructure**
+
+```
+Store              (composition root — wires ports,
+                    vends a Container + dispatches verbs)
+Storage::FileStore (bytes-only port: read/write/delete/
+                    exists?/etag)
+Manifest           (Data, Resolver, Policy, Rules)
+Schemas            (eager-load cache)
+Ports::{AuditLog,AuditSubscriber,Publisher,Clock,
+        Fetch::Lock,Fetch::Detached,BuildLock}
+Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,
+        Signature,Builtin,ErrorLog}
+Entry::{Markdown,Json,Yaml,Text}  (format strategies)
+```
+
+## How a verb becomes a method
+
+Each application use case is a plain class under `lib/textus/{read,write,maintenance}/`. The shape is uniform:
+
+```ruby
+module Textus
+  module Read
+    class Get
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+      end
+
+      def call(key)
+        ...
+      end
+    end
+  end
+end
+```
+
+Verbs are looked up in a static frozen table (`Textus::Dispatcher::VERBS`) that maps `:get → Textus::Read::Get`, `:put → Textus::Write::Put`, etc. `Store#put` / `Store#get` / `Store#as(role).<verb>(...)` instantiate the use case on `(container:, call:)` and invoke `#call`. Adding a new verb is **one entry in `Dispatcher::VERBS`** plus the class — no metaprogramming.
+
+The instantiate-and-call step itself has one home: `Dispatcher.invoke(verb, container:, call:, args:, kwargs:)` (ADR 0026). `RoleScope` builds the `Call` (request state) and delegates the dispatch to `Dispatcher.invoke`; the convention for invoking a uniform-shape use case lives next to the table that maps the verbs, not re-spelled in the caller. `Store`'s own verb loop is separate — it extracts the `role:` keyword and forwards to `as(role)`, a role-selection job distinct from invocation.
+
+`boot` and `doctor` are read verbs like any other: `Read::Boot` / `Read::Doctor`
+are thin `(container:, call:)` use cases that delegate to the `Textus::Boot` /
+`Textus::Doctor` report-building libraries (`build(container:, ...)`). They are
+reached through `Dispatcher::VERBS`, not a special method on `RoleScope`.
+
+Two collaborators live outside the dispatcher because they're composed by other use cases, not invoked as verbs:
+
+- `Write::FetchOrchestrator` — composes `FetchWorker` with the freshness `Action` returned by `Domain::Freshness`.
+- `Envelope::IO::{Reader,Writer}` — own the parse and persist halves of the write pipeline; the audit-append-as-final-step invariant lives in `Writer`.
+
+## Container
+
+Use cases never see the raw `Store`. `Textus::Container` is a single record holding the wired collaborators:
+
+```ruby
+Container = Data.define(
+  :manifest, :file_store, :schemas, :root,
+  :audit_log, :events, :rpc
+)
+```
+
+The `Store` builds one `Container` at boot; every use case receives it via `(container:, call:)`. RPC hook callables (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps: <Container>` — field names match what the prior `WriteCaps` exposed, so handlers reading `caps.manifest`, `caps.events`, etc. continue to work.
+
+## Ports
+
+Ports are infrastructure adapters with an interface defined by the domain. Each port is independently replaceable — swap the implementation for tests or alternative runtimes without touching application or domain code.
+
+| Class | Role |
+|---|---|
+| `Ports::Storage::FileStore` | Bytes-only FS I/O — `read`, `write`, `delete`, `exists?`, `etag`. No knowledge of envelopes or schemas. |
+| `Ports::AuditLog` | Append-only structured log (`audit.log`). Owns seq numbering, file-locking, and rotation. |
+| `Ports::Clock` | Supplies `Time.now` — a module-function so tests can swap it without dependency injection boilerplate. |
+| `Ports::Publisher` | Copies a built artifact to a repo-relative consumer path and writes a sentinel so the next publish can confirm the target is managed. |
+| `Ports::Fetch::Lock` | Non-blocking `flock`-backed lock per key — prevents concurrent fetch workers from racing on the same entry. |
+| `Ports::Fetch::Detached` | Spawns a background thread for async fetch; the caller receives a `fetch_backgrounded` event instead of blocking. |
+| `Ports::BuildLock` | Process-exclusive `flock` guard over the materializer build pipeline. Raises `BuildInProgress` if a build is already running. |
+
+Application use cases access ports only through `Container` fields — never through the raw `Store`.
+
+### EnvelopeIO
+
+`Envelope::IO::Reader` and `Envelope::IO::Writer` split the envelope pipeline into read-only parse and write-with-audit halves.
+
+**Reader** (`lib/textus/envelope/io/reader.rb`) — resolves a key through `manifest.resolver`, reads bytes via `FileStore`, delegates parsing to the format strategy (`Entry.for_format`), and returns an `Envelope`. No audit, no events, no permission checks. Also used by `Writer` for the existing-uid lookup on `put`.
+
+**Writer** (`lib/textus/envelope/io/writer.rb`) — owns the full write pipeline: serialize → schema-validate → etag-check → `FileStore#write` → `AuditLog#append`. The class comment states the invariant directly: every public method's final action is `@audit_log.append(...)`. If the audit append fails, the caller sees the underlying error — the byte write already happened, but the pipeline contract treats audit as the commit step. No permission check, no event firing — those stay in the calling use case (`Write::Put`, `Write::Delete`, `Write::Mv`).
+
+The three public methods are `put`, `delete`, and `move`; all follow the same validate → write → audit sequence.
+
+Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` (which builds its own `Reader.from`) and `Reader.from(container:)` (ADR 0026). Write use cases call `Writer.from` rather than reconstructing the object graph by hand, so a change to the Writer's dependencies is a one-line edit in one place.
+
+## Manifest carving
+
+Manifest carving means slicing the parsed manifest YAML into four purpose-specific sub-objects. Each consumer sees only the fields it needs; none reach into the full raw document.
+
+`Manifest` itself is a `Data.define` struct — a composition record with four named members:
+
+| Member | Class | Responsibility |
+|---|---|---|
+| `data` | `Manifest::Data` | Frozen value: `raw`, `root`, `zones`, `entries`, `audit_config`, `role_caps` (role name → capability set). Structural data only — no behaviour beyond accessors and key validation. |
+| `resolver` | `Manifest::Resolver` | Key → `Resolution(entry, path, remaining)`. Handles nested entry enumeration and fuzzy-match suggestions. |
+| `policy` | `Manifest::Policy` | Zone/capability authority — `verb_for_zone` (zone-kind → required verb), `roles_with_capability(verb)`, `zone_writers` (derived: roles holding the verb the zone's kind requires), `permission_for`, `declared_kind`, `proposer_role`, `propose_zone_for(role)`. Write authority is derived from capabilities × zone-kind (ADR 0030); no filesystem I/O. `propose_zone_for` returns the single `kind: queue` zone when the role can write it (ADR 0027). |
+| `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` returns a `RuleSet(fetch, handler_allowlist, guard, retention)` by evaluating all `match:` blocks against the key. |
+
+Rationale: cleaner test seams — a use case that only needs key resolution constructs a `Manifest::Resolver` from a stub `Data`; one that only needs rule lookup constructs a `Manifest::Rules` directly. No consumer is forced to build the full manifest to exercise one sub-view.
+
+The four members are wired in `Manifest.build` (`lib/textus/manifest.rb`). `Manifest::Data` constructs `Policy` internally during `initialize`; the others are assembled by the loader and handed in as named arguments.
+
+## Read path (`store.get(key)`)
+
+1. CLI verb (or MCP tool) calls `store.get(key, role:)` (or `store.as(role).get(key)`).
+2. `Store#get` looks up `Dispatcher::VERBS[:get] → Read::Get`, builds a `Call`, instantiates `Read::Get.new(container:, call:).call(key)`.
+3. `Read::Get#call` resolves the path through `container.manifest`, reads bytes via `container.file_store`, parses the envelope.
+4. Looks up the fetch policy via `container.manifest.rules.for(key)`. If absent, returns the envelope annotated fresh.
+5. Otherwise `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`; the envelope is annotated with `stale`, `reason`, `fetching: false`.
+
+`store.get_or_fetch(key)` composes `Read::Get` with `Write::FetchOrchestrator` to optionally fetch on stale.
+
+## Write path (`store.put(key, ...)`)
+
+1. CLI verb calls `store.put(key, meta:, body:, content:, if_etag:, role:)`.
+2. `Write::Put#call` validates the key, resolves the manifest entry, builds `GuardFactory.for(:put, key)` and calls `Guard#check!(eval)` (topology is predicate #0, `zone_writable_by`) — raises `WriteForbidden` if the topology gate denies, `GuardFailed` if any other predicate fails.
+3. Delegates persistence to `Envelope::IO::Writer#put`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
+4. Publishes `:entry_put` via `container.events` with `ctx: <Hooks::Context>`, `key:`, `envelope:`.
+
+`Write::{Delete,Mv,Accept,Reject,Publish}` follow the same shape: explicit container, the unified `Guard` for authz (built per transition via `GuardFactory`), `Envelope::IO::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
+
+`Write::Mv` delegates the file-move + audit to `Envelope::IO::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::IO::Writer#write` directly — no `Put` bypass.
+
+## Fetch path (`store.fetch(key)`)
+
+1. CLI `Verb::Fetch` calls `store.fetch(key, role: "automation")`.
+2. `Write::FetchWorker#run(key)`:
+   - Resolves the manifest entry, looks up the intake handler via `container.rpc.callable(:resolve_intake, mentry.handler)`.
+   - Publishes `:fetch_started` with the hook context.
+   - Invokes the handler under a 30s thread-join deadline.
+   - On any error: publishes `:fetch_failed`, then re-raises.
+   - On success: builds `GuardFactory.for(:fetch, key)` and calls `Guard#check!`, then persists via `Envelope::IO::Writer#write` directly (no `Put` round-trip); publishes `:entry_fetched` unless etag is unchanged.
+3. `store.fetch_all(prefix:, zone:)` lists stale entries via `Read::Stale` and runs `FetchWorker#run` per entry; returns `{ fetched:, failed:, skipped: }`.
+
+## Hook payload contract
+
+Pub-sub hooks (`:entry_put`, `:entry_fetched`, …) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface (`get`, `list`, `put`, `delete`, `audit`, `publish_followup`, plus `role` and `correlation_id`). The raw `Store` is not handed out.
+
+RPC hooks (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps:` — a `Textus::Container`. They are gem-internal: the framework calls them, not user pub-sub.
+
+## Agent surface (boot + pulse + MCP)
+
+Agents and plugins talk to a textus store through three layers:
+
+```
+soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  memory (.textus/)
+```
+
+Two transports, one façade:
+
+- **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
+- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, manifest_etag) is server-side.
+
+Both transports call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`). No duplicate logic.
+
+The agent loop (cadence guide in [`agents-mcp.md`](../how-to/agents-mcp.md)):
+
+1. **Session start:** `boot()` → contract envelope (zones, entries, schemas, write_flows, agent_quickstart with `latest_seq`).
+2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
+3. **On demand:** `get`, `put`, `propose`, `fetch`, `schema`, `rules`.
+
+Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
+
+## Hooks event catalog
+
+`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027).
+
+RPC (single handler, declares `caps:`):
+- `resolve_intake(caps:, config:, args:)` — intake fetch handler.
+- `transform_rows(caps:, rows:, config:)` — row transform for intakes.
+- `validate(caps:)` — custom doctor validator.
+
+Pub-sub (0..N handlers, declare `ctx:`):
+- `entry_put(ctx:, key:, envelope:)`
+- `entry_deleted(ctx:, key:)`
+- `entry_fetched(ctx:, key:, envelope:, change:)`
+- `entry_renamed(ctx:, key:, from_key:, to_key:, envelope:)`
+- `build_completed(ctx:, key:, envelope:, sources:)`
+- `proposal_accepted(ctx:, key:, target_key:)`
+- `proposal_rejected(ctx:, key:, target_key:)`
+- `file_published(ctx:, key:, envelope:, source:, target:)`
+- `store_loaded(ctx:)`
+- `fetch_started(ctx:, key:, mode:)`
+- `fetch_failed(ctx:, key:, error_class:, error_message:)`
+- `fetch_backgrounded(ctx:, key:, started_at:, budget_ms:)`
+
+Authoritative source: `lib/textus/hooks/catalog.rb` (`Catalog::RPC` and `Catalog::PUBSUB`).

data/docs/reference/conventions.md

@@ -0,0 +1,148 @@
+# Conventions
+
+> **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.35)
+
+Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../../SPEC.md`](../../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
+
+## Key naming
+
+- **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
+- **Lead with the zone in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
+- **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
+- **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
+
+## Zone layout
+
+Recommended top-level layout — the spec allows alternatives, but this is what tooling will default to:
+
+```
+.textus/
+  manifest.yaml
+  schemas/        # YAML schema definitions
+  zones/
+    knowledge/    # authored truth: identity, voice, decisions — author-holders write
+    notebook/     # agent's own durable lane (workspace) — keep-holders write
+    feeds/        # automation-fed external inputs (fetch)
+    proposals/    # AI proposals awaiting accept (propose)
+    artifacts/    # generated by build automation — never edit by hand
+```
+
+Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
+
+## Schema design
+
+- **One schema per entry type, not per directory.** `person.yaml`, `project.yaml`, `decision.yaml` — applied across multiple subtrees if the shape matches.
+- **Required = "this entry is meaningless without it."** Everything else is `optional`. Resist the urge to mark organisational metadata (like `tags`) required.
+- **Prefer `enum` over free-text** for low-cardinality fields (relationship type, status, severity). Agents are far better at picking from a list than at producing exact strings.
+- **Cap string lengths** with `max:` where the field has a natural bound (names, summaries). Skip for prose body — bodies are not schema-validated, only frontmatter is.
+
+## Owner strings
+
+The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
+
+- `textus:network` — humans curate
+- `agent:planner` — a specific named agent
+- `build:catalog-skills` — a specific build job
+
+Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
+
+## Derived entries
+
+A derived entry declares a `compute:` block with a `kind:` discriminator. Two kinds:
+
+**`compute: { kind: projection }`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
+
+```yaml
+- key: artifacts.catalogs.people
+  path: artifacts/catalogs/people.md
+  zone: artifacts
+  schema: null
+  owner: build:catalog-people
+  compute:
+    kind: projection
+    select: knowledge.network.org   # prefix or list of prefixes
+    pluck:  [name, relationship, org]
+    sort_by: name
+  template: people.mustache         # under .textus/templates/
+  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
+```
+
+**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
+
+```yaml
+- key: artifacts.catalogs.skills
+  path: artifacts/catalogs/skills.md
+  zone: artifacts
+  owner: build:catalog-skills
+  compute:
+    kind: external
+    command: "rake catalog:skills"   # informational; the automation invokes it
+    sources: [knowledge.projects, knowledge.network]
+```
+
+The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `compute.sources` — same list, recorded twice so a diff proves what was consumed.
+
+Full contract for both shapes is in [`../../SPEC.md` §5.2.1 and §5.2.2](../../SPEC.md). Transforms (`compute.transform:`) and per-leaf publishing (`publish_each:`) are also covered there.
+
+## Intake and freshness
+
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
+
+```sh
+textus fetch feeds.notion.roadmap --as=automation
+textus fetch stale --zone=feeds --as=automation   # everything past its TTL
+```
+
+Freshness budgets live in the top-level `rules:` block, matched by glob:
+
+```yaml
+rules:
+  - match: feeds.notion.**
+    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
+```
+
+A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
+
+```sh
+textus fetch stale --zone=intake --as=automation   # in cron / CI
+```
+
+See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
+
+### Read vs. fetch
+
+There are two read operations, and the difference matters in custom code:
+
+| Operation | Triggers fetch? | Use for |
+|-----------|-----------------|---------|
+| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
+| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+
+Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
+
+## Body content
+
+- **Bodies are Markdown.** Headings, lists, code fences — whatever a human or agent finds useful.
+- **The schema does not validate the body.** If a field belongs in structured data, put it in frontmatter, not the body.
+- **Keep entries short.** If a project entry hits 500 lines, it probably wants to be split into sub-entries (e.g. `working.projects.acme.dashboard` + `working.projects.acme.api`) rather than one mega-document.
+
+## Concurrency
+
+For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
+
+## Application layering
+
+The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
+
+- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
+- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
+- **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
+
+The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
+
+## Pairing with other tools
+
+- **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
+- **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
+- **CI**: run `textus freshness` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.

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

@@ -26,11 +26,13 @@ module Textus
             end
           end
 
+          # Validate --as resolves to a declared role (raises InvalidRole); hook
+          # run has no role-scoped authority itself, so the result is discarded.
           Role.resolve(flag: as_flag, env: ENV, root: store.root)
 
           begin
             Textus::Write::IntakeFetch.invoke(
-              rpc: store.rpc, handler: name, config: {}, args: args, label: "hook run",
+              caps: store.container, handler: name, config: {}, args: args, label: "hook run",
             )
           rescue Textus::Error
             raise

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

@@ -18,7 +18,7 @@ module Textus
           payload =
             if fetch_name
               result = Textus::Write::IntakeFetch.invoke(
-                rpc: store.rpc, handler: fetch_name,
+                caps: store.container, handler: fetch_name,
                 config: { "bytes" => raw }, args: {}, label: "fetch"
               )
               basename = key.split(".").last

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

@@ -0,0 +1,48 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0047 Decision 4. A publish_tree entry prunes its WHOLE target dir on
+      # every build. If a derived entry's publish_to writes a file into that same
+      # dir, the tree's prune will delete it unless the tree `ignore`s that
+      # filename. Warn so the author adds the ignore before prune eats the index.
+      class PublishTreeIndexOverlap < Check
+        def call
+          entries = manifest.data.entries
+          trees = entries.select { |e| e.nested? && e.publish_tree }
+          return [] if trees.empty?
+
+          derived_targets = entries.flat_map do |e|
+            Array(e.publish_to).map { |rel| [e, rel] }
+          end
+
+          trees.flat_map do |tree|
+            target_prefix = "#{tree.publish_tree.chomp("/")}/"
+            derived_targets.filter_map do |(derived, rel)|
+              next nil unless rel.start_with?(target_prefix)
+
+              rel_to_target = rel.delete_prefix(target_prefix)
+              next nil if tree.ignored?(rel_to_target)
+
+              issue(tree, derived, rel, rel_to_target)
+            end
+          end
+        end
+
+        private
+
+        def issue(tree, derived, rel, rel_to_target)
+          basename = File.basename(rel_to_target)
+          {
+            "code" => "publish.tree_index_overlap",
+            "level" => "warning",
+            "subject" => tree.key,
+            "message" => "publish_tree '#{tree.publish_tree}' overlaps derived entry " \
+                         "'#{derived.key}' publish_to '#{rel}'; the tree's prune will delete it on rebuild",
+            "fix" => "add a glob covering '#{rel_to_target}' to entry '#{tree.key}' ignore " \
+                     "(e.g. ignore: [\"**/#{basename}\"])",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

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

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

@@ -44,6 +44,7 @@ module Textus
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
         def events         = {}
         def publish_each   = nil
+        def publish_tree   = nil
         def index_filename = nil
         def ignore         = []
 
@@ -78,27 +79,18 @@ module Textus
           end
         end
 
-        # Subclasses override to customize publish behavior.
-        # Default: copy the stored file to each publish_to target.
-        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Publish#call, or nil to skip.
-        def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil if Array(publish_to).empty?
-
-          source_path = pctx.manifest.resolver.resolve(@key).path
-          envelope = pctx.reader.call(@key)
-
-          publish_to.each do |rel|
-            target_abs = File.join(pctx.repo_root, rel)
-            Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published,
-                      key: @key,
-                      envelope: envelope,
-                      source: source_path,
-                      target: target_abs)
-          end
+        # ADR 0049: an entry resolves, once, to one Publish::* mode that owns its
+        # publish algorithm. A plain entry publishes via ToPaths (publish_to) or
+        # None; Nested resolves among the key/path-driven modes. Derived
+        # overrides publish_via to materialize first.
+        def publish_mode
+          @publish_mode ||= Publish.resolve(self)
+        end
 
-          { kind: :built, value: { "key" => @key, "path" => source_path, "published_to" => publish_to } }
+        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
+        # Write::Publish, or nil to skip.
+        def publish_via(pctx, prefix: nil)
+          publish_mode.publish(pctx, prefix: prefix)
         end
       end
     end