textus 0.10.4 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efe7d1a6ddffa757d720b66fbd52c0685691e4b2b6beaa042552b7f154878f21
-  data.tar.gz: f8eb5a0656c343d4b6990710aa39ecf80d1a19908f4b9d9be365ab19bf443deb
+  metadata.gz: e14d58006851be5feba9ffa7016f5860b0ea380cef09cbf324a897d24ae56ee8
+  data.tar.gz: f928e250b5c3bc6e072c1ffc1928e68fdf61d2965d1746c121657ad4bd07ac75
 SHA512:
-  metadata.gz: ac44def8227532f58b69da7c0d6f1783299a174f1ac4e278074aba52a20de3da6bc14fd0df10db824dce8991a6bd65ba970994d703702586dce0ae91f66a89fa
-  data.tar.gz: 6a3e41cc32743bb1a7ff8cb23a16d8a775bfa1ec0758fb69398047ec8517a8d47579e9c2ab6e78159a064b8f7624591aa34f3667151324c72bd5f8c6050e4be4
+  metadata.gz: 6eb5690e16fc78f71b42a5f4308d7698684b5aa9f43a92534f73edca5fc36494be65bfab6df2d8d0832f788e7fe7496638ad23f83ee6f69f5a9950b419237745
+  data.tar.gz: aa3b5903ff1fb44dcc5d1bb3f0676bffb9d8cce99c6e6237f2d947b3486e3d0cfce53271fcf282b927ea1b2e9b1164e721ed0800ddd5ffde1644f85dd660339a

data/CHANGELOG.md

@@ -5,8 +5,133 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 The **gem version** (`0.x.y`) is distinct from the **protocol version**
-(currently `textus/2`, embedded in every envelope as `protocol`). The protocol
-is additive within a major; a new major would change the wire string.
+(currently `textus/3`, embedded in every envelope as `protocol`). A protocol
+bump is a breaking change that requires a store migration; the gem version
+tracks both additive improvements and breaking protocol bumps independently.
+
+## 0.12.1 — textus/2 hint fix (2026-05-26)
+
+### Fixed
+- Manifest parser now points textus/2 stores at the 0.11.x stepping-stone
+  migrator instead of the misleading "check YAML frontmatter for syntax errors"
+  hint. The protocol_version doctor check carried the correct hint already, but
+  was unreachable on textus/2 stores because `Store.discover` → `Manifest.load`
+  raises before doctor checks run. Surfaced by v0.12.0 release smoke testing.
+
+## 0.12.0 — legacy sweep (2026-05-25)
+
+### Removed (breaking)
+- `Role::LEGACY_RENAMES` (`ai`/`script`/`build` → friendly error). Legacy role
+  names now fail with the generic `InvalidRole` error.
+- `Manifest::LEGACY_ZONE_RENAMES` (`inbox` → friendly error).
+- `Hooks::Registry::LEGACY_EVENT_RENAMES` (14 legacy event names → friendly
+  error). Legacy events now fail with `unknown event: <name>`.
+- `CLI::LEGACY_VERB_RENAMES` / `CLI::LEGACY_GROUP_RENAMES` and the
+  `CommandRenamed` error class.
+- `textus migrate --to=textus/3` verb and `lib/textus/migration/**` (eight
+  files, ~924 lines).
+- Eight ad-hoc legacy-key guards in `manifest.rb` / `manifest/entry.rb` /
+  `manifest/rules.rb`.
+
+### Added
+- `Manifest::Schema.validate!` — strict-unknown-keys parser. Manifests with
+  any unrecognized key fail uniformly with `unknown key 'X' at '<jsonpath>'`.
+- ADR 0003 documenting the sweep and the 0.11.x stepping-stone path.
+
+### Changed
+- `Doctor::Check::ProtocolVersion` hint no longer suggests `textus migrate`
+  (the verb is gone); points at 0.11.x docs instead.
+- Test suite consolidated: five batches of disciplined deletions/merges
+  (−4 files, −134 LOC from the post-P6 peak). Net effect across the release:
+  test suite grew +8.2% LOC to cover new behavior (schema walker, permissive
+  audit-log tolerance).
+
+### Migration
+- **From textus/2 (gem ≤0.10.x):** install textus 0.11.x first; run
+  `textus migrate --to=textus/3`; then upgrade to 0.12.0.
+- **From 0.11.x:** drop-in upgrade.
+
+## 0.11.0 — textus/3 vocabulary redesign (2026-05-25)
+
+**BREAKING:** Protocol bumps to `textus/3`. Stores authored on 0.10.x must run `textus migrate --to=textus/3` before installing 0.11.0. `textus doctor` refuses to operate on un-migrated stores.
+
+### Renamed — actors
+
+- `ai` → `agent`, `script` → `runner`, `build` → `builder`. `Role.resolve` rejects legacy names with a one-line migration hint pointing at `--as=<new>`.
+
+### Renamed — zone
+
+- `inbox` → `intake`. Directory rename + key prefix update + manifest field handled by the migrator.
+
+### Renamed — manifest schema
+
+- `writable_by:` → `write_policy:`; new explicit `read_policy:` on zones (default `[all]`).
+- `policies:` (top-level) → `rules:`. Class rename: `Manifest::Policies` → `Manifest::Rules`.
+- `projection:` and `generator:` unified under `compute: { kind: projection|external, ... }`.
+- `reduce:` (inside compute/projection) → `transform:`.
+- `handler_allowlist:` → `intake_handler_allowlist:`.
+- `promote_requires:` (reserved in textus/2) → `promotion: { requires: [...] }` and is now **enforced** during `textus accept`.
+
+### Renamed — hook events
+
+- RPC: `:intake` → `:resolve_intake`, `:reduce` → `:transform_rows`, `:check` → `:validate`.
+- Pub-sub (object_pasttense): `:put` → `:entry_put`, `:deleted` → `:entry_deleted`, `:built` → `:build_completed`, `:mv` → `:entry_renamed`, `:accepted` → `:proposal_accepted`, `:reject` → `:proposal_rejected`, `:published` → `:file_published`, `:loaded` → `:store_loaded`, `:refreshed` → `:entry_refreshed`, `:refresh_began` → `:refresh_started`, `:refresh_detached` → `:refresh_backgrounded`. `:refresh_failed` kept.
+- DSL: single `Textus.on(event, name, **opts) { ... }`. Sugar methods (`Textus.intake`, `Textus.reduce`, `Textus.check`, etc.) and the generic `Textus.hook(...)` form removed.
+
+### Renamed — CLI
+
+- Namespaced: `textus key mv`, `textus key normalize` (was `key migrate`), `textus rule list` (was `policy list`), `textus rule explain` (was `policy explain`), `textus refresh stale` (was `refresh-stale`).
+- Top-level mutator `textus mv` removed (use `textus key mv`).
+- Envelope-render flag `--format=json` → `--output=json`. Entry-level `format:` in the manifest is unchanged.
+- Legacy spellings emit a `CommandRenamed` envelope (`code: "command_renamed"`); legacy flags emit `FlagRenamed`.
+
+### Added
+
+- `textus migrate --to=textus/3`: idempotent one-shot migrator (manifest YAML rewrite, zone directory rename `inbox` → `intake`, frontmatter owner sweep across `.md`/`.json`/`.yaml`, audit-log marker, hook DSL scanner that reports old call sites).
+- `textus doctor` check `protocol_version`: refuses textus/2 stores.
+- `promotion.requires` predicates: `schema_valid`, `human_accept`. Enforced by `textus accept` for matching rules.
+
+### Internal
+
+- `Manifest::Policies` → `Manifest::Rules` (class + file + accessor + doctor check).
+- New errors: `Textus::BadManifest`, `Textus::CommandRenamed`, `Textus::FlagRenamed`.
+- Two new domain classes under `Textus::Domain::Policy::Predicates::` for promotion gating.
+- Migration toolkit under `Textus::Migration::V3::`.
+
+### Migration notes for 0.10.x users
+
+1. Update `Gemfile`: `gem "textus", "~> 0.11"`.
+2. `bundle update textus`.
+3. `cd` to each textus store and run `textus migrate --to=textus/3`.
+4. Review the hook-scanner findings printed at the end of the migrate output. For each call site, replace `Textus.X(:name) { ... }` with the canonical `Textus.on(:Y, :name) { ... }` per the event rename table above.
+5. Run `textus doctor` — should report `ok: true`.
+6. Commit the rewritten `.textus/` directory (manifest, audit marker, possibly renamed zone dir).
+
+### Fixed
+
+- **`Doctor::Check::IllegalKeys` now honors `index_filename:`.** Previously the doctor walked every file and directory under a nested entry and flagged any whose basename failed the `[a-z0-9][a-z0-9-]*` segment regex — including `SKILL.md` itself and unrelated siblings like `references/foo.md`. With this fix, when an entry declares `index_filename:`, only the parent-directory segments leading to each matching index file are validated; sibling files and unrelated subtrees are not enumerated and are not flagged. `manifest.enumerate` already filtered correctly via the new glob; this brings the doctor check into parity. Two new specs in `spec/doctor_spec.rb` cover (a) `SKILL.md` is not flagged, (b) sibling `references/` files are not flagged. The pre-existing illegal-parent-segment case (e.g. `Bad_Name/SKILL.md`) still reports `key.illegal`.
+
+## 0.10.5 — tech-debt cleanup + `index_filename:` + docs polish (2026-05-25)
+
+Patch release. One user-facing feature (`index_filename:` on nested manifest entries) plus internal refactors that remove 7 of 19 `rubocop:disable` suppressions. No protocol bump; existing manifests parse unchanged.
+
+### Added
+
+- **Per-entry `index_filename:` on nested manifest entries.** A nested entry MAY declare `index_filename: SKILL.md` (or any other bare basename) to surface that single file per directory as the row; the row's key segments come from the directory path, and siblings are not enumerated. Lets entries project spec-mandated filenames (e.g. agentskills.io's `SKILL.md`) whose uppercase casing would otherwise be rejected by the `[a-z0-9][a-z0-9-]*` key-segment grammar. `resolve(key)` returns the index-filename path for sub-directories. Validation: requires `nested: true`, basename only (no slashes), extension must match the entry's `format:`. New spec `spec/manifest_index_filename_spec.rb`. Documented in SPEC §4.
+
+### Internal
+
+- **`Store::Mover#call` refactor.** Replaces an 81-line method (suppressed `Metrics/AbcSize, Metrics/MethodLength`) with an 8-line orchestrator sequenced over four named private phases — `prepare_plan`, `ensure_uid!`, `perform_move`, `record_move` — coordinated through a `MovePlan` value object. The pre-read envelope is threaded separately so `MovePlan` describes only the planned operation.
+- **`Store::Staleness#call` split.** Replaces a 70-line dual-loop method (the most aggressive suppression in the gem — `AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity, BlockLength`) with a composer + two single-purpose checks (`GeneratorCheck`, `IntakeCheck`) and a private filter method on the composer. Each new unit fits default rubocop thresholds.
+- **`Store::Writer` payload + ctx grouping.** Collapses `write_envelope_to_disk`'s 8 keyword args to 5 by introducing `Store::Writer::Payload = Data.define(:meta, :body, :content)` and reusing `Application::Context` for `role` + `correlation_id`. Applies the same `ctx:` pattern to the sibling `delete_envelope_from_disk`. The class-wide `Metrics/ParameterLists` disable is narrowed to a method-level disable on the `put` back-compat shim (which mirrors the user-facing `Store#put` 7-kwarg signature and cannot be changed).
+- **Net suppression change:** 19 `rubocop:disable` lines → 17; 7 metric-cop suppressions removed; one `ParameterLists` disable narrowed in scope. Full suite unchanged.
+
+### Documentation
+
+- **SPEC.md §5.2.1 added.** Documents the `generator:` field — the externally-generated-derived-entry shape (build runner produces the file; textus tracks `sources:` for staleness via `_meta.generated.at`). The field was always parsed and tested but had no spec coverage. Clarifies that textus never executes `command:` — consistent with §2 "Not an executor."
+- **README.md trimmed.** Removed the duplicated "CLI verbs" and "Zones and roles" tables; readers are pointed at SPEC §5 / §9 and `docs/zones.md` for the canonical surfaces. README narrative kept.
+- **docs/conventions.md** now covers both derived-entry shapes (`projection:` for declarative compute inside textus; `generator:` for external build tools) and the current intake / freshness model (top-level `policies:` + `textus refresh-stale`). Replaces a stale section that described a pre-0.4 build-runner pattern.
+- **CONTRIBUTING.md** sources-of-truth pointer updated. Per-release implementation plans are kept locally by maintainers and no longer signposted in public docs.
 
 ## 0.10.4 — GitHub folder intake recipe + skill-bundle deferral ADR (2026-05-24)
 
@@ -42,7 +167,7 @@ Patch release. Two pieces of work: (1) docs describe current state only — ever
 
 ### Documentation
 
-- **`docs/plans/`** is now signposted in `CONTRIBUTING.md` as design history, not current documentation.
+- **`CONTRIBUTING.md`** now points readers at SPEC / ARCHITECTURE / `docs/` / CHANGELOG as the sources of truth. Per-release implementation plans are kept locally by maintainers and are no longer signposted in public docs.
 - **README, SPEC, ARCHITECTURE, docs/zones, docs/events, docs/conventions, examples/claude-plugin/README** — stripped `(0.8.2+)`, `(0.9.0+)`, `(0.9.2)`, `(v1.0)`, `(v1.1)`, `(v1.2)`, `(v0.3)` annotations from headings, parentheticals, and inline notes. Removed "Renamed in 0.9.2" / "Pre-0.9.2 stores" / "New in 0.9.0" / "Backward compatibility (v0.5)" callouts. Example code that used pre-0.9.2 zone names (`canon`, `intake`, `pending`, `derived`) now uses current names (`identity`, `inbox`, `review`, `output`).
 - **`docs/events.md`** — header count corrected to "15 events: 3 RPC and 12 pub-sub" (previously read "12 events", with refresh\_\* mentioned in subtext); stale Linear manifest example updated to use top-level `policies:` block.
 - **SPEC.md §10.2** — removed `legacy_intake_fields` from the builtin doctor-check list.

data/README.md

@@ -7,17 +7,27 @@
 
 A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus intro`) and know what to read, what to write, and what's off-limits.
 
-Reference implementation in Ruby. Wire format `textus/2`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
+Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
 
 ## Versioning
 
 Two versions, deliberately independent:
 
-- **Protocol wire string:** `textus/2`. Stable; breaking changes require `textus/3`.
-- **Gem version:** semver, currently `0.10.3`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Protocol wire string:** `textus/3`. Stable; breaking changes require `textus/4`.
+- **Gem version:** semver, currently `0.11.0`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
+### Upgrading from textus/2
+
+textus 0.12.0 does not include a built-in migrator. If you are upgrading from
+a textus/2 store (gem versions ≤ 0.10.x), first install textus 0.11.x and run:
+
+    textus migrate --to=textus/3
+
+Then upgrade to 0.12.0. Pre-0.11.0 audit-log rows with `role: ai|script|build`
+are tolerated verbatim by the reader — no rewrite step required.
+
 ## Install
 
 ```sh
@@ -49,10 +59,10 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   sentinels/          # publish bookkeeping
   zones/
     identity/         # human-only — identity, voice, decisions
-    working/          # human / ai / script — day-to-day catalog
-    inbox/            # script — declared external inputs (actions)
-    review/           # ai + human — proposals awaiting accept
-    output/           # build only — computed outputs
+    working/          # human / agent / runner — day-to-day catalog
+    intake/           # runner — declared external inputs (actions)
+    review/           # agent + human — proposals awaiting accept
+    output/           # builder only — computed outputs
 ```
 
 Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
@@ -65,92 +75,41 @@ textus list --zone=working
 echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put working.network.org.bob --as=human --stdin
 textus freshness --zone=output       # per-entry fresh/stale/never_refreshed/no_policy
-textus policy list                   # show every policy block
+textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
 ```
 
-(All verbs return JSON envelopes by default; pass `--format=json` explicitly if you prefer.)
+(All verbs return JSON envelopes by default; pass `--output=json` explicitly if you prefer.)
 
 For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
 ## What ships today
 
-- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `reducer`).
+- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `transform`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
-- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key migrate --dry-run|--write` rewrites existing stores with illegal segments deterministically.
+- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key normalize --dry-run|--write` rewrites existing stores with illegal segments deterministically.
 - **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
 - **`textus doctor`.** Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
 - **Actionable hints on every error.** `UnknownKey` carries ranked "did you mean" suggestions. `WriteForbidden` names the role that *would* be allowed. `BadFrontmatter` tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.
+- **Compute.** Derived entries declare `compute: { kind: projection, ... }` (declarative rows + template) or `compute: { kind: external, ... }` (build runner produces the file; textus tracks sources for staleness). Inside projection computes, `transform:` names the row-shaping hook.
 
 Symlink-mode publish was removed; publish is `FileUtils.cp` + sentinel. Sentinels for published files live under `.textus/sentinels/<target_rel>.textus-managed.json` so consumer directories stay clean. Legacy sibling sentinels auto-migrate on next publish.
 
-## CLI verbs
-
-All verbs accept `--format=json` and return the envelope defined in SPEC §8. Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`).
-
-**Read:**
-
-| Verb | Purpose |
-|---|---|
-| `intro` | Store orientation: zones, entries, hooks, write flows, CLI map |
-| `list [--prefix=K] [--zone=Z]` | Enumerate keys |
-| `where K` | Resolve a key to its filesystem path |
-| `get K` | Full envelope (frontmatter, body, uid, etag, format) |
-| `schema show K` | Schema bound to an entry |
-| `freshness [--prefix=K] [--zone=Z]` | Per-entry status (fresh / stale / never_refreshed / no_policy) against `policies:` |
-| `audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]` | Query `.textus/audit.log` |
-| `blame KEY` | Audit rows joined with git commit metadata |
-| `policy list` / `policy explain KEY` | Dump effective policies / per-slot winners for one key |
-| `deps K` / `rdeps K` | Forward / reverse projection dependencies |
-| `published` | List `publish_to:` targets and their backing keys |
-| `doctor --check=schema_violations` | Validate every entry against its schema |
-| `hook list [--event=E]` | Registered hooks grouped by event (intake, reduce, check, put, deleted, refreshed, built, accepted, published, mv, reject, loaded, refresh_began, refresh_failed, refresh_detached) |
-
-**Write:**
-
-| Verb | Role |
-|---|---|
-| `put K --stdin --as=R [--action=NAME]` | per zone |
-| `hook run NAME [--key=val] [--as=R]` | per zone written (invoke a registered intake hook) |
-| `delete K --if-etag=E --as=R` | per zone |
-| `refresh K --as=script` | per zone (typically `script`) |
-| `key mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
-| `build [--prefix=K] [--dry-run]` | `build` |
-| `accept K --as=human` | `human` only |
-| `reject K --as=human` | `human` only (discards a pending proposal; fires `:reject`) |
-
-**Health & maintenance:**
-
-| Verb | Purpose |
-|---|---|
-| `doctor` | Health checks (manifest, schemas, templates, hooks, illegal keys, sentinels, audit log, policy ambiguity, handler allowlist, legacy intake fields); `ok: true` when clean |
-| `key migrate [--dry-run]` | Rename files whose basenames violate the strict key grammar |
-
-**Scaffolding (human-only):**
-
-| Verb | Purpose |
-|---|---|
-| `init` | Scaffold a fresh `.textus/` |
-| `schema init NAME` | Stub a schema |
-| `schema diff NAME` | Compare a schema against entries that claim it |
-| `schema migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
-
-## Zones and roles
-
-| Zone | `writable_by` | Purpose |
-|---|---|---|
-| `identity` | `[human]` | Identity, voice, decisions — slow-changing |
-| `working` | `[human, ai, script]` | Active project state |
-| `inbox` | `[script]` | Declared external inputs (actions) |
-| `review` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
-| `output` | `[build]` | Computed outputs from `textus build` |
-
-Mismatches return `write_forbidden` with a hint naming the role that *would* be allowed. Every write records the resolved role in `.textus/audit.log`.
+## CLI and zones
+
+All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`). Recognized roles: `human`, `agent`, `runner`, `builder`.
+
+- Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
+- Zone semantics and the role/`write_policy` mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
+
+`textus intro` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
 ## Compute and publish
 
-Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`, optional `reducer`) and either a template under `.textus/templates/` (markdown/text) or a templateless path that lets a reducer shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.
+Derived entries declare `compute: { kind: projection, select: ..., pluck: ..., sort_by: ..., limit: ..., transform: name }` and either a template under `.textus/templates/` (markdown/text) or a templateless path that lets a transform hook shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.
+
+For externally-generated entries, declare `compute: { kind: external, sources: [...] }` — textus tracks the declared sources for staleness; the build runner produces the file.
 
 `publish_to: [path]` byte-copies a single derived file to one target. `publish_each: "template/{basename}.md"` on a nested entry byte-copies every leaf to its templated target — substitutes `{leaf}`, `{basename}`, `{key}`, `{ext}`. Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
 
@@ -158,15 +117,15 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectories are fine; files load alphabetically by full path). Events:
 
-- `:intake` — bring bytes in from elsewhere (returns `{_meta:, body:}`)
-- `:reduce` — transform rows during projection (returns rows)
-- `:check` — custom doctor check (returns issues)
-- `:put`, `:deleted`, `:refreshed`, `:built`, `:accepted`, `:published`, `:mv`, `:reject`, `:loaded` — react to lifecycle events
-- `:refresh_began`, `:refresh_failed`, `:refresh_detached` — background-refresh lifecycle
+- `:resolve_intake` — bring bytes in from elsewhere (returns `{_meta:, body:}`)
+- `:transform_rows` — transform rows during projection (returns rows)
+- `:validate` — custom doctor check (returns issues)
+- `:entry_put`, `:entry_deleted`, `:entry_refreshed`, `:build_completed`, `:proposal_accepted`, `:file_published`, `:entry_renamed`, `:proposal_rejected`, `:store_loaded` — react to lifecycle events
+- `:refresh_started`, `:refresh_failed`, `:refresh_backgrounded` — background-refresh lifecycle
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
-Textus.intake(:local_file) do |config:, args:, **|
+Textus.on(:resolve_intake, :local_file) do |config:, args:, **|
   path = config["path"] or raise "local-file requires intake.config.path"
   {
     _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
@@ -176,7 +135,7 @@ end
 ```
 
 ```ruby
-Textus.reduce(:rank_by_recency) do |rows:, **|
+Textus.on(:transform_rows, :rank_by_recency) do |rows:, **|
   rows.sort_by { |r| r["updated_at"].to_s }.reverse
 end
 ```
@@ -184,18 +143,18 @@ end
 To keep a batch of stale intake entries current in one shot:
 
 ```sh
-textus refresh-stale --prefix=working --zone=inbox --as=script
-# or just refresh everything stale in the inbox zone:
-textus refresh-stale --zone=inbox --as=script
+textus refresh stale --prefix=working --zone=intake --as=runner
+# or just refresh everything stale in the intake zone:
+textus refresh stale --zone=intake --as=runner
 ```
 
-The primitive `Textus.hook(event, name, **opts) { ... }` is also supported. See SPEC.md §5.10 for the full contract.
+See SPEC.md §5.10 for the full hook contract.
 
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests