textus 0.49.0 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a370d0ed895357e5a2e70d5f9b41542b0a4e5036472aa6f728f7a0bc459838
-  data.tar.gz: 87bf64e383226fad74ca8534fca9f8b8de707f1e01bc910c05ad1266e5de032a
+  metadata.gz: 5832639952f2e74862490a982a1bed11beb0d8b46febb18d3db60ab03a7c533e
+  data.tar.gz: e959c0f82d1b7b2b50161f1089d3851cdf2f0452147efd80563f8c5a60299d29
 SHA512:
-  metadata.gz: d3f2279c8660c754b64defe04aeac05e198095ef056b7a4aee534d3bd290baac7bf13d206999872a82c6bc61f723771f852bbfde2594fbaa17f80a19082df877
-  data.tar.gz: e11ce9e704b3ea33ef94012d8425624dd3391152869d1ecb6b00e5422042a50d4c3c75612227ddd61f9ed8c10720e6f254c818e1492056a2ca3d00751500554b
+  metadata.gz: cdddc5128eddb2790a4a449bd53a981f18835f85fe19026a036bb95c17d9ac71bd430112e911f8c014a31cfec0a11e40874eff4fc5597353a1ed1a0844138d4b
+  data.tar.gz: 454407cf83ac596d39a78bd31dc4233289153e98a82dce46fdc34ec77dfa281a3637e92a7b00f5a83149d945c6a4a6bc1be59fdafe606344d530da04c13130c1

data/CHANGELOG.md

@@ -9,6 +9,51 @@ 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.51.0 — 2026-06-08 — The reconcile era: one engine for produce + sweep, `source`/`retention`, produced reference docs (ADR 0087, 0090–0095, 0097)
+
+`build` folds into `reconcile`, materialization becomes system-pushed, the producer kinds and machine zones collapse onto one `source` + `retention` grammar, and the machine-derivable reference docs graduate to produced artifacts.
+
+### Changed (breaking)
+
+- **`build` is removed; `tend` is now `reconcile`** (ADR 0087). One verb runs the full two-phase **produce → destructive-sweep** under a shared lock, and every canon write reactively rebuilds its dependent produced entries (`source.on_write: sync | async`). **Migration:** drop all `build` calls (CLI + MCP); rename scripted/cron `tend` to `reconcile` — the verb, the MCP tool id, and the audit-log verb string.
+- **Capabilities collapse to four — `author`, `keep`, `propose`, `reconcile`** (ADR 0090). The `fetch` and `build` capabilities fold into `reconcile`; `automation` defaults to `[reconcile]`. **Migration:** a role with `can: [fetch]` / `can: [build]` (or the interim `ingest`) becomes `can: [reconcile]`; the old spellings are rejected at load with a hint.
+- **One `machine` zone-kind and one `produced` entry-kind** (ADR 0091, 0095). Zone-kinds become `canon | workspace | machine | queue` — the former `quarantine` + `derived` zone-kinds fold into one `machine` kind (the kind ⟺ capability mapping is a bijection again; at most one `machine` zone). Entry-kinds become `leaf | nested | produced` — the former `derived` + `intake` entry-kinds fold into one `produced` kind, with the produce-method (intake / derived / external) read off `source.from`. **Migration:** `kind: quarantine` / `kind: derived` on a zone → `kind: machine`; `kind: derived` / `kind: intake` on an entry → `kind: produced`. Both are rejected at load with a fold hint; no shim.
+- **`source:` + `retention:` replace `upkeep` / `lifecycle` / `materialize` / `intake` / `compute` / `template`** (ADR 0093). The old slots conflated *production* (how an entry's bytes are made) with *retention* (when an aged entry is retired). They split into an entry-level **`source: { from: project | handler | command }`** — one "acquire data from upstream" concept, where `from` must agree with `kind:` — and a glob-matched **`retention: { ttl, action: drop | archive }`** rule; both run through one produce engine. This is strictly more expressive (re-pull hourly *and* archive at 90 days is now sayable). The `lifecycle: { on_expire: warn }` form is removed (`warn` was dead since 0.50's pure-read `get`). **Migration:** rewrite `upkeep:` / `lifecycle:` / `materialize:` (and the old `intake:` / `compute:` / `template:` blocks) into `source:` + `retention:`. Old manifests fail at load with mechanical fold hints; no shim.
+- **A `source` produces *data*; `publish:` is a list of targets** (ADR 0094). A produced entry's stored form is data (e.g. `.json`); rendering moves entirely to the publish path. **`publish:` is now a list** — each element a `{ to:, template?:, inject_boot?: }` file target (copies the data verbatim, or renders it through that target's own template) or a `{ tree: }` subtree mirror — so one dataset can render to differently-shaped targets (`CLAUDE.md` vs `AGENTS.md`) without bespoke handler code. Published artifacts are clean content; textus's `_meta` provenance stays in the stored entry. **Migration:** the *map* `publish: { to: [...] }` / `publish: { tree: }` forms (and the older `publish_to:` / `publish_tree:`) are rejected at load — `publish:` is a list.
+- **Hook events renamed** (ADR 0094). RPC `:resolve_intake` → `:resolve_handler`; pub-sub `:entry_put` → `:entry_written`, `:build_completed` → `:entry_produced` (plus `:entry_published` and `produce_failed`). **Migration:** update hook subscriptions to the new names; old names fail at registration.
+
+### Added
+
+- **Reference docs are produced, not hand-authored** (ADR 0097, 0098). `docs/reference/verbs.md` and `docs/reference/schema.md` (projected from the live verb/schema registry) and the new `docs/reference/adr-log.md` (projected from the ADR files) are `kind: produced` entries published out, with a CI gate that fails when `reconcile` is not a no-op. **Do not hand-edit them** — edit the upstream source (the verb/schema code, or an ADR) and run `reconcile`; `doctor` flags a stale hand-edit as `generator_drift`.
+- **The root `README.md`, `CONTRIBUTING.md`, and `SECURITY.md` are canon, published out** (ADR 0103, 0104). They are authored under `.textus/zones/knowledge/` and published verbatim to the repo root with an editor banner (the same pattern as `docs/`); a hand-edit to a front-door doc is clobbered by `reconcile` and caught by the CI no-op gate.
+
+### Changed
+
+- **Docs SSoT/DRY cleanup** (ADR 0098). The duplicated ADR index is single-sourced — the mechanical status board lives in `docs/reference/adr-log.md`, and the curated decisions README becomes an annotated reading guide; the verb producer depends on `Read::Capabilities` rather than reaching into `Dispatcher` internals; a conformance guard keeps the `events` / `zones` / `mcp` projections covered.
+
+### Internal
+
+- **The architecture is now executable, and the produce / schema / port layers are decomposed** (ADR 0092, 0099–0101, 0105–0109). The hexagonal layering is enforced by a conformance guard with the layer map written to `lib/textus/ARCHITECTURE.md` (0106); the verb token gains a build-time route ⟺ contract bijection guard (0105); the divergent staleness comparisons collapse into one `Domain::Freshness::Evaluator` (0099); the produce pipeline is gathered under `lib/textus/produce/` with an `acquire` ÷ `render` split and the `fetch_*` fossils renamed (0100); two interface fossils are removed (0101); `manifest/schema.rb` splits its validation walk into `Schema::Validator` and its constants into `Schema::Vocabulary` + `Schema::Keys` (0107, 0109); every port becomes one shape — an instantiable class (0108, 0109); and the conformance spec tier is consolidated (67→19 loose) and coupled to the contract rather than to fixture spelling (0092). No behaviour, manifest-grammar, or verb-surface change.
+
+## 0.50.0 — 2026-06-04 — Observability on two axes + boot lifecycle (ADR 0083, 0084, 0085)
+
+`freshness` collapses into `pulse`, the contract-drift guard stops deadlocking, and `boot` gains a lean session-start projection shipped via a plugin.
+
+### Added
+
+- **`boot --lean`** (ADR 0084) — a compact orientation projection (`protocol`, `store_root`, `zones`, `agent_quickstart`, `contract_etag`) for cheap session-start injection. The full `boot` envelope now also carries `contract_etag`. `--lean` is a contract arg, so it threads to every surface (CLI flag, MCP `lean` tool arg, Ruby kwarg).
+- **textus ships as a Claude Code plugin** (ADR 0084) — a single self-contained `.claude-plugin/plugin.json` with an **inline** `SessionStart` hook (`startup`/`clear`/`compact`) that runs `boot --lean`, so enabling the plugin auto-orients each session. The agent-invokable `boot` tool is unchanged; the hook is additive. Plugin data is kept inside `.claude-plugin/` (a separate concern from the gem), not a top-level `hooks/` dir.
+- **Agent-integration config is textus-managed, projected from canon** (ADR 0086). This repo's `.mcp.json` and `.claude-plugin/plugin.json` are now **build artifacts** — `textus build` projects them from `knowledge.project` + `Textus::VERSION` (so the plugin version can never drift off the gem) the same way it projects `CLAUDE.md`. The plugin manifest also gains an inline `mcpServers` stanza (enable the plugin → MCP server *and* orientation hook in one). A new `provenance: false` derived-entry flag lets the JSON renderer emit config without a `_meta` block. Downstream consumers are unaffected — `init --with-agent` still scaffolds a write-once `.mcp.json` (a build must never clobber a user's config).
+
+### Changed
+
+- **The contract-drift guard applies to mutating verbs only; `boot` self-heals** (ADR 0083). A mid-session manifest/hook/schema edit no longer deadlocks every MCP verb behind "re-run boot": pure reads and `boot` bypass the guard, `boot` re-arms the session's cached `contract_etag`, and only mutating verbs (the `Write::` family + the destructive `Maintenance::` verbs `tend`/`zone_mv`/`key_mv_prefix`/`key_delete_prefix`) enforce it. "Re-run boot" now actually recovers instead of looping. Refines ADR 0074.
+- **`tend` returns a health summary, not full `issues[]`** (ADR 0085) — matching `pulse`; `doctor` stays the sole owner of detailed health output.
+
+### Removed (breaking)
+
+- **The public `freshness` verb** (ADR 0085). Observability is now two verbs on orthogonal axes — `pulse` (transient/temporal: `changed` + `stale` + `next_due_at`) and `doctor` (structural correctness). The lifecycle scan that backed `freshness` becomes a Ruby-only internal (empty `surfaces`, ADR 0073) consumed by `pulse` and the hook context; per-entry detail is reconstructable from `get` (carries `stale`/`last_fetched_at`) + `rule_explain` (the `lifecycle:` ttl + `on_expire`). **Migration:** replace `textus freshness` with `textus pulse` (for the `stale` list / `next_due_at`) or `get` + `rule_explain` (for one entry's verdict). SPEC's generator-drift attribution is corrected to `doctor`'s `generator_drift` check.
+
 ## 0.49.0 — 2026-06-04 — Normalize the key-verb family + remove `migrate` (ADR 0082)
 
 The single-key mutation verbs gain the `key_` family stem, and the `migrate` orchestrator is removed.

data/README.md

@@ -1,3 +1,4 @@
+<!-- Generated from .textus/zones/knowledge/readme.md — edit there, then run `textus reconcile`. Do not hand-edit README.md (it is clobbered on reconcile and flagged by doctor). ADR 0103. -->
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/branding/wordmark-dark.png">
@@ -37,11 +38,9 @@ flowchart LR
     human -->|author| knowledge["knowledge<br/>(canon)"]
     agent -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    automation -->|fetch| feeds["feeds<br/>(quarantine)"]
-    automation -->|build| artifacts["artifacts<br/>(derived)"]
+    automation -->|reconcile| artifacts["artifacts<br/>(machine)"]
 
     proposals ==>|human accept| knowledge
-    feeds -.->|projection source| artifacts
     knowledge -.->|projection source| artifacts
 
     classDef actor fill:#238636,stroke:#2ea043,color:#fff;
@@ -65,23 +64,22 @@ DURABLE       │  notebook                │  knowledge  ★ the goal
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
-TRANSIENT     │  feeds                   │  proposals  (queue)           │
+TRANSIENT     │  artifacts.feeds.*       │  proposals  (queue)           │
 (staging)     │  raw external input,     │  a candidate, in review       │
-              │  unverified              │  ▲ climbs via human accept    │
+              │  unverified (machine)    │  ▲ climbs via human accept    │
               └──────────────────────────┴───────────────────────────────┘
                 raw material ──── propose ────► a human accept lifts it to canon
 ```
 
-*(The fifth lane, `artifacts`, isn't on this grid — it's a derived **output**, computed from the lanes rather than an input climbing toward trust.)*
+*(The `machine` lane's other half, `artifacts.derived.*`, isn't on this grid — it's a computed **output** projected from the lanes, not an input climbing toward trust.)*
 
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — called a **zone** in the manifest and CLI, the term used everywhere technical from here on — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
 
 ```
 knowledge/   author only        — who you are, what you decide, how you sound (knowledge.identity.* for identity facts)
 notebook/    keep only          — agent's own durable lane (agents keep theirs; bytes climb to knowledge only via propose→accept)
-feeds/       fetch only         — declared external inputs
 proposals/   propose (agent + human) — proposals waiting on a human accept
-artifacts/   build only         — computed, published artifacts
+artifacts/   reconcile only     — machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
 ```
 
 An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
@@ -111,7 +109,7 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 ## Try it
 
-- **Worked end-to-end store** — the role gate (propose → accept), build/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`examples/project/`](examples/project/)
+- **Worked end-to-end store** — the role gate (propose → accept), reconcile/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`examples/project/`](examples/project/)
 - **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md)
 
 ## Protocol, not just a gem
@@ -139,20 +137,19 @@ bundle exec exe/textus --help
 
 ## What `textus init` gives you
 
-You get `.textus/` with all five zone directories, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, fetch/build locks). Roles declare capabilities; each zone declares a `kind:`, and write authority is derived from the role's capabilities crossed with the zone's kind:
+You get `.textus/` with all four zone directories, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, produce locks). Roles declare capabilities; each zone declares a `kind:`, and write authority is derived from the role's capabilities crossed with the zone's kind:
 
 ```yaml
 roles:
   - { name: human,      can: [author, propose] }
   - { name: agent,      can: [propose, keep] }
-  - { name: automation, can: [fetch, build] }
+  - { name: automation, can: [reconcile] }
 
 zones:
-  - { name: knowledge,  kind: canon }      # author — canonical truth
-  - { name: notebook,   kind: workspace }  # keep — agent's own durable lane
-  - { name: feeds,      kind: quarantine } # fetch — declared external inputs
-  - { name: proposals,  kind: queue }      # propose — proposals awaiting accept
-  - { name: artifacts,  kind: derived }    # build — computed outputs
+  - { name: knowledge, kind: canon }      # author    — canonical truth
+  - { name: notebook,  kind: workspace }  # keep      — agent's own durable lane
+  - { name: proposals, kind: queue }      # propose   — proposals awaiting accept
+  - { name: artifacts, kind: machine }    # reconcile — external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
 ```
 
 ```
@@ -165,14 +162,13 @@ zones:
   zones/                 # one dir per zone; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
     notebook/
-    feeds/
     proposals/
-    artifacts/
+    artifacts/           # machine lane: feeds/ (external inputs) + derived/ (computed outputs)
   .run/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
     audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~50 MB)
     state/cursor.<role>  # per-role pulse cursor — where `pulse --since` resumes
-    locks/  build.lock   # per-key fetch locks + the build mutex
-    sentinels/           # publish bookkeeping (target sha) — regenerated on build (ADR 0070)
+    locks/               # per-key produce locks + the produce mutex
+    sentinels/           # publish bookkeeping (target sha) — regenerated on reconcile (ADR 0070)
 ```
 
 Manifest `path:` fields are relative to `.textus/zones/`. So `knowledge.notes.org.jane` lives at `.textus/zones/knowledge/notes/org/jane.md`.
@@ -184,20 +180,20 @@ textus get knowledge.notes.org.jane
 textus list --zone=knowledge
 printf '%s' '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put knowledge.notes.bob --as=human --stdin
-textus freshness --zone=artifacts    # per-entry fresh/expired/no_policy + on_expire action
+textus reconcile --as=automation     # re-pull stale inputs + recompute derived outputs
 textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
 ```
 
 (All verbs return JSON envelopes; `--output=json` is the default and the only format in v1.)
 
-For a worked store — knowledge entries, a staged proposal, schemas, a template, and a build that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
+For a worked store — knowledge entries, a staged proposal, schemas, a template, and a `reconcile` that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
 
 ## What's shipped
 
 - **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))
+- **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`, `machine`→`reconcile`, `queue`→`propose`). 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))
 - **`textus doctor`.** Health checks across schemas, hooks, keys, sentinels, and the audit log.
 
@@ -210,13 +206,15 @@ Every command operates on one store, located in this order: `--root <path>` flag
 
 `textus boot` 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
+## Produce and publish
 
-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.
+Produced entries (`kind: produced`) declare how they're acquired in one `source:` block (ADR 0093/0094); `reconcile` materialises them:
 
-For externally-generated entries, declare `compute: { kind: external, sources: [...] }` — textus tracks the declared sources for staleness; the build automation produces the file.
+- **`source: { from: project, select: [...], pluck:, sort_by:, limit:, transform: name }`** — a *projection*: textus computes the entry's data from other entries, then renders it through 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.
+- **`source: { from: handler, handler: name, ttl: 1h, config: {...} }`** — *intake*: an RPC handler pulls external bytes on a `ttl` cadence; `reconcile` re-pulls when the entry goes stale.
+- **`source: { from: command, sources: [...] }`** — *externally generated*: an out-of-band command writes the file; textus tracks the declared `sources` for staleness.
 
-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/.run/sentinels/` (git-ignored runtime state, regenerated on build — ADR 0070). See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052). `publish: { to: [path, ...] }` byte-copies a single produced 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/.run/sentinels/` (git-ignored runtime state, regenerated on reconcile — ADR 0070). See SPEC §5.2, §5.3, §5.12.
 
 ## Extension points
 
@@ -226,7 +224,7 @@ textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectorie
 
 | Event | Fires when | You return |
 |---|---|---|
-| `:resolve_intake` | a fetch needs bytes | `{_meta:, body:}` |
+| `:resolve_handler` | an intake needs bytes | `{_meta:, body:}` |
 | `:transform_rows` | a projection builds | the reshaped rows |
 | `:validate` | `textus doctor` runs | doctor issues (or none) |
 
@@ -234,19 +232,19 @@ textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectorie
 
 | Event(s) | Fires when |
 |---|---|
-| `:entry_put` · `:entry_deleted` · `:entry_renamed` | a write lands |
-| `:entry_fetched` | a fetch-driven write lands |
-| `:build_completed` | a derived entry materializes |
-| `:file_published` | a derived file is copied to its target |
+| `:entry_written` · `:entry_deleted` · `:entry_renamed` | a write lands |
+| `:entry_fetched` | an intake-driven write lands |
+| `:entry_produced` | a produced entry materializes |
+| `:entry_published` | a produced file is copied to its target |
 | `:proposal_accepted` · `:proposal_rejected` | a proposal is resolved |
-| `:fetch_started` · `:fetch_failed` · `:fetch_backgrounded` | background-fetch lifecycle |
-| `:store_loaded` | the store finishes loading |
+| `:entry_fetch_started` · `:entry_fetch_failed` · `:produce_failed` · `:reconcile_failed` | produce lifecycle |
+| `:store_loaded` · `:session_opened` | the store loads · a role connects |
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
 Textus.hook do |reg|
-  reg.on(:resolve_intake, :local_file) do |config:, args:, **|
-    path = config["path"] or raise "local-file requires intake.config.path"
+  reg.on(:resolve_handler, :local_file) do |config:, args:, **|
+    path = config["path"] or raise "local-file requires source.config.path"
     {
       _meta: { "last_fetched_at" => Time.now.utc.iso8601, "source_path" => path },
       body: File.read(File.expand_path(path)),
@@ -263,14 +261,14 @@ Textus.hook do |reg|
 end
 ```
 
-Stale intake entries refresh lazily on read: a `textus get KEY` whose matched
-`lifecycle` rule says `on_expire: refresh` re-pulls the source in-process before
-returning. To find what is due, list the expired entries:
+Stale intake entries are re-pulled by `reconcile`, not by reads — `get` is a pure
+read that annotates the returned envelope with a freshness verdict (ADR 0089).
+`reconcile` re-pulls anything past its `source.ttl` and recomputes derived outputs:
 
 ```sh
-textus freshness --zone=feeds --output=json   # rows with status: "expired"
-# then read each one (read-through refresh per its lifecycle rule):
-textus get feeds.calendar.events --as=automation
+textus reconcile --as=automation                  # re-pull every stale intake + recompute derived
+textus reconcile artifacts.feeds --as=automation  # scope to one prefix
+textus get artifacts.feeds.calendar.events         # a pure read; carries a freshness verdict
 ```
 
 See SPEC.md §5.10 for the full hook contract.
@@ -281,7 +279,7 @@ See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot
 
 ## Examples
 
-[`examples/project/`](examples/project/) — textus as a project's own context store (a fictional Rails service, `ledger`). Human-authored `knowledge/` (project facts, runbooks), a staged ADR in `proposals/` showing the agent-propose / human-accept loop, schemas validating each family, a mustache template plus a `:transform_rows` hook, and a `build` that publishes the `artifacts/orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
+[`examples/project/`](examples/project/) — textus as a project's own context store (a fictional Rails service, `ledger`). Human-authored `knowledge/` (project facts, runbooks), a staged ADR in `proposals/` showing the agent-propose / human-accept loop, schemas validating each family, a mustache template plus a `:transform_rows` hook, and a `reconcile` that publishes the `artifacts.derived.orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
 
 ## Tests