textus 0.42.0 → 0.43.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36d711f8c5947548e8f2431cfded1a514596af239b4eb6e91a3d3d0a6f20c83e
-  data.tar.gz: 33496ad8d0d862655cddbc47c36fd4c3ccf01f7e1b37dea06ee1fc24062be51c
+  metadata.gz: 2c26661afb6c59f813ccdb737e56666be242a14e3315a100348dd8514a41e78a
+  data.tar.gz: 26ff3e7e8cd94a545cdcabe964c6e8c7311fe0179a24a13b0ab298eab7f2bf34
 SHA512:
-  metadata.gz: 6b5b84af6db5f692db3b27f3b029348ab80d7bc9e05d2ebf74d32b9fc9b29d497fb275b508725b8437549f75bc69c1de01818ccc2d1eee4dc2af79cfa292e6dc
-  data.tar.gz: 99f9c63b92f629bd37956a79a303fcc081997d81afe96a85d804d806831388f9d6821b66c449299f82c7f27422e97ada2759518be6062061a45acb8db043d7c9
+  metadata.gz: db6b8047ba7d7c79ad78a653944709d7cc7cfd5c22a4baae116e97c8d6fea48c409788c835e1c1f83c7684a58da089b08a0525a44791de92875d1d2bb0c26a76
+  data.tar.gz: 26e9d74398110f4d34dd59c837901170e5d80a847268f5edee45010f4793c51e1f47737d5d3c85b0098fa06b1334e00bf1038330a12a1061c9957d045e07638c

data/CHANGELOG.md

@@ -9,6 +9,40 @@ 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.
 
+## 0.43.1 — 2026-06-02 — `boot` agent surface derives from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md))
+
+No `textus/3` wire-format change — `boot`'s agent-orientation fields are corrected to match the verbs an MCP agent can actually call.
+
+### Fixed
+
+- **`boot.agent_quickstart.read_verbs` had drifted from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** It was a hand-maintained list that advertised CLI-only read verbs an MCP agent cannot call (`audit`, `freshness`, `doctor`) while omitting the ones it can and needs (`schema`, `rules`). It now **derives** from `MCP::Catalog` (`get list pulse schema boot rules`) and is reconciled by a guard spec, so it can no longer advertise an uncallable verb or omit a callable one. This is what led downstream skills to shell out to a CLI for schema discovery instead of calling the `schema` verb.
+
+### Changed
+
+- **`boot.agent_protocol.recipes` reference verbs, not CLI strings ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** Each recipe step names a verb (`get KEY`, `schema KEY`, `put KEY`, `propose KEY`, `fetch_all`) or a plain build step, instead of a `textus …` / `echo … | textus …` shell line — each transport frames the verb itself (CLI vs MCP tool). Keeps shell syntax out of the surface an MCP agent reads. `human_steps` still name `accept` (the author-only transition, not an MCP tool, by design).
+
+### Added
+
+- **ADR 0054 (Proposed, no implementation): entry-level `desc`.** Records the decision to add an optional one-line `desc:` to manifest entries — surfaced in `boot.entries`/`list` — turning the manifest into a navigable index so an agent finds the right data without a caller hardcoding the key. Pre-registers ADR 0055 (a `find`/search verb) as the evidence-triggered follow-up. Documentation only in this release.
+
+## 0.43.0 — 2026-06-02 — Typed `publish:` block + remove `index_filename` ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md), [0053](docs/architecture/decisions/0053-remove-index-filename.md))
+
+No `textus/3` wire-format change. Two breaking (pre-1.0) changes on the publish/enumeration surface: the two top-level publish keys become one typed `publish:` block, and the unused `index_filename:` enumeration feature is removed. Both fail at load with a migration-pointing message.
+
+### Changed
+
+- **BREAKING (pre-1.0): `publish_to:`/`publish_tree:` folded into one typed `publish:` block ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md)).** Publishing is now configured by `publish: { to: [...] }` (file fan-out) **xor** `publish: { tree: "dir" }` (subtree mirror), mirroring the ADR 0049 internal sum type at the manifest layer and giving a future third mode a namespace instead of a third top-level key. Surface-only — the `Publish::*` modes, `:file_published` event, and build envelope are unchanged. A manifest using the flat `publish_to:`/`publish_tree:` keys **fails at load** with the replacement (`use publish: { to: [...] }` / `{ tree: "..." }`). This is grouping/extensibility, not a new invariant: a block with both `to:` and `tree:` is still caught by the one exclusivity guard in `Publish.resolve`.
+
+### Removed
+
+- **BREAKING (pre-1.0): the `index_filename:` enumeration feature is removed ([ADR 0053](docs/architecture/decisions/0053-remove-index-filename.md)).** `index_filename:` let a nested entry enumerate *directories* as addressable keys via a fixed index file (e.g. `SKILL.md`). It had zero real usage, its only motivating consumer (`EachDir` per-leaf publish) was removed in 0.42.0, and it could not compose with `publish_tree` (mutually exclusive). A nested entry now always enumerates each file under its tree as a key (key segments derived from the path, extension stripped). A manifest declaring `index_filename:` **fails at load** with a migration message; to mirror a directory of files to a consumer path without enumerating them as keys, use `publish: { tree: "..." }`. Native skill authoring (ADR 0050) is unaffected — it rides `publish_tree`, which never enumerated an index. The shallowest-index-wins claiming logic (ADR 0046 D5) and the `index_filename ⊥ publish_tree` guard go with it.
+
+No `textus/3` wire-format change — repo-local publish behaviour only.
+
+### Fixed
+
+- **`publish_tree` files are now opaque in *every* path, not just the Publisher ([ADR 0047](docs/architecture/decisions/0047-publish-tree-keyless-subtree-mirror.md)).** A keyless subtree mirror carrying non-key-legal filenames (uppercase `SKILL.md`, `README`) tripped `doctor`'s `key.illegal` and red-gated commits, even though publish itself mirrored the files correctly — `doctor`'s `IllegalKeys` and `Resolver#enumerate_nested` still key-walked them, contradicting ADR 0047's "no keys" contract. The resolved publish mode now answers `Publish::Mode#keyless?` (true only for `Tree`); both paths consult it and skip enumerating a keyless mirror's files. A `publish_tree` subtree with uppercase filenames stays `doctor`-green and still mirrors; a non-publish nested entry still flags illegal segments as before.
+
 ## 0.42.0 — 2026-06-02 — Remove `publish_each`: collapse publish to two modes ([ADR 0051](docs/architecture/decisions/0051-remove-publish-each.md))
 
 No `textus/3` wire-format change. **Breaking (pre-1.0):** the `publish_each:` manifest key is removed; a manifest declaring it now fails at load. The publish surface collapses to two modes — `publish_to:` (fixed paths) and `publish_tree:` (whole-subtree mirror) — plus `None`.

data/README.md

@@ -182,7 +182,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, a template
 
 ## What's shipped
 
-- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; `publish_to:`/`publish_tree:` byte-copy derived files (or a whole subtree) to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
+- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × zone-kind gate.** Writes carry `--as=<role>`; a role may write a zone iff it holds the capability the zone's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `quarantine`→`fetch`, `queue`→`propose`, `derived`→`build`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
@@ -203,7 +203,7 @@ Derived entries declare `compute: { kind: projection, select: ..., pluck: ..., s
 
 For externally-generated entries, declare `compute: { kind: external, sources: [...] }` — textus tracks the declared sources for staleness; the build automation produces the file.
 
-`publish_to: [path]` byte-copies a single derived file to one or more targets. `publish_tree: "dir"` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052). `publish: { to: [path, ...] }` byte-copies a single derived file to one or more targets. `publish: { tree: "dir" }` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
 
 ## Extension points
 

data/SPEC.md

@@ -24,7 +24,7 @@
   - [5.2 Compute layer (derived entries)](#52-compute-layer-derived-entries)
     - [5.2.1 Projection compute](#521-projection-compute-kind-projection)
     - [5.2.2 External compute](#522-external-compute-kind-external)
-  - [5.3 Publish layer](#53-publish-layer-publish_to)
+  - [5.3 Publish layer](#53-publish-layer-publish)
   - [5.4 Intake](#54-intake-declared-fetched-via-registered-intake-handler)
   - [5.5 Pending / accept workflow](#55-pending--accept-workflow)
   - [5.6 Audit log](#56-audit-log)
@@ -100,7 +100,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 | L1 | **Store** | Plain-file backend: `.textus/zones/<zone>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
 | L2 | **Sources** | Declared external inputs (the `feeds` zone in the default scaffold; any `quarantine` zone, writable by a role with `fetch`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external automation fetches and pipes results through `textus put`. |
 | L3 | **Compute** | Pure transforms from store entries to derived entries. Projections (select/pluck/sort/limit/format) plus a vendored Mustache template subset. No shell execution. |
-| L4 | **Publish** | Byte-for-byte file copy from derived entries to repo-relative paths declared via `publish_to:`. The in-store artifact is the consumer-shaped output; the published file is an identical copy. A sentinel under `.textus/sentinels/<target-rel-path>.textus-managed.json` records the source, sha256, and `mode: "copy"`. |
+| L4 | **Publish** | Byte-for-byte file copy from derived entries to repo-relative paths declared via `publish: { to: [...] }`. The in-store artifact is the consumer-shaped output; the published file is an identical copy. A sentinel under `.textus/sentinels/<target-rel-path>.textus-managed.json` records the source, sha256, and `mode: "copy"`. |
 | L5 | **Consumers** | Anything that reads the published files or calls the CLI — editors, LLM tools, MCP servers, CI jobs, dashboards. textus is agnostic about who consumes; the envelope is the contract. |
 
 ## 2. Goals and non-goals
@@ -197,14 +197,14 @@ entries:
     path: knowledge/network/org
     zone: knowledge
     schema: person
-    owner: textus:network
+    owner: human:network
     nested: true
 
   - key: artifacts.catalogs.people
     path: artifacts/catalogs/people.md
     zone: artifacts
     schema: null
-    owner: textus:build
+    owner: automation:build
 
 rules:
   - match: feeds.**
@@ -228,21 +228,11 @@ Zone names are conventional — write authority comes from each zone's declared
 | `yaml`     | `.yaml` or `.yml` required  | optional (escape hatch) | optional (top-level keys) |
 | `text`     | `.txt` or no extension      | required for derived | MUST be null |
 
-For `nested: true`, the recursive glob matches the format's extension (markdown→`**/*.md`, json→`**/*.json`, yaml→`**/*.{yaml,yml}`, text→`**/*.txt`). All files under one nested entry share one format and one schema.
+For `nested: true`, the recursive glob matches the format's extension (markdown→`**/*.md`, json→`**/*.json`, yaml→`**/*.{yaml,yml}`, text→`**/*.txt`). All files under one nested entry share one format and one schema. Each matching file is enumerated as its own key, with the key segments derived from the path relative to the entry (extension stripped). A nested entry that instead mirrors a whole directory of files to a consumer path — without enumerating any of them as keys — uses `publish: { tree: }` (below); its files are opaque payload. (The former `index_filename:` directory-keyed enumeration was removed in 0.43.0 — ADR 0053.)
 
-**Per-entry `index_filename:`.** A nested entry MAY declare `index_filename:` to surface a single fixed basename (e.g. `SKILL.md`) per directory as the row, with the row's key segments derived from the directory path. Sibling files are not enumerated. The basename's extension MUST match the entry's `format:`. This lets entries project spec-mandated filenames whose casing would otherwise be rejected by the key-segment grammar. Example:
+**The `publish:` block (ADR 0052).** Publishing is configured by one typed `publish:` block with exactly one of two sub-keys — `publish: { to: [...] }` (file fan-out, §5.3) **xor** `publish: { tree: "dir" }` (subtree mirror, below). Setting both is an error. The legacy top-level `publish_to:` / `publish_tree:` keys are rejected at load with a migration message.
 
-```yaml
-- key: skills
-  path: skills
-  zone: skills
-  nested: true
-  index_filename: SKILL.md
-```
-
-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). `index_filename:` is a pure *enumeration* feature — it selects which file is the addressable row per directory and is independent of publishing (ADR 0051).
-
-**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). 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 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.
+**Subtree mirror (`publish: { tree: }`).** A nested manifest entry MAY declare `publish: { tree: "dir" }` to mirror its entire stored subtree (`zones/<path>/**`) to a single target directory, preserving relative layout (case and extension preserved). 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). 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 mirroring 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
@@ -250,7 +240,8 @@ A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.text
   zone: working
   schema: skill
   nested: true
-  publish_tree: "skills"
+  publish:
+    tree: "skills"
   ignore: ["*.tmp", ".DS_Store"]
 ```
 
@@ -413,7 +404,7 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 - key: output.catalogs.skills
   path: output/catalogs/skills.md
   zone: output
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; external automation invokes it
@@ -444,21 +435,24 @@ generated:
 
 `kind: external` and `kind: projection` are alternatives — exactly one per entry. Templates are not required for `kind: external`: the external automation produces the bytes directly.
 
-### 5.3 Publish layer (`publish_to:`)
+### 5.3 Publish layer (`publish:`)
+
+Publishing is configured by one typed `publish:` block with exactly one sub-key (ADR 0052): `to:` (file fan-out) **xor** `tree:` (subtree mirror). Setting both is an error; the legacy top-level `publish_to:` / `publish_tree:` keys are rejected at load with a migration message.
 
-A derived entry MAY declare `publish_to:` in its frontmatter, listing one or more destination paths relative to the project root:
+A derived entry MAY declare `publish: { to: [...] }`, listing one or more destination paths relative to the project root:
 
 ```yaml
-publish_to:
-  - CLAUDE.md
-  - .ai/instructions.md
+publish:
+  to:
+    - CLAUDE.md
+    - .ai/instructions.md
 ```
 
 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, 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.
 
-**Subtree mirror.** A nested entry MAY declare `publish_tree:` instead of `publish_to:` (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. The build envelope grows a `published_leaves` array — one row per mirrored file, with `key`, `source`, and `target` — alongside the existing `built` array, plus a `pruned` array listing any orphaned managed files removed on this build. `publish_tree:` is mutually exclusive with `publish_to:`, and incompatible with `index_filename:`. Targets that would resolve outside the repo root are refused. 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).
+**Subtree mirror.** A nested entry MAY declare `publish: { tree: "dir" }` instead of `to:` (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. The build envelope grows a `published_leaves` array — one row per mirrored 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. When a `publish.tree` target overlaps a `derived` entry's `publish.to` (e.g. a derived `SKILL.md` written into the mirrored dir), the mirroring 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)
 
@@ -806,7 +800,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "protocol": "textus/3",
   "key": "knowledge.network.org.jane",
   "zone": "knowledge",
-  "owner": "textus:network",
+  "owner": "human:network",
   "path": "/absolute/path/to/.textus/zones/knowledge/network/org/jane.md",
   "format": "markdown",
   "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
@@ -904,7 +898,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 ```json
 {
   "agent_quickstart": {
-    "read_verbs":     ["boot", "get", "list", "audit", "pulse", "freshness", "doctor"],
+    "read_verbs":     ["get", "list", "pulse", "schema", "boot", "rules"],
     "write_verbs":    ["put KEY --as=agent --stdin"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
@@ -913,6 +907,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 }
 ```
 
+`read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema` for an entry's field shape, `rules` for its freshness/guard policy) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema` verb before a `put`/`propose`, not by shelling out to a CLI.
+
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
 **`textus pulse` output shape:**
@@ -1018,7 +1014,7 @@ Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: project
 Given a derived entry with a `template` clause referencing a `.mustache` file and inputs drawn from other keys, `textus build` produces a body whose contents match the expected rendered output byte-for-byte (after trailing-newline normalization).
 
 **Fixture G — Copy publish:**
-Given a manifest entry with `publish_to: <path>`, a successful `textus build` for that entry leaves a plain file at `<path>` whose contents are byte-identical to the in-store artifact at `.textus/zones/<...>`, accompanied by a sentinel at `.textus/sentinels/<path>.textus-managed.json` recording `source`, `target`, `sha256`, and `mode: "copy"`. Re-running `build` is idempotent.
+Given a manifest entry with `publish: { to: [<path>] }`, a successful `textus build` for that entry leaves a plain file at `<path>` whose contents are byte-identical to the in-store artifact at `.textus/zones/<...>`, accompanied by a sentinel at `.textus/sentinels/<path>.textus-managed.json` recording `source`, `target`, `sha256`, and `mode: "copy"`. Re-running `build` is idempotent.
 
 **Fixture H — Audit log format:**
 Every successful write verb (`put`, `delete`, `build`, `accept`, `schema migrate`) appends exactly one line per affected key to the audit log, in the canonical format defined in §audit (timestamp, actor role, verb, key, etag-before, etag-after). No write produces zero or multiple lines per key.

data/docs/architecture/README.md

@@ -1,7 +1,7 @@
 # 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)
+> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-06 (v0.43)
 
 ```mermaid
 flowchart TD

data/docs/reference/conventions.md

@@ -1,7 +1,7 @@
 # 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)
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-06 (v0.43)
 
 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*.
 
@@ -39,11 +39,11 @@ Inside `knowledge/`, group by **domain** (identity, people, projects, decisions,
 
 ## Owner strings
 
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
+The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*. The form is `<archetype>` or `<archetype>:<subject>`; the archetype must be one of `human`, `agent`, `automation` (validated at load — ADR 0045), and the subject is free-form:
 
-- `textus:network` — humans curate
+- `human:network` — humans curate
 - `agent:planner` — a specific named agent
-- `build:catalog-skills` — a specific build job
+- `automation: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.
 
@@ -58,14 +58,15 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
   path: artifacts/catalogs/people.md
   zone: artifacts
   schema: null
-  owner: build:catalog-people
+  owner: automation: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
+  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`).
@@ -74,7 +75,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
 - key: artifacts.catalogs.skills
   path: artifacts/catalogs/skills.md
   zone: artifacts
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; the automation invokes it
@@ -83,7 +84,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
 
 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 subtree publishing (`publish_tree:`) are also covered there.
+Full contract for both shapes is in [`../../SPEC.md` §5.2.1 and §5.2.2](../../SPEC.md). Transforms (`compute.transform:`) and subtree publishing (`publish: { tree: }`) are also covered there.
 
 ## Intake and freshness
 
@@ -105,7 +106,7 @@ rules:
 A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
 
 ```sh
-textus fetch stale --zone=intake --as=automation   # in cron / CI
+textus fetch stale --zone=feeds --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.
@@ -136,7 +137,7 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 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.
+- **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`); `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.

data/lib/textus/boot.rb

@@ -127,7 +127,10 @@ module Textus
       propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
-        "read_verbs" => %w[boot get list audit pulse freshness doctor],
+        # Derived from the MCP catalog (ADR 0056): the agent's real read surface,
+        # so the quickstart can neither advertise a verb the agent cannot call
+        # (audit/freshness/doctor are CLI-only) nor omit one it can (schema/rules).
+        "read_verbs" => Textus::MCP::Catalog.read_verbs,
         "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
@@ -135,6 +138,10 @@ module Textus
       }
     end
 
+    # Recipes reference verbs, not a transport's CLI strings (ADR 0056): every
+    # step names a verb the agent can call (each transport frames it — CLI as
+    # `textus get KEY`, MCP as the `get` tool) or is a plain build step. This
+    # keeps shell lines out of the surface an MCP agent reads.
     def self.recipes(manifest)
       queue = manifest.policy.queue_zone
       feeds = zone_label(manifest, :quarantine, "the quarantine zone")
@@ -142,32 +149,32 @@ module Textus
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
-            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
-            "textus get KEY                            # returns envelope JSON",
+            "list (zone:, prefix:) — discover keys without reading bodies",
+            "get KEY — returns the entry envelope",
           ],
         },
         "write" => {
           "purpose" => "create or update an entry",
           "steps" => [
-            "textus schema get FAMILY                  # learn the _meta field shape",
-            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
-            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
+            "schema KEY — learn the _meta field shape (required, optional, field types) before writing",
+            "assemble an envelope: { _meta: {…}, body: \"…\" }",
+            "put KEY — persist it (role-gated); pass if_etag to guard a concurrent edit",
           ],
         },
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "echo ENVELOPE | textus put #{queue}.KEY --as=agent --stdin",
+            "propose KEY — writes the change into the #{queue} zone for review",
           ],
           "human_steps" => [
-            "textus accept #{queue}.KEY --as=human       # promotes the proposal to its target zone",
+            "accept #{queue}.KEY — promotes the proposal into its target zone",
           ],
         },
         "fetch" => {
-          "purpose" => "rebuild stale quarantine-zone caches from their declared actions",
+          "purpose" => "refresh stale quarantine-zone caches from their declared intake",
           "steps" => [
-            "textus freshness --zone=#{feeds}            # report fresh/stale per entry",
-            "textus fetch stale --zone=#{feeds} --as=automation",
+            "pulse — its `stale` list names entries past their ttl",
+            "fetch_all (zone: #{feeds}) — re-pull the stale entries",
           ],
         },
       }

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

@@ -6,12 +6,12 @@ module Textus
           out = []
           manifest.data.entries.each do |entry|
             next unless entry.nested?
+            next if entry.publish_mode.keyless? # publish_tree files are opaque payload, never keys (ADR 0047)
 
             base = File.join(root, "zones", entry.path)
             next unless File.directory?(base)
 
-            index_fn = entry.respond_to?(:index_filename) ? entry.index_filename : nil
-            index_fn ? check_index_paths(entry, index_fn, base, out) : check_all_paths(entry, base, out)
+            check_all_paths(entry, base, out)
           end
           out
         end
@@ -31,24 +31,6 @@ module Textus
           end
         end
 
-        # When the entry uses `index_filename:`, only the parent-directory
-        # segments leading to each index file participate in keys. Sibling
-        # files and unrelated subtrees are not enumerated and must not be
-        # flagged. Each illegal segment is reported once per path. Paths under
-        # an ignored subtree (ADR 0042) are excluded before any segment check.
-        def check_index_paths(entry, index_fn, base, out)
-          Dir.glob(File.join(base, "**", index_fn)).each do |fp|
-            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-            next if entry.ignored?(rel)
-
-            File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
-              next if seg.match?(Key::Grammar::SEGMENT)
-
-              out << issue(fp, seg)
-            end
-          end
-        end
-
         def issue(abs_path, stem)
           {
             "code" => "key.illegal",

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

@@ -44,7 +44,6 @@ module Textus
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
         def events         = {}
         def publish_tree   = nil
-        def index_filename = nil
         def ignore         = []
 
         # Per-entry ignore (ADR 0042). Base entries enumerate no tree, so

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

@@ -6,11 +6,10 @@ module Textus
       # Entry::Publish::* — Nested is just the value (attributes + ignore
       # predicate) those modes read.
       class Nested < Base
-        attr_reader :index_filename, :publish_tree, :ignore
+        attr_reader :publish_tree, :ignore
 
-        def initialize(index_filename: nil, publish_tree: nil, ignore: nil, **rest)
+        def initialize(publish_tree: nil, ignore: nil, **rest)
           super(**rest)
-          @index_filename = index_filename
           @publish_tree = publish_tree
           @ignore = Array(ignore)
         end
@@ -26,8 +25,7 @@ module Textus
 
         def self.from_raw(common, raw)
           new(
-            index_filename: raw["index_filename"],
-            publish_tree: raw["publish_tree"],
+            publish_tree: raw.dig("publish", "tree"), # ADR 0052: typed publish block
             ignore: raw["ignore"],
             **common,
           )

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

@@ -18,7 +18,10 @@ module Textus
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
             format: format,
-            publish_to: raw["publish_to"]
+            # ADR 0052: publish config is one typed block; the internal
+            # publish_to/publish_tree readers (the ADR 0049 modes) are sourced
+            # from it (publish_to <- publish.to, publish_tree <- publish.tree).
+            publish_to: raw.dig("publish", "to")
           }
 
           klass = Entry::REGISTRY[kind] or

data/lib/textus/manifest/entry/publish/mode.rb

@@ -17,6 +17,12 @@ module Textus
           # No shape rules by default — ToPaths/None publish without templating.
           def validate!; end
 
+          # Whether this entry's subtree files are opaque payload that must
+          # never be enumerated as keys. Only Tree (publish_tree, ADR 0047)
+          # overrides to true; doctor's IllegalKeys and the resolver consult
+          # this so they stop key-walking a keyless mirror's files.
+          def keyless? = false
+
           private
 
           # Expand `rel` under repo_root and confirm it stays inside it.

data/lib/textus/manifest/entry/publish/to_paths.rb

@@ -2,8 +2,8 @@ module Textus
   class Manifest
     class Entry
       module Publish
-        # publish_to: copy the entry's one stored file to each fixed repo path.
-        # The default behaviour of any entry that declares `publish_to:`.
+        # publish.to: copy the entry's one stored file to each fixed repo path.
+        # The behaviour of any entry that declares `publish: { to: [...] }`.
         class ToPaths < Mode
           def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
             targets = Array(entry.publish_to)

data/lib/textus/manifest/entry/publish/tree.rb

@@ -8,6 +8,9 @@ module Textus
         # (e.g. a SKILL.md written by a separate entry into the same dir)
         # survives the whole-target prune (ADR 0047 D4).
         class Tree < Mode
+          # Mirrored files are opaque payload, never addressable keys (ADR 0047).
+          def keyless? = true
+
           def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
             target_rel = entry.publish_tree
             target_dir = repo_abs(pctx, target_rel)
@@ -30,20 +33,13 @@ module Textus
 
           def validate!
             publish_tree = entry.publish_tree
-            raise UsageError.new("entry '#{entry.key}': publish_tree must be a string") unless publish_tree.is_a?(String)
-
-            unless entry.index_filename.nil?
-              raise UsageError.new(
-                "entry '#{entry.key}': index_filename and publish_tree are mutually exclusive — " \
-                "publish_tree mirrors a whole subtree by path and never enumerates an index.",
-              )
-            end
+            raise UsageError.new("entry '#{entry.key}': publish.tree must be a string") unless publish_tree.is_a?(String)
 
             used_vars = publish_tree.scan(Template::VAR_RE).flatten
             return if used_vars.empty?
 
             raise UsageError.new(
-              "entry '#{entry.key}': publish_tree names a single directory and takes no template variable(s) " \
+              "entry '#{entry.key}': publish.tree names a single directory and takes no template variable(s) " \
               "#{used_vars.map { |v| "{#{v}}" }.join(", ")} — it mirrors the whole subtree to one target dir.",
             )
           end

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

@@ -5,26 +5,28 @@ module Textus
       # realized as one resolved sum type. Each directory entry resolves, once,
       # to one Publish::* mode that owns its publish algorithm — no nil-cascade,
       # no pairwise exclusivity guards, one shared subtree mirror. ADR 0051
-      # removed `publish_each` (both leaf modes); the surface is now two modes:
+      # removed `publish_each` (both leaf modes); ADR 0052 folded the two surviving
+      # keys into one `publish:` block (`to:` xor `tree:`). The surface is two modes:
       #
-      #   None      — nothing to publish
-      #   ToPaths   — publish_to: 1 stored file -> N fixed repo paths
-      #   Tree      — publish_tree: whole entry subtree -> 1 dir, no keys
+      #   None      — nothing to publish (no publish: block)
+      #   ToPaths   — publish: { to: [...] }  — 1 stored file -> N fixed repo paths
+      #   Tree      — publish: { tree: "dir" } — whole entry subtree -> 1 dir, no keys
       module Publish
-        # Resolve an entry to its single publish mode. Raises one UsageError if
-        # both publish_to and publish_tree are set — exclusivity is structural
-        # here, not scattered pairwise guards. A removed `publish_each:` key is
-        # rejected loudly with its replacement (ADR 0051).
+        # Resolve an entry to its single publish mode. The publish config is the
+        # ADR 0052 `publish:` block, sourced into entry.publish_to/publish_tree.
+        # Raises one UsageError if both `publish.to` and `publish.tree` are set —
+        # the block groups the two but does not make exclusivity structural, so
+        # this stays the one enforcement point (ADR 0052 D2).
         def self.resolve(entry)
           reject_removed_publish_each(entry)
 
           set = []
-          set << "publish_to"   unless Array(entry.publish_to).empty?
-          set << "publish_tree" unless entry.publish_tree.nil?
+          set << "publish.to"   unless Array(entry.publish_to).empty?
+          set << "publish.tree" unless entry.publish_tree.nil?
 
           if set.length > 1
             raise Textus::UsageError.new(
-              "entry '#{entry.key}': #{set.join(", ")} are mutually exclusive — an entry publishes exactly one way",
+              "entry '#{entry.key}': #{set.join(" and ")} are mutually exclusive — an entry publishes exactly one way",
             )
           end
 
@@ -36,15 +38,15 @@ module Textus
 
           raise Textus::UsageError.new(
             "entry '#{entry.key}': publish_each was removed in 0.42.0 (ADR 0051) — " \
-            "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+            "mirror the subtree with `publish: { tree: \"...\" }`.",
           )
         end
         private_class_method :reject_removed_publish_each
 
         def self.mode_for(entry, key)
           case key
-          when "publish_to"   then ToPaths.new(entry)
-          when "publish_tree" then Tree.new(entry)
+          when "publish.to"   then ToPaths.new(entry)
+          when "publish.tree" then Tree.new(entry)
           else None.new(entry)
           end
         end

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

@@ -8,11 +8,13 @@ module Textus
         # the scattered pairwise "not-both" guards of the old PublishEach +
         # PublishTree validators. Misuse on a non-nested entry is still caught
         # here from raw, since the typed attrs stub nil on Base. (publish_each was
-        # removed in 0.42.0 — ADR 0051; Schema rejects it at load.)
+        # removed in 0.42.0 — ADR 0051; the publish_to/publish_tree keys were folded
+        # into the `publish:` block in 0.43.0 — ADR 0052; Schema rejects the retired
+        # flat keys at load.)
         module Publish
           def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             unless entry.nested?
-              raise UsageError.new("entry '#{entry.key}': publish_tree requires nested: true") if entry.raw["publish_tree"]
+              raise UsageError.new("entry '#{entry.key}': publish.tree requires nested: true") if entry.raw.dig("publish", "tree")
 
               return
             end

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

@@ -6,7 +6,6 @@ module Textus
           Events,
           Publish,
           InjectBoot,
-          IndexFilename,
           Ignore,
           FormatMatrix,
         ].freeze

data/lib/textus/manifest/resolver.rb

@@ -51,13 +51,8 @@ module Textus
         else
           raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless nested_entry?(entry)
 
-          index_fn = entry.index_filename
-          path = if index_fn
-                   File.join(@data.root, "zones", entry.path, *remaining, index_fn)
-                 else
-                   primary_ext = Textus::Entry.for_format(entry.format).extensions.first
-                   File.join(@data.root, "zones", entry.path, *remaining) + primary_ext
-                 end
+          primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+          path = File.join(@data.root, "zones", entry.path, *remaining) + primary_ext
           Resolution.new(entry: entry, path: path, remaining: remaining)
         end
       end
@@ -68,33 +63,22 @@ module Textus
       end
 
       def enumerate_nested(entry)
+        # publish_tree mirrors opaque payload by path — its files are never
+        # enumerated as keys (ADR 0047). Ask the resolved mode, not the path.
+        return [] if entry.publish_mode.keyless?
+
         base = File.join(@data.root, "zones", entry.path)
         return [] unless File.directory?(base)
 
-        entry_index_filename = entry.index_filename
-        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
+        Dir.glob(File.join(base, nested_glob(entry.format)))
+           .filter_map { |path| nested_row_for(entry, base, path) }
       end
 
       def nested_row_for(entry, base, path)
         rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
         return nil if entry.ignored?(rel)
 
-        entry_if = entry.index_filename
-        stripped = entry_if ? File.dirname(rel) : rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+        stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
         segs = stripped.split("/").reject { |s| s.empty? || s == "." }
         return nil if segs.empty?
 

data/lib/textus/manifest/schema.rb

@@ -24,9 +24,12 @@ module Textus
       KIND_REQUIRES_VERB = LANES
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
-        compute template publish_to publish_tree
-        intake events inject_boot index_filename ignore tracked
+        compute template publish
+        intake events inject_boot ignore tracked
       ].freeze
+      # ADR 0052: the typed publish block — `publish: { to: [...] }` (file
+      # fan-out) xor `publish: { tree: "dir" }` (subtree mirror).
+      PUBLISH_KEYS = %w[to tree].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
       RULE_KEYS    = %w[match fetch intake_handler_allowlist guard retention].freeze
@@ -73,25 +76,62 @@ module Textus
       def self.validate_entries!(entries)
         Array(entries).each_with_index do |e, i|
           path = "$.entries[#{i}]"
-          reject_removed_publish_each!(e, path)
+          reject_retired_publish_keys!(e, path)
           walk(e, ENTRY_KEYS, path)
+          validate_publish_block!(e, path)
           walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
           walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
         end
       end
 
-      # publish_each was removed in 0.42.0 (ADR 0051). It is no longer an allowed
-      # entry key, so `walk` would reject it as merely "unknown"; intercept it
-      # first with the migration path so a pre-0.42 manifest gets a useful error.
-      def self.reject_removed_publish_each!(entry, path)
-        return unless entry.is_a?(Hash) && entry.key?("publish_each")
+      # Retired keys are no longer allowed, so `walk` would reject them as merely
+      # "unknown"; intercept first with the migration path so a pre-0.43 manifest
+      # gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/
+      # `publish_tree` were folded into the `publish:` block (ADR 0052);
+      # `index_filename` was removed (ADR 0053).
+      def self.reject_retired_publish_keys!(entry, path)
+        return unless entry.is_a?(Hash)
+
+        if entry.key?("publish_each")
+          raise BadManifest.new(
+            "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
+            "mirror the subtree with `publish: { tree: \"...\" }`.",
+          )
+        end
+
+        if entry.key?("publish_to")
+          raise BadManifest.new(
+            "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
+            "use `publish: { to: [...] }`.",
+          )
+        end
+
+        if entry.key?("publish_tree")
+          raise BadManifest.new(
+            "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
+            "use `publish: { tree: \"...\" }`.",
+          )
+        end
+
+        return unless entry.key?("index_filename")
 
         raise BadManifest.new(
-          "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-          "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+          "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
+          "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
         )
       end
 
+      # Shape of the ADR 0052 publish block: a Hash whose only keys are to/tree.
+      # Exclusivity (both set) and per-mode rules stay in Publish.resolve (ADR 0049).
+      def self.validate_publish_block!(entry, path)
+        return unless entry.is_a?(Hash) && entry.key?("publish")
+
+        block = entry["publish"]
+        raise BadManifest.new("publish: must be a mapping with `to:` or `tree:` at '#{path}.publish'") unless block.is_a?(Hash)
+
+        walk(block, PUBLISH_KEYS, "#{path}.publish")
+      end
+
       def self.validate_rules!(rules)
         Array(rules).each_with_index do |r, i|
           path = "$.rules[#{i}]"

data/lib/textus/mcp/catalog.rb

@@ -11,7 +11,7 @@ module Textus
       # Contracts of every MCP-surfaced verb, in Dispatcher order.
       def specs
         Textus::Dispatcher::VERBS.values
-                                 .select { |k| k.respond_to?(:contract?) && k.contract? && k.contract.mcp? }
+                                 .select { |k| mcp_surfaced?(k) }
                                  .map(&:contract)
       end
 
@@ -25,9 +25,23 @@ module Textus
         specs.map { |s| s.verb.to_s }
       end
 
+      # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
+      # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
+      # from this so it can never advertise a verb the agent cannot call, nor
+      # omit one it can (ADR 0056). Excludes Write/Maintenance.
+      def read_verbs
+        Textus::Dispatcher::VERBS
+          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Read::") }
+          .keys.map(&:to_s)
+      end
+
+      def mcp_surfaced?(klass)
+        klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+      end
+
       def call(name, session:, store:, args:)
         klass = Textus::Dispatcher::VERBS[name.to_sym]
-        raise ToolError.new("unknown tool: #{name}") unless klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+        raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
 
         spec = klass.contract
         pos, kw = map_args(spec, args || {}, session)

data/lib/textus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.43.1
 platform: ruby
 authors:
 - Patrick
@@ -271,7 +271,6 @@ files:
 - lib/textus/manifest/entry/validators/events.rb
 - lib/textus/manifest/entry/validators/format_matrix.rb
 - lib/textus/manifest/entry/validators/ignore.rb
-- lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_boot.rb
 - lib/textus/manifest/entry/validators/publish.rb
 - lib/textus/manifest/policy.rb

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

@@ -1,47 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module IndexFilename
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
-            index_filename = entry.nested? ? entry.index_filename : entry.raw["index_filename"]
-            return if index_filename.nil?
-
-            check_shape!(entry, index_filename)
-            check_extension!(entry, index_filename)
-          end
-
-          def self.check_shape!(entry, index_filename)
-            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested?
-
-            unless index_filename.is_a?(String) && !index_filename.empty?
-              raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
-            end
-
-            return unless index_filename.include?("/") || File.basename(index_filename) != index_filename
-
-            raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
-          end
-
-          def self.check_extension!(entry, index_filename)
-            ext = File.extname(index_filename)
-            inferred = Textus::Entry.infer_from_extension(ext)
-
-            if inferred.nil?
-              raise UsageError.new(
-                "entry '#{entry.key}': index_filename #{index_filename.inspect} has unknown extension #{ext.inspect}",
-              )
-            end
-            return if inferred == entry.format
-
-            raise UsageError.new(
-              "entry '#{entry.key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
-              "but entry format is #{entry.format.inspect}",
-            )
-          end
-        end
-      end
-    end
-  end
-end