textus 0.8.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91be0acd415a4b41d96e896015dfd19e58fc7867d007332456499ec5ceb8a6aa
-  data.tar.gz: 576d361ebba900b33b2f612b1a0a51d0373cb4a5e1fbd503e43c2bb248ca9306
+  metadata.gz: ca479a6c2f4282b97184aee5c65bc94c3607d18ae0a608756737c70ef53407b5
+  data.tar.gz: 2294eaa31b51276d48f1a7bc850464c3351a2c93b5d273100192fec4d89561d9
 SHA512:
-  metadata.gz: c551c60809be1eefc0d964092adc62a8555cb6f0df3585e775fd2fda1549f1e7d811fb2bfeec992dd3ce872dccb16fd9300a66314d5e51e8f24a98b57f29da5b
-  data.tar.gz: c96ec13692d6366a916b125266afb70aabcca439594db4e8fd1b434f1db1a88e216938cbf64bc69e64bcfef241ca7314664398c656f1d7333a7480a7d02852f9
+  metadata.gz: 6a6c5a434cf90e8e417faed9034e6ea653f1f94b3e373ea00b47045297e73b9e0f58d4619a84f497b45cb3078930da9b4327d7e179540369af7bf7297db2bd05
+  data.tar.gz: 4cbcd09254c93d94d1fd06c766ceefb5125990851422db6f6b3af4ad716b7754d71e432ebc88161d938aa5177ec26d6e1f43b7577daa80210e7a493e0266f6ea

data/CHANGELOG.md

@@ -8,6 +8,251 @@ 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.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
+- `textus intro` JSON: the `"extensions"` key is renamed to `"hooks"`. Consumers
+  reading `env["extensions"]` must switch to `env["hooks"]`. Wire protocol
+  remains `textus/2`; envelope shape on read/write is unchanged.
+
+### Internal Ruby renames
+- `Textus::Store#load_extensions` → `Textus::Store#load_hooks`.
+- `Textus::Intro.extensions_for` → `Textus::Intro.hooks_for`.
+- Error string `"failed loading extension <file>"` → `"failed loading hook <file>"`.
+
+### Fixed
+- `textus doctor` `:check`-hook failure hint pointed to `.textus/extensions/`,
+  which has never existed in 0.6+. Now correctly points to `.textus/hooks/`.
+
+### Docs
+- SPEC.md §5.10: "single extension verb" → "single hook verb".
+- Scaffolded `.textus/hooks/README.md` no longer mixes "hook" and "extension"
+  terminology.
+
 ## 0.8.0 — Folder restructure & Zeitwerk autoload (2026-05-21)
 
 ### Breaking — internal Ruby renames

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.
 
@@ -45,18 +45,20 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   audit.log           # append-only NDJSON, every write
   schemas/            # YAML field shapes per entry family
   templates/          # mustache templates for derived entries
-  extensions/         # one .rb per action / reducer / hook / doctor_check
+  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.)
@@ -77,8 +81,8 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 - **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.
-- **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded extensions, 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 extensions, 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.
+- **`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.
 
 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.
@@ -91,34 +95,38 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 
 | Verb | Purpose |
 |---|---|
-| `intro` | Store orientation: zones, entries, extensions, write flows, CLI map |
+| `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 |
-| `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.