textus 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4b96d4cff83e901df4b2871b57f9c86d071b11126fd42e8fc5563abf45ce810
-  data.tar.gz: 6afa20a10f7ddee98b5b4adbf6eb87218725b5eb1c3f7b181b8bcb462d4fff74
+  metadata.gz: 198dc9a4561b79bf4da22a2f890caa5da2764b8d82b1665b506d6c4c8c0e3fe3
+  data.tar.gz: dc5333c3605b7b05174f4b290fcb63260aad7ea089da900f0b3325cf3823d83c
 SHA512:
-  metadata.gz: 83825a241b91ac10c2024ebdf04ec0f1bb753b8deeded27894fbbbff84f3f654ad6cc4c0faa2bbfcf940b989bc0393d832ae90af837039814fe51e5f7e4c4515
-  data.tar.gz: 57079b174111a5e89637140d53ca83f5c9b0c5f777c270be9833174c3dd11c7f4d8b8039ef30c69c6f85e1dfb9d78c89dab3eb99cd517b32e1cf7af2ce7ded7a
+  metadata.gz: f9e08a7a3fc46732dcd9458114765a54e3f8d2aca08b3ead6b70ecfc2782c0e9fec5eec38fc933cef9582c5943db52973c8bb06e544c02afec468dc50bbc8797
+  data.tar.gz: 9cb891ae4ce1d7583af7546e16e1f1a23d8d88af105430d31c2eb3fd4e25af6df2a60c5677c810a3d11f01582d7500a18d681b8996e9f2f5da1948e32ec2a39f

data/CHANGELOG.md

@@ -8,6 +8,335 @@ 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.
 
+## 0.10.0 — Shim removal, signal-based zone detection, Builder extraction (2026-05-22)
+
+### Breaking — Ruby API
+
+- `Textus::Publisher` constant removed. Use `Textus::Infra::Publisher`.
+- `Textus::Store::View` class removed. Use `Textus::Application::Context`
+  (constructed via `Composition.context(store, role:)`).
+- `Textus::Builder` class removed as a public entry point. Build logic lives
+  in `Textus::Application::Writes::Build`. External callers should use
+  `Textus::Composition.writes_build(ctx).call` instead of
+  `Textus::Builder.new(store).build`. The `Textus::Builder` namespace is
+  retained internally only for nested helpers (`Builder::Pipeline`,
+  `Builder::Renderer::*`).
+- `Application::Context` no longer exposes `put` / `delete` / `get` / `list`
+  / `where` shim methods. Hook callers that receive a Context via the
+  `store:` hook keyword must call `ctx.store.put(...)` etc., and explicitly
+  pass `as: ctx.role` for write operations.
+- Intake handler return values must use `_meta:` for frontmatter. The
+  previous `frontmatter:` legacy key is no longer accepted.
+
+### Fixed
+
+- `textus reject` and `textus refresh-stale` now work correctly for stores
+  that use the post-0.9.2 default zone names (`review`, `output`).
+  Zone-kind detection is now signal-based (driven by `writable_by:`
+  membership), not name-based. Stores using the pre-0.9.2 names (`pending`,
+  `derived`) continue to work.
+- Event payloads' `store:` keyword now carries a Context whose
+  `correlation_id` matches the event payload's top-level `correlation_id`
+  key. Previously the `store:` Context received a fresh, unrelated
+  `correlation_id`.
+
+### Added
+
+- `Textus::Manifest::Entry#in_generator_zone?` and `#in_proposal_zone?`
+  predicates. Internal `derived?` retained as an alias of
+  `in_generator_zone?`.
+- `:built` and `:published` events now carry `correlation_id` in the
+  payload, matching the existing pattern on `:put` / `:deleted` /
+  `:accepted`.
+
+### Removed
+
+- Legacy zone-purpose annotations for `canon` / `intake` / `pending` /
+  `derived` removed from `Textus::Intro::ZONE_PURPOSES`. Custom-named zones
+  continue to get no purpose annotation (existing behavior). Stores still
+  using the pre-rename default names will simply not get purpose
+  annotations on those zones in `textus intro` output.
+- Dead code: `Textus::Manifest#validate_keys!` removed (had no callers).
+
+### Internal
+
+- Builder logic fully extracted into `Application::Writes::Build`.
+- CLI verbs now share `context_for(store)` / `resolved_role(store)`
+  helpers on `CLI::Verb`.
+- Internal helpers in `Manifest`, `Doctor`, and `Manifest::Entry` are
+  properly marked private.
+
+### Unchanged
+
+- Wire protocol stays `textus/2`. Envelope shape unchanged.
+- CLI verbs, their flags, and their JSON output shape — unchanged.
+- Manifest YAML schema — unchanged.
+- Event names — unchanged (payload gains `correlation_id` on `:built` /
+  `:published`, but no existing key is removed or renamed).
+- Hook DSL — unchanged in shape. The `store:` keyword still passes an
+  object that responds to `.get`, `.list`, `.where`. The Context's
+  role-aware `with_role` is the recommended construction site for hook
+  contexts now.
+
+### Migration recipe
+
+```ruby
+# Hook handlers — before 0.10.0
+Textus.hook(:intake, :my_hook) do |store:, config:, args:|
+  store.put("inbox.foo", meta: { ... }, body: "...")  # used Context shim
+end
+
+# Hook handlers — 0.10.0+
+Textus.hook(:intake, :my_hook) do |store:, config:, args:|
+  ctx = store  # rename for clarity if desired
+  ctx.store.put("inbox.foo", meta: { ... }, body: "...", as: ctx.role)
+end
+
+# Intake handler returns — before 0.10.0
+{ frontmatter: { ... }, body: "..." }  # legacy key
+
+# Intake handler returns — 0.10.0+
+{ _meta: { ... }, body: "..." }  # _meta is the canonical key
+```
+
+If you imported the removed constants directly:
+
+```ruby
+# Before
+Textus::Publisher        # removed
+Textus::Store::View      # removed
+Textus::Builder.new(store).build(key, ...)  # removed
+
+# After
+Textus::Infra::Publisher
+Textus::Application::Context  # via Composition.context(store, role:)
+Textus::Composition.writes_build(ctx).call(key, ...)
+```
+
+## 0.9.2 — Policies, audit verbs, zone rename (2026-05-22)
+
+### Breaking — manifest YAML
+
+- **Top-level `policies:` block added.** Replaces entry-level `intake.ttl` and
+  `intake.on_stale`. Hand-edit existing manifests (see migration recipe below);
+  no migrator ships with 0.9.2 because the gem is pre-1.0 with no known
+  outside upgraders.
+- **Default zone names renamed.** `canon → identity`, `intake → inbox`,
+  `pending → review`, `derived → output`. `working` unchanged. Hand-edit
+  the manifest + `mv` the zone directories (see recipe below).
+- Custom-named zones are unaffected.
+
+### Breaking — CLI
+
+- `textus stale` removed. Use `textus freshness`.
+
+### Added — verbs
+
+- `textus freshness [--prefix=K] [--zone=Z]` — per-entry status (ttl, age,
+  next_due_at, status: fresh|stale|never_refreshed|no_policy).
+- `textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X]
+  [--correlation-id=ID] [--limit=N]` — query `.textus/audit.log`.
+- `textus blame KEY` — audit rows joined with git commit metadata.
+- `textus policy list` — dump effective policies.
+- `textus policy explain KEY` — show per-slot winners and matching blocks.
+
+### Added — domain
+
+- `Textus::Domain::Policy::Refresh` — ttl + on_stale value, exports to
+  `Domain::Freshness::Policy`. `on_stale` vocab is `warn | sync | timed_sync`
+  (unchanged from 0.9.0).
+- `Textus::Domain::Policy::Promote` — promote_requires predicate.
+- `Textus::Domain::Policy::HandlerAllowlist` — allowed intake handlers.
+- `Textus::Domain::Policy::Matcher` — glob match + specificity ranking.
+- `Textus::Manifest::Policies` — collection over policy blocks with
+  most-specific-wins resolution.
+
+### Added — doctor checks
+
+- `policy_ambiguity` — two blocks of the same specificity matching one key.
+- `handler_allowlist` — intake handler outside its policy's allowlist.
+- `legacy_intake_fields` — `intake.ttl`/`intake.on_stale` still present in
+  raw YAML.
+
+### Unchanged
+
+- Wire protocol stays `textus/2`. Envelope shape unchanged.
+- Hook DSL, event names, role gate semantics, schema validation unchanged.
+- `on_stale:` vocabulary (`warn | sync | timed_sync`) and its semantics
+  (return-stale / block-and-refresh / try-with-deadline) are unchanged —
+  policies merely change where the value lives.
+- `:publish` hook (shipped 0.8.2) remains the extension point for custom
+  publish targets.
+
+### Migration recipe (hand-edit, no migrator ships)
+
+```sh
+# In your existing .textus/manifest.yaml:
+#   1. Rename zones[].name fields: canon→identity, intake→inbox,
+#      pending→review, derived→output.
+#   2. Rewrite every entries[].zone and entries[].path prefix accordingly.
+#   3. Move each entries[].intake.ttl / on_stale / sync_budget_ms into
+#      a new top-level policies:[] block keyed by the entry's exact key:
+#
+#        policies:
+#          - match: "inbox.news.hn"
+#            refresh: { ttl: 6h, on_stale: sync }
+
+# On disk:
+mv .textus/zones/canon   .textus/zones/identity
+mv .textus/zones/intake  .textus/zones/inbox
+mv .textus/zones/pending .textus/zones/review
+mv .textus/zones/derived .textus/zones/output
+
+# Verify:
+textus doctor
+```
+
+Find-and-replace tips for ad-hoc references in your own files:
+
+```sh
+# README snippets, CI yaml, shell scripts
+sed -i.bak \
+  -e 's/\bcanon\b/identity/g' \
+  -e 's/\bintake\b/inbox/g' \
+  -e 's/\bpending\b/review/g' \
+  -e 's/\bderived\b/output/g' \
+  -e 's/textus stale/textus freshness/g' \
+  README.md CONTRIBUTING.md
+```
+
+## 0.9.1 — write-path layering + request Context (2026-05-22)
+
+### Changed — internal architecture (no plugin-visible impact)
+
+- Promoted `Store::View` to `Application::Context`. The new Context carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. It answers `can_read?(zone)` / `can_write?(zone)` via the new `Domain::Permission` value. `Store::View` remains as a deprecated alias for one release; slated for removal in 0.10.0.
+- Extracted `Domain::Permission` from `Manifest#zone_writers`. Pure predicate value — `allows_read?(role)` / `allows_write?(role)`. Manifest gains `#permission_for(zone_name)` returning a `Permission`.
+- Extracted write-path use cases under `Application::Writes::*`:
+  - `Writes::Put` (was `Store::Writer#put` orchestration)
+  - `Writes::Delete` (was `Store::Writer#delete` orchestration)
+  - `Writes::Build` (was `Builder#build` orchestration)
+  - `Writes::Accept` (was `Proposal.accept`)
+  - `Writes::Publish` (was direct calls to `Publisher.publish`)
+- `Store::Writer#put` and `#delete` reduced to pure I/O (`#write_envelope_to_disk`, `#delete_envelope_from_disk`). The original methods remain as backward-compat shims that delegate to the use cases.
+- `Builder`, `Proposal`, `Publisher` become thin shims. `Publisher` also moved to `Textus::Infra::Publisher` (its prior location remains as an alias).
+- `Store#get`, `#put`, `#delete` reduced to 2-line shims through the new `Composition` module. `Store` itself no longer imports from `Application::*`.
+- New `Composition` factory module wires Contexts and use cases. CLI verbs construct via `Composition.context(store, role:)` then `Composition.<use_case>(ctx).call(...)`.
+- `Refresh::Worker` and `Refresh::Orchestrator` migrated to take `Context` instead of `store:` + `as:`.
+
+### Added
+
+- Every event payload now includes `correlation_id` — a UUID generated once per Context. Hook authors can use this to correlate events within a single request (e.g., a `:refreshed` event and a downstream `:built` event share an ID).
+
+### Deprecated
+
+- `Textus::Store::View` — use `Textus::Application::Context`. Removed in 0.10.0.
+- `Textus::Publisher` — use `Textus::Infra::Publisher` or `Textus::Application::Writes::Publish`. Removed in 0.10.0.
+
+### Unchanged
+
+- Plugin DSL, manifest YAML schema, CLI verb JSON output, envelope fields, event names, wire protocol — all identical to 0.9.0.
+- No migration needed for plugin authors.
+
+## 0.9.0 — intake, event standardization, read-time freshness, layered architecture (2026-05-22)
+
+### Breaking — manifest schema
+- The `source:` block is renamed to `intake:`. Its inner `fetch:` is renamed to `handler:`. Other inner fields (`config:`, `ttl:`) keep their names.
+- Loading a manifest that still uses `source:` raises a clear migration error.
+
+### Breaking — event names (pub-sub bus)
+- `:fetch` → `:intake` (RPC)
+- `:delete` → `:deleted`
+- `:refresh` → `:refreshed`
+- `:build` → `:built`
+- `:publish` → `:published`
+- `:accept` → `:accepted`
+- `:put`, `:mv`, `:reject`, `:loaded` are unchanged (already past tense).
+
+### Breaking — DSL sugar
+- `Textus.fetch(:name)` → `Textus.intake(:name)`
+- `Textus.refresh`, `.build`, `.publish`, `.delete`, `.accept` rename to past-tense equivalents.
+- The primitive `Textus.hook(event, name)` is unchanged — event symbols update per above.
+
+### Added — read-time freshness
+- Every entry's manifest may declare `intake.on_stale: warn | sync | timed_sync` (default `warn`).
+  - `warn` — return stale envelope with `stale: true`, `stale_reason: "…"`; no refresh.
+  - `sync` — refresh inline, return fresh envelope.
+  - `timed_sync` — attempt sync up to `sync_budget_ms` (default 500ms); if exceeded, fork+detach a child to complete the refresh and return stale + `refreshing: true` to the caller. Unix only; on Windows falls back to `warn`.
+- New envelope fields on `textus get`: `stale`, `stale_reason`, `refreshing`.
+
+### Added — refresh lifecycle events
+- `:refresh_began { key, mode }` fires when refresh begins.
+- `:refresh_failed { key, error_class, error_message }` fires on intake errors.
+- `:refresh_detached { key, started_at, budget_ms }` fires when timed_sync gives up waiting and forks.
+
+### Added — actuator
+- `textus refresh-stale [--prefix=KEY] [--zone=Z]` — refreshes every entry whose TTL has expired. Returns `{ refreshed, failed, skipped }` JSON. Exits non-zero on any failure. Intended for cron / CI.
+
+### Added — doctor check
+- `textus doctor` now verifies every manifest `intake.handler:` resolves to a registered `Textus.intake(:name)`, reports missing handlers as errors, and orphan registrations as warnings.
+
+### Changed — internal architecture (no plugin-visible impact)
+- Internals reorganized into four layers: `domain/` (pure values), `application/` (use cases), `infra/` (adapters), and `cli/` (interface). Plugin DSL, manifest schema, CLI verbs, and envelope shape are unchanged.
+- `Freshness` is split into `Domain::Freshness::Evaluator` (pure) + `Domain::Freshness::Policy#decide` (data-driven) + `Application::Refresh::Orchestrator` (effects).
+- `Refresh.call` is now a one-line shim over `Application::Refresh::Worker.run`. `Refresh::Lock` and `Refresh::Detached` moved to `Infra::Refresh`.
+- `Store#get` now routes through `Application::Reads::Get`. `Store::Reader#get` was reduced to pure I/O (`#read_raw_envelope`) — third-party code calling it directly should switch to `Store#get` for freshness annotations.
+
+### Unchanged
+- Wire protocol stays `textus/2`.
+- `:reduce`, `:check`, `:put` unchanged.
+- The recursive `hooks/**/*.rb` loader from 0.8.2.
+
+### Migration
+1. In `.textus/manifest.yaml`, replace every `source:` with `intake:` and every `fetch:` inside it with `handler:`. No other inner-field renames needed.
+2. In hook files, replace `Textus.fetch(:name)` with `Textus.intake(:name)` and the other five pub-sub sugar names with their past-tense equivalents.
+3. (Optional) Add `on_stale: timed_sync` to entries where you want self-healing reads.
+4. Wire `textus refresh-stale` into cron / GH Actions for scheduled freshness.
+5. If you subscribed to the `:refresh_started` event during 0.9.0 betas, rename your handler to `Textus.refresh_began(:name)`.
+6. If you called `Textus::Refresh::Lock` or `Textus::Refresh::Detached` directly (you probably did not), update to `Textus::Infra::Refresh::Lock` / `Textus::Infra::Refresh::Detached`.
+
+## 0.8.3 — :mv, :reject, :loaded events (2026-05-22)
+
+### Added
+- New `:mv` event — fires after a successful `store.mv`. Payload:
+  `{ key:, from_key:, to_key:, envelope: }` where `key:` equals `to_key:`
+  so `keys:` glob filters route against the entry's post-move home.
+  `:put` and `:delete` remain suppressed for renames; `:mv` is the sole signal.
+- New `:reject` event + `store.reject(pending_key, as: "human")` +
+  `textus reject KEY --as=human` CLI verb. Counterpart to `:accept` —
+  explicitly discards a proposal. Fires `:delete` then `:reject`.
+- New `:loaded` event — fires exactly once at the tail of `Store#initialize`,
+  after all hooks are registered and reader/writer are built. Use for cache
+  warmups and one-shot setup. Payload: `store:` only.
+
+## 0.8.2 — Hook DSL sugar + :publish event (2026-05-22)
+
+### Added
+- Per-event hook sugar: `Textus.fetch`, `.reduce`, `.check`, `.put`,
+  `.delete`, `.refresh`, `.build`, `.accept`, `.publish`. Each takes
+  `(name, **opts, &blk)` and delegates to the existing registry. Block
+  signatures are per-event (use `**` to absorb unused kwargs).
+- New `:publish` pub-sub event. Fires once per file written to a repo
+  path (both for the fixed-list `publish_to:` case and the `publish_each:`
+  per-leaf case). Payload: `{ key:, envelope:, source:, target: }`.
+  Listeners can react per-file — e.g. `git add` each published file,
+  notify on writes, compute checksums.
+- `.textus/hooks/**/*.rb` — hook files in subdirectories are now loaded.
+  Subdirectory names are organizational; the registered event and name
+  come from the DSL call, not the file path. Files load in alphabetical
+  order by full path.
+
+### Unchanged
+- `Textus.hook(:event, :name, &blk)` primitive — still works, still the
+  authoritative entry point.
+- `:build` event semantics — still fires once per derived entry.
+- Registry shape, dispatcher behavior, audit log, wire protocol
+  (`textus/2`), envelope shape.
+
+### Example migrations
+The bundled `examples/claude-plugin` was migrated to the new DSL
+(snake_case names, sugar methods). No behavioral change; serves as the
+canonical example.
+
 ## 0.8.1 — Terminology cleanup (2026-05-21)
 
 ### Breaking — intro output

data/README.md

@@ -14,7 +14,7 @@ Reference implementation in Ruby. Wire format `textus/2`. SPEC: [`SPEC.md`](SPEC
 Two versions, deliberately independent:
 
 - **Protocol wire string:** `textus/2`. Stable; breaking changes require `textus/3`.
-- **Gem version:** semver, currently `0.8.0`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Gem version:** semver, currently `0.9.2`. 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.
 
@@ -48,15 +48,17 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   hooks/              # one .rb per hook
   sentinels/          # publish bookkeeping
   zones/
-    canon/            # human-only — identity, voice, decisions
+    identity/         # human-only — identity, voice, decisions
     working/          # human / ai / script — day-to-day catalog
-    intake/           # script — declared external inputs (actions)
-    pending/          # ai + human — proposals awaiting accept
-    derived/          # build only — computed outputs
+    inbox/            # script — declared external inputs (actions)
+    review/           # ai + human — proposals awaiting accept
+    output/           # build 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`.
 
+> **Renamed in 0.9.2.** Pre-0.9.2 defaults were `canon`, `intake`, `pending`, `derived`. `working` is unchanged. Upgrading a 0.9.1 store is a hand-edit (see CHANGELOG migration recipe).
+
 Read and write:
 
 ```sh
@@ -64,7 +66,9 @@ textus get working.network.org.jane
 textus list --zone=working
 echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put working.network.org.bob --as=human --stdin
-textus stale --zone=derived
+textus freshness --zone=output       # per-entry fresh/stale/never_refreshed/no_policy
+textus policy list                   # show every policy block
+textus audit --limit=20              # query the audit log
 ```
 
 (All verbs return JSON envelopes by default; pass `--format=json` explicitly if you prefer.)
@@ -96,29 +100,33 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | `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 |
-| `stale [--prefix=K] [--zone=Z]` | List stale derived/intake entries |
+| `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 (fetch, reduce, check, put, delete, refresh, build, accept) |
+| `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 fetch hook) |
+| `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` | 8 health checks; `ok: true` when clean |
+| `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):**
@@ -134,11 +142,11 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 
 | Zone | `writable_by` | Purpose |
 |---|---|---|
-| `canon` | `[human]` | Identity, voice, decisions — slow-changing |
+| `identity` | `[human]` | Identity, voice, decisions — slow-changing |
 | `working` | `[human, ai, script]` | Active project state |
-| `intake` | `[script]` | Declared external inputs (actions) |
-| `pending` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
-| `derived` | `[build]` | Computed outputs from `textus build` |
+| `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`.
 
@@ -150,20 +158,40 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 ## Extension points
 
-textus exposes one DSL verb:
+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 (0.9.0+)
 
 ```ruby
-Textus.hook(event, name, **opts) { |args| ... }
+# Inside .textus/hooks/local_file.rb
+Textus.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 },
+    body: File.read(File.expand_path(path)),
+  }
+end
 ```
 
-Drop `.rb` files into `.textus/hooks/`. Events:
+```ruby
+Textus.reduce(:rank_by_recency) do |rows:, **|
+  rows.sort_by { |r| r["updated_at"].to_s }.reverse
+end
+```
 
-- `:fetch` — bring bytes in from elsewhere (returns `{frontmatter:, body:}`)
-- `:reduce` — transform rows during projection (returns rows)
-- `:check` — custom doctor check (returns issues)
-- `:put`, `:delete`, `:refresh`, `:build`, `:accept` — react to lifecycle events
+To keep a batch of stale intake entries current in one shot:
+
+```sh
+textus refresh-stale --prefix=working --zone=intake --as=script
+# or just refresh everything stale in the intake zone:
+textus refresh-stale --zone=intake --as=script
+```
 
-See SPEC.md §5.10 for the full contract.
+The primitive `Textus.hook(event, name, **opts) { ... }` is also supported. See SPEC.md §5.10 for the full 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.