textus 0.20.2 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35d3b6540fc043048133df0874e76b36e522d844da783b69a5e8993418157ae4
-  data.tar.gz: e0293b87efb32c1edf2d6c0103dcd94289d91031a4be570f8fdd40fb681c1e79
+  metadata.gz: e822d94de7ae06481dd8c03eab813a097b62e78121d94c9d1045017675da665c
+  data.tar.gz: 3372f74bb31465b28be8e6ce5b4721a3f15cae7536ebdfc8ef9b6c6d7c9f2d88
 SHA512:
-  metadata.gz: '039b6f44941ea52ac8d956297d9619c4cc8b2346e7d8bced24bc5671506726a44348da66791aa6d032e56dd403353d1b34e9b2fee37eaec05cd6c83d5defc715'
-  data.tar.gz: e6e5e8f97f5f9a07a03813d61f9efa2088fb8f1338af89ba1298bf307c6c72e89f1028aa5a67ffdf8f97f2151c0af1273f82ff80751c59c11aa93ef2953323a9
+  metadata.gz: 31e4b83f9a7d3b061d043c447393b23ba404a47e7d79b0a411ad49719625d01ec30116a067f28bf88ac6944ff0262c1825d35c851022340d63b813dca26f98aa
+  data.tar.gz: 590cc3419cb7823688bab11c4fce49a011bf62b463ab887b415753dd3c8037cd0704b8ccc4df6e778b21c04bd8101847a28fa5d4819e447e7af3d44febc017f3

data/ARCHITECTURE.md

@@ -2,88 +2,191 @@
 
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  ops = Operations.for(store, role:)            │
-│              ops.<name>(...)   # flat methods, one per use │
-│                                # case (put/get/refresh/…)  │
+│  CLI verbs:  session = Session.for(store, role:)           │
+│              session.<name>(...)   # one method per         │
+│                                # registered use case        │
+│                                # (put/get/refresh/…)        │
 │                                                            │
-│  Or, for embedders bringing their own ports:               │
-│              Operations.new(ctx:, manifest:, file_store:,  │
-│                             schemas:, audit_log:, bus:,    │
-│                             registry:, root:, store:)      │
+│  MCP gate:   textus mcp serve — same use cases, JSON-RPC.  │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
 │  Context          (slim Data: role, correlation_id, now,   │
 │                    dry_run — request state only)           │
-│  Operations       (flat facade; inline use-case factories) │
+│  Caps             (Read/Write/Hook records — store slices) │
+│  Session          (per-call dispatch; methods generated    │
+│                    from UseCase registry)                  │
+│  UseCase          (registry: verb → module, caps_kind)     │
 │                                                            │
-│  reads/{get,list,where,uid,schema_envelope,deps,rdeps,     │
-│         published,stale,validate_all,freshness,audit,      │
-│         blame,policy_explain,get_or_refresh}.rb            │
-│  writes/{put,delete,mv,accept,reject,build,publish,        │
-│          envelope_io}.rb                                   │
-│  refresh/{worker,orchestrator,all}.rb                      │
-│  policy/{promotion,predicates/{schema_valid,human_accept}} │
+│  read/{get,get_or_refresh,list,where,uid,schema_envelope,  │
+│        deps,rdeps,published,stale,validate_all,            │
+│        freshness,audit,blame,policy_explain,pulse}.rb      │
+│  write/{put,delete,mv,accept,reject,publish,               │
+│         materializer,authority_gate,                       │
+│         refresh_worker,refresh_orchestrator,refresh_all}   │
+│  maintenance/{migrate,key_mv_prefix,key_delete_prefix,     │
+│               zone_mv,rule_lint}.rb                        │
+│  envelope/{reader,writer}.rb  (split: parse vs persist)    │
+│  projection.rb                                             │
 └──────────┬───────────────────────────────┬─────────────────┘
            │ uses domain                   │ uses ports
 ┌─ Domain ─▼─────────────────────────────────────────────────┐
 │  Authorizer         (manifest + role → allow / deny)       │
 │  Permission         (write/read predicate per zone)        │
 │  Freshness::{Policy,Verdict,Evaluator}                     │
-│  Action  Outcome                                           │
-│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist}        │
+│  Staleness          (Generator/Intake checks)              │
+│  Action  Outcome  Sentinel                                 │
+│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist,        │
+│           Predicates::{SchemaValid,AcceptAuthoritySigned}} │
 └──────────────────────────────────────────┬─────────────────┘
                                            │ implements
 ┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (composition root — wires ports)       │
+│  Store              (composition root — wires ports,       │
+│                      vends Sessions)                       │
 │  Storage::FileStore (bytes-only port: read/write/delete/   │
 │                      exists?/etag)                         │
-│  Manifest           (Entry, Rules, Schema, permission_for) │
+│  Manifest           (Data, Resolver, Policy, Rules)        │
 │  Schemas            (eager-load cache)                     │
-│  AuditLog                                                  │
-│  Hooks::{Registry,Dispatcher,Loader,FireReport}            │
-│  Infra::{Publisher,EventBus,Clock,Refresh::Lock,           │
-│          Refresh::Detached,BuildLock,AuditSubscriber}      │
+│  Infra::{AuditLog,AuditSubscriber,Publisher,Clock,         │
+│          Refresh::Lock,Refresh::Detached,BuildLock}        │
+│  Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,   │
+│          Builtin,ErrorLog}                                 │
 │  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
    Dependency rule: arrows point DOWN. Domain has zero outbound
    imports. Application imports Domain + Infra (via ports).
-   Use cases declare their real ports in their constructor.
+   Use cases declare their real collaborators in their Impl
+   constructor; UseCase.register hooks them into Session.
 ```
 
-## Read path (`ops.get(key)`)
+## How a verb becomes a method
 
-1. CLI verb (or any external caller) builds `ops = Textus::Operations.for(store, role:)` then `ops.get(key)`.
-2. `Operations#get` constructs `Application::Reads::Get.new(ctx:, manifest:, file_store:)` and calls it.
-3. `Reads::Get#call(key)` resolves the path through `@manifest`, reads bytes via `@file_store`, parses the envelope.
-4. Looks up the refresh policy via `@manifest.rules_for(key)`. If absent, returns the envelope annotated fresh.
+Each application use case is a module under `lib/textus/application/{read,write,maintenance}/`. The shape is uniform:
+
+```ruby
+module Textus
+  module Application
+    module Read
+      module Get
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, ...)
+            @ctx = ctx; @manifest = caps.manifest; ...
+          end
+
+          def call(key) ... end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:get, Textus::Application::Read::Get, caps: :read)
+```
+
+`Session` generates one dispatch method per registered entry (see `lib/textus/session.rb` — the `Application::UseCase.each do |entry| ... end` block at the bottom). Adding a new verb is **one `UseCase.register` line** plus the module — no edits to `Session`.
+
+Two collaborators live outside the registry because they're composed by other use cases, not invoked as verbs:
+
+- `Application::Write::RefreshOrchestrator` — composes `RefreshWorker` with the freshness `Action` returned by `Domain::Freshness`. Session memoizes one (`session.refresh_orchestrator`).
+- `Application::Envelope::{Reader,Writer}` — own the parse and persist halves of the write pipeline; the audit-append-as-final-step invariant lives in `Writer`. Session memoizes both.
+
+## Caps
+
+Use cases never see the raw `Store`. `Application::Caps` defines three role-scoped slices:
+
+```ruby
+ReadCaps  = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events)
+WriteCaps = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events, :authorizer)
+HookCaps  = Data.define(:events, :rpc, :manifest, :root)
+```
+
+`Session.for(store, role:)` builds all three via `Application.caps_from_store(store)`; the dispatch method picks `read_caps` or `write_caps` based on the `caps_kind` declared at registration time. RPC hook callables (`:resolve_intake`, `:transform_rows`, `:validate`) receive a `caps:` kwarg that is the appropriate Read/Write slice — legacy `store:` is rejected by `Hooks::RpcRegistry#invoke`.
+
+## Read path (`session.get(key)`)
+
+1. CLI verb (or MCP tool) builds `session = Session.for(store, role:)` then `session.get(key)`.
+2. `Session#get` dispatches to `Application::Read::Get.call(key, session:, ctx:, caps:)`.
+3. `Read::Get::Impl#call` resolves the path through `caps.manifest`, reads bytes via `caps.file_store`, parses the envelope.
+4. Looks up the refresh policy via `caps.manifest.rules.for(key)`. If absent, returns the envelope annotated fresh.
 5. Otherwise `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`; the envelope is annotated with `stale`, `reason`, `refreshing: false`.
 
-`ops.get_or_refresh(key)` composes `Reads::Get` with `Refresh::Orchestrator` to optionally refresh on stale — same as 0.18.x.
+`session.get_or_refresh(key)` composes `Read::Get` with `Write::RefreshOrchestrator` to optionally refresh on stale.
 
-## Write path (`ops.put(key, ...)`)
+## Write path (`session.put(key, ...)`)
 
-1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.put(key, meta:, body:, content:, if_etag:)`.
-2. `Writes::Put#call` validates the key, resolves the manifest entry, and calls `@authorizer.authorize_write!(mentry, role: @ctx.role)` — raises `WriteForbidden` if denied.
-3. Delegates persistence to `EnvelopeIO#write`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
-4. Publishes `:entry_put` via `@bus` with `store: @store`, `key:`, `envelope:`, `role: @ctx.role`, `correlation_id: @ctx.correlation_id`.
+1. CLI verb calls `session = Session.for(store, role:)` then `session.put(key, meta:, body:, content:, if_etag:)`.
+2. `Write::Put::Impl#call` validates the key, resolves the manifest entry, and calls `@authorizer.authorize_write!(mentry, role: @ctx.role)` — raises `WriteForbidden` if denied.
+3. Delegates persistence to `session.envelope_writer.put`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
+4. Publishes `:entry_put` via `caps.events` with `ctx: session.hook_context`, `key:`, `envelope:`.
 
-`Writes::{Delete,Mv,Accept,Reject,Build,Publish}` follow the same shape: explicit ports, `Authorizer` for authz, `EnvelopeIO` for persistence (where applicable), event published with `store: real Store + role:` in payload.
+`Write::{Delete,Mv,Accept,Reject,Publish}` follow the same shape: explicit caps, `Authorizer` for authz, `Envelope::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
 
-`Writes::Mv` delegates the file-move + audit to `EnvelopeIO#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `EnvelopeIO#write` directly — no `Put` bypass.
+`Write::Mv` delegates the file-move + audit to `Envelope::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::Writer#write` directly — no `Put` bypass.
 
-## Refresh path (`ops.refresh(key)`)
+## Refresh path (`session.refresh(key)`)
 
-1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh(key)`.
-2. `Refresh::Worker#run(key)`:
-   - Resolves the manifest entry, looks up the intake handler via `@registry.rpc_callable(:resolve_intake, mentry.intake_handler)`.
-   - Publishes `:refresh_started` with `role:` in the payload.
+1. CLI `Verb::Refresh` builds `session = Session.for(store, role: "runner")` then calls `session.refresh(key)`.
+2. `Write::RefreshWorker::Impl#run(key)`:
+   - Resolves the manifest entry, looks up the intake handler via `caps.rpc.callable(:resolve_intake, mentry.handler)`.
+   - Publishes `:refresh_started` with the hook context.
    - Invokes the handler under a 30s thread-join deadline.
    - On any error: publishes `:refresh_failed`, then re-raises.
-   - On success: applies `@authorizer.authorize_write!` and persists via `EnvelopeIO#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
-3. `ops.refresh_all(prefix:, zone:)` lists stale entries via `Reads::Stale` and runs `Worker#run` per entry; returns `{ refreshed:, failed:, skipped: }`.
+   - On success: applies `@authorizer.authorize_write!` and persists via `Envelope::Writer#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
+3. `session.refresh_all(prefix:, zone:)` lists stale entries via `Read::Stale` and runs `Worker#run` per entry; returns `{ refreshed:, failed:, skipped: }`.
 
 ## Hook payload contract
 
-Hooks/intakes/transforms receive the actual `Textus::Store` (the composition root) as `store:`. Every write/refresh event payload carries `role:` directly so hook authors observe the actor without reaching through `store:`.
+Pub-sub hooks (`:entry_put`, `:entry_refreshed`, …) receive `ctx:` — a `Textus::Hooks::Context` that wraps the session and exposes a narrow surface (`get`, `list`, `put`, `delete`, `audit`, `publish_followup`, plus `role` and `correlation_id`). The raw `Store` is not handed out.
+
+RPC hooks (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps:` — a `ReadCaps` or `WriteCaps` slice. They are gem-internal: the framework calls them, not user pub-sub.
+
+## Agent surface (boot + pulse + MCP)
+
+Agents and plugins talk to a textus store through three layers:
+
+```
+soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Session  ──▶  memory (.textus/)
+```
+
+Two transports, one façade:
+
+- **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
+- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, manifest_etag) is server-side.
+
+Both transports call `Session.for(store, role:)`. No duplicate logic.
+
+The agent loop (cadence guide in `docs/agent-integration.md`):
+
+1. **Session start:** `boot()` → contract envelope (zones, entries, schemas, write_flows, agent_quickstart with `latest_seq`).
+2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
+3. **On demand:** `get`, `put`, `propose`, `refresh`, `schema`, `rules`.
+
+Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
+
+## Hooks::EventBus event catalog
+
+RPC (single handler, declares `caps:`):
+- `resolve_intake(caps:, config:, args:)` — intake fetch handler.
+- `transform_rows(caps:, rows:, config:)` — row transform for intakes.
+- `validate(caps:)` — custom doctor validator.
+
+Pub-sub (0..N handlers, declare `ctx:`):
+- `entry_put(ctx:, key:, envelope:)`
+- `entry_deleted(ctx:, key:)`
+- `entry_refreshed(ctx:, key:, envelope:, change:)`
+- `entry_renamed(ctx:, key:, from_key:, to_key:, envelope:)`
+- `build_completed(ctx:, key:, envelope:, sources:)`
+- `proposal_accepted(ctx:, key:, target_key:)`
+- `proposal_rejected(ctx:, key:, target_key:)`
+- `file_published(ctx:, key:, envelope:, source:, target:)`
+- `store_loaded(ctx:)`
+- `refresh_started(ctx:, key:, mode:)`
+- `refresh_failed(ctx:, key:, error_class:, error_message:)`
+- `refresh_backgrounded(ctx:, key:, started_at:, budget_ms:)`
+
+Authoritative source: `lib/textus/hooks/event_bus.rb` `EVENTS`.

data/CHANGELOG.md

@@ -9,6 +9,200 @@ 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.26.0 — 2026-05-28
+
+### Breaking
+- Split `Textus::Hooks::Bus` into `Textus::Hooks::EventBus` (pubsub) and `Textus::Hooks::RpcRegistry` (named callables). The `Hooks::Bus` constant is removed.
+- Replaced `Textus::Application::Ports` with three capability records: `Textus::Application::ReadCaps`, `WriteCaps`, `HookCaps`.
+- Renamed `Textus::Operations` to `Textus::Session`. Access via `store.session(role:)`. `Operations.for(store, ...)` is removed.
+- Hook RPC callables (`resolve_intake`, `transform_rows`, `validate`) no longer accept `store:` — declare `caps:` (a `WriteCaps` for `resolve_intake`/`validate`, `ReadCaps` for `transform_rows`).
+- Removed all `Manifest` top-level deprecation shims (`zones`, `entries`, `zone_writers`, `permission_for`, etc.). Use `manifest.data.*` / `manifest.policy.*` / `manifest.resolver.*` / `manifest.rules.*`.
+- Moved `Textus::Application::Writes::EnvelopeReader`/`EnvelopeWriter` to `Textus::Application::Envelope::Reader`/`Writer`.
+- Renamed `Textus::Application::Writes` → `Textus::Application::Write`; `Textus::Application::Reads` → `Textus::Application::Read`; `Textus::Application::Restructure` → `Textus::Application::Maintenance`.
+- Merged `Textus::Application::Refresh::*` into `Textus::Application::Write::Refresh{Worker,Orchestrator,All}`.
+- Moved `Textus::Application::Policy::Promotion` and predicates to `Textus::Domain::Policy::Promotion`/`Predicates`.
+
+## 0.25.1 — 2026-05-28
+
+### Internal refactors
+
+- **ADR 0018**: `Manifest` is now a composition record over `Data`,
+  `Resolver`, `Policy`, `Rules`. Top-level methods like
+  `Manifest#permission_for` are deprecated; use
+  `manifest.policy.permission_for(zone)`. One-cycle bridge — shims
+  warn until 0.26.0.
+
+- **ADR 0016**: Application use cases take a single `ports:` kwarg
+  bundling six adapters + the store root. Hook DSL callables that
+  declare `|store:|` continue to work with a one-shot deprecation
+  warning per (event, hook_name); declare `|ports:|` to silence it.
+
+- **ADR 0017**: `Application::Writes::EnvelopeIO` split into
+  `EnvelopeReader` (parse) and `EnvelopeWriter` (put/delete/move
+  + audit). Every public `EnvelopeWriter` method now ends with an
+  audit-row append — the write-without-audit failure mode is gone.
+
+### Breaking (internal)
+
+- `Operations#store` accessor removed. There is no clean deprecation
+  shim because `Ports` cannot reconstruct a `Store`. External
+  callers should use `ops.ports.X` directly.
+
+- `Textus::Manifest::Entry::Base::PublishContext` struct shape
+  changed: `:store` removed, `:ports` + `:boot` added. Affects
+  third-party plugins that build custom derived entries.
+
+- `transform_context` passed to `transform_rows` RPC callables is
+  now an `Application::Ports`, not a `Store`. Transforms that treat
+  it as opaque continue to work; transforms that reach `.x` need
+  updates.
+
+No CLI verb signatures changed. No wire envelopes changed.
+Protocol remains `textus/3`.
+
+## 0.25.0 — 2026-05-28
+
+### Added (additive — backward-compatible pulse fields)
+- `pulse.manifest_etag` — sha256 of `manifest.yaml`; lets agents detect contract drift without a second verb.
+- `pulse.next_due_at` — soonest `next_due_at` across all entries with a refresh policy. Schedulers sleep until this timestamp instead of polling.
+- `pulse.hook_errors` — recent hook failures since cursor; bounded in-memory ring on `Hooks::Bus#error_log` (default 256).
+
+### Changed
+- `Application::Reads::Freshness` memoizes the evaluator verdict by `(key, last_refreshed_at)` per request — pulse no longer pays O(N) evaluator calls when nothing has changed.
+- `Application::Refresh::Orchestrator` gains a cooperative-cancel fallback for `RefreshTimed` when `fork(2)` is unavailable (Windows). Previously degraded to `Failed("timed_sync requires fork")`; now executes within the budget on a Thread, killing it on budget exceeded.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged. Pulse fields are additive — existing consumers ignoring unknown keys continue to work.
+
+## 0.24.0 — 2026-05-28
+
+### Added
+- **Context-structure ergonomics** (ADR 0015 Phase 2):
+  - `textus key mv --prefix OLD NEW` — bulk rename leaves under a prefix; preserves UIDs.
+  - `textus key delete --prefix P` — bulk delete leaves.
+  - `textus zone mv FROM TO` — rename a zone; refuses if destination exists; rewrites manifest + moves files.
+  - `textus rule lint --against=FILE` — diff candidate manifest YAML's `rules:` block against the live manifest.
+  - `textus migrate PLAN.yaml` — run a multi-op declarative migration plan (ops: `key_mv_prefix`, `key_delete_prefix`, `zone_mv`).
+  - All five operations also surface as MCP tools (`key_mv_prefix`, `key_delete_prefix`, `zone_mv`, `rule_lint`, `migrate`).
+- `Textus::Application::Restructure` module with `Plan` value object and one use case per operation.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged.
+
+## 0.23.0 — 2026-05-28
+
+### Added
+- **Agent gate (MCP transport).** `textus mcp serve` — stdio JSON-RPC 2.0
+  server speaking MCP draft 2024-11-05. Wraps `Textus::Operations` as ten
+  auto-derived tools (`boot`, `tick`, `find`, `read`, `write`, `propose`,
+  `refresh`, `refresh_stale`, `schema`, `rules`). Session state (cursor,
+  role, manifest_etag) held server-side. Manifest drift surfaces as
+  `ContractDrift` (-32001); cursor expiry as `CursorExpired` (-32002).
+  See [`docs/mcp.md`](docs/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
+- `examples/claude-plugin/.mcp.json` and migrated skills/commands/agents —
+  zero `textus <verb>` shell strings remain in plugin markdown.
+
+### Changed (docs)
+- `ARCHITECTURE.md`: fixed stale `registry` references (now `bus`),
+  added Agent Surface section and complete Hooks::Bus event catalog.
+- `docs/agent-integration.md`: documents three transports (CLI, Ruby API,
+  MCP); points agent authors at the MCP transport by default.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged.
+
+## 0.22.0 — 2026-05-28
+
+### Changed (internal — no manifest-schema impact)
+- **Entry polymorphism pass.** Behavior-preserving refactor that
+  consolidates cross-cutting fields on `Manifest::Entry::Base` and
+  replaces case-statement dispatch with polymorphic methods. Adding
+  a new entry kind now costs ~1 file edit instead of ~5–10.
+  - `publish_to` is now owned by `Base` (was declared four separate
+    times across Leaf/Derived/Nested/Intake).
+  - `Base` exposes nil-returning stubs for `template`, `inject_boot`,
+    `events`, `publish_each`, `index_filename` — validators and
+    serializers no longer need `respond_to?` guards.
+  - `Publish#call` dispatches via `entry.publish_via(context)` instead
+    of a 4-branch case-statement. The byte-identical
+    `publish_leaf_entry` / `publish_intake_entry` helpers are gone.
+  - Each `Entry` subclass declares a `KIND` constant and a
+    `self.from_raw(common, raw)` factory; `Parser` dispatches via
+    `Entry::REGISTRY` instead of a closed `case kind`.
+  - Dead `Base#kind` method removed.
+
+No public API or manifest YAML changes. All existing manifests load
+identically.
+
+Remaining `is_a?(Entry::Derived)` callsites in `builder/`, `renderer/`,
+`application/reads/`, and `domain/staleness/` are out of scope for this
+pass — they touch a different polymorphism axis (what data the entry
+contributes to a build) and will be addressed in a follow-up.
+
+Known follow-up: `Intake#nested?` still reads `@raw["nested"]` to
+preserve the `kind: intake, nested: true` YAML overlay used by nested
+intake handlers. This dual discriminator (`kind:` + `nested:`) is a
+design tension worth revisiting alongside the broader is_a? cleanup.
+
+## 0.21.1 — 2026-05-27
+
+### Fixed
+- **Intake entries can now act as builder outputs.** Two related gaps closed:
+  - `FormatMatrix` validator no longer rejects `kind: intake` entries in
+    generator zones for missing a template. Intake bodies come from a
+    `:resolve_intake` handler, so the "derived format requires template"
+    rule never applied. (Error message widened from "derived #{format}"
+    to "#{format} entries in a generator zone require a template".)
+  - `Manifest::Entry::Intake` now parses `publish_to:` from YAML (was
+    hardcoded to `[]`).
+  - `textus publish` / `textus build` now fan out intake bodies to each
+    `publish_to` target, mirroring the Leaf fan-out path. Refresh-time
+    fan-out is unchanged — bodies still publish on the next publish/build
+    run.
+
+  Closes #80. Lets consumers replace `kind: derived, compute: { kind:
+  external }` runner glue with `kind: intake` + `Textus.on(:resolve_intake)`
+  hooks for builder-produced outputs.
+
+## 0.21.0 — 2026-05-27
+
+### BREAKING
+- `textus intro` is removed. Use `textus boot` instead — same envelope, same
+  use case, better name (pairs with the new `pulse` verb to form the agent
+  lifecycle: `boot` for static contract, `pulse` for dynamic state).
+- The `Textus::Intro` module is now `Textus::Boot`. The manifest entry field
+  `inject_intro:` is now `inject_boot:`. Builder template variable
+  `{{intro.*}}` is now `{{boot.*}}`. Pre-1.0; no compatibility alias.
+
+### Added
+- **`textus pulse [--since=N]`** — agent heartbeat verb. Returns an envelope
+  with `cursor` (current `latest_seq`), `changed` (audit rows since N),
+  `stale` (entries past refresh policy), `pending_review` (keys in review
+  zone), and `doctor` (ok/warn/fail counts). One round-trip replaces what
+  was previously four separate verbs.
+- **`agent_quickstart` block in `textus boot`** — names the read verbs,
+  write verbs, writable zones, default propose zone, and current
+  `latest_seq` (the starting cursor for `pulse`). Lets an agent boot once
+  and immediately know how to talk and where to start polling.
+- **Audit log rotation.** Active `audit.log` rotates to `audit.log.1` when
+  it exceeds `audit.max_size` (default 10MB), keeping the last
+  `audit.keep` files (default 5). Each rotated file has a sidecar
+  `audit.log.N.meta.json` with `min_seq`/`max_seq`/`rotated_at`. Configure
+  via the new top-level `audit:` block in `manifest.yaml`.
+- **Monotonic `seq` on every audit row.** Foundation for cursor-based
+  queries; `audit --seq-since=N` and `pulse --since=N` both use it.
+- **`Textus::CursorExpired`** error class, raised by `pulse` and
+  `audit --seq-since` when the requested seq has rotated off disk. The
+  message names the oldest still-available seq and tells the agent to
+  re-orient via `textus boot`.
+- `docs/agent-integration.md` — boot → pulse → work loop reference, with
+  an example agent loop and cursor-expiry handling.
+
+### Changed
+- Audit rows now include a `seq` integer field (existing fields unchanged).
+- `textus boot` envelope gains `agent_quickstart` (additive — existing
+  consumers unaffected).
+
 ## 0.20.2 — 2026-05-27
 
 ### Fixed

data/README.md

@@ -5,7 +5,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg)](https://www.ruby-lang.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-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.
+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 boot`) and know what to read, what to write, and what's off-limits.
 
 Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
 
@@ -79,11 +79,12 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 - **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.
-- **Split build/publish (v0.14.0).** `Application::Writes::Build` materializes generator-zone entries; `Application::Writes::Publish` copies nested leaves to `publish_each` targets. The `textus build` CLI verb calls both and merges results, so wire output is unchanged.
+- **Build and publish in one pass.** `Application::Write::Publish` materializes generator-zone entries and copies nested leaves to their `publish_each` targets. The `textus build` CLI verb dispatches to it; the wire envelope is unchanged.
 - **Typed envelopes (v0.14.0).** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
 - **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 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 boot`.** 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, and an `agent_quickstart` block (read/write verbs, writable zones, propose zone, latest audit seq). The boot signal for any agent — one tool call and it knows your store.
+- **`textus pulse [--since=N]`.** Per-turn heartbeat for agents: changed entries since cursor N, stale keys, pending review proposals, and a doctor summary. Cursor is a monotonic seq stamped on every audit row; rotation keeps the last 5 files (configurable via `audit:` in the manifest) and raises `CursorExpired` when the requested cursor has fallen off disk.
 - **`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.
@@ -97,7 +98,7 @@ All verbs accept `--output=json` and return the envelope defined in [SPEC §8](S
 - 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.
+`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
 
@@ -150,9 +151,11 @@ 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.
 
+See [`docs/agent-integration.md`](docs/agent-integration.md) for the agent boot → pulse loop.
+
 ## 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 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`.
+[`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_boot:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests
 

data/SPEC.md

@@ -189,7 +189,7 @@ Validation at manifest load: any unknown variable raises `UsageError`; the templ
 
 A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/working/skills/writing/voice-writer.md`) publishes to `skills/voice-writer/SKILL.md`.
 
-**`inject_intro:`.** A derived entry with a `template:` MAY declare `inject_intro: true`. When the builder materializes the entry, it merges the `textus intro` envelope (§9) into the projection data under the key `intro`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus intro` exposes.
+**`inject_boot:`.** A derived entry with a `template:` MAY declare `inject_boot: true`. When the builder materializes the entry, it merges the `textus boot` envelope (§9) into the projection data under the key `boot`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus boot` exposes.
 
 **Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/zones/<entry.path>[/<remaining>...].md` — implementations MUST prepend `zones/` to the manifest `path:` when constructing the filesystem location.
 
@@ -430,9 +430,11 @@ Every successful write appends one compact JSON object (NDJSON) to `.textus/audi
 Schema (one JSON object per line, no interior whitespace):
 
 ```json
-{"ts":"<iso8601-utc>","role":"<role>","verb":"<verb>","key":"<key>","etag_before":<etag-or-null>,"etag_after":<etag-or-null>}
+{"seq":<integer>,"ts":"<iso8601-utc>","role":"<role>","verb":"<verb>","key":"<key>","etag_before":<etag-or-null>,"etag_after":<etag-or-null>}
 ```
 
+`seq` is a monotonic integer counter, auto-incremented on each append. It is the foundation for cursor-based queries: `textus audit --seq-since=N` returns only rows with `seq > N`, and `textus pulse --since=N` builds its `changed` array from the same cursor. When an agent's cursor falls below the oldest available seq (due to log rotation), the operation raises `CursorExpired`.
+
 `ts` is the wall-clock timestamp in UTC with second precision. `role` is the resolved role for the invocation. `verb` is the audit-log payload string identifying the operation (`put`, `delete`, `accept`, `compute`, `mv`, ...). `key` is the affected entry key. `etag_before` and `etag_after` are the entry etags before and after the write, or JSON `null` when not applicable (e.g. create has no before-etag, delete has no after-etag).
 
 For `mv`, the structural fields `from_key`, `to_key`, and `uid` appear at the top level of the JSON object. Remaining verb-specific data (e.g. `from_path`, `to_path`) is nested under an `extras` key. The `extras` key is omitted entirely when empty.
@@ -729,7 +731,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `hook list` | read | any |
 | `hook run NAME` | write | any |
 | `doctor [--check=NAME[,NAME]] [--output=json]` | read | any |
-| `intro [--output=json]` | read | any |
+| `boot [--output=json]` | read | any |
+| `pulse [--since=N]` | read | any |
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh KEY --as=runner` | write | per zone (typically `runner`) |
@@ -741,6 +744,36 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `key uid K` | read | any |
 
+**`textus boot` envelope extras.** In addition to zones, entries, hooks, write flows, and the `cli_verbs` catalog, the boot envelope includes an `agent_quickstart` block synthesized from the manifest's role-kind declarations:
+
+```json
+{
+  "agent_quickstart": {
+    "read_verbs":     ["boot", "get", "list", "audit", "pulse", "freshness", "doctor"],
+    "write_verbs":    ["put KEY --as=<proposer-role> --stdin"],
+    "writable_zones": ["review"],
+    "propose_zone":   "review",
+    "latest_seq":     1842
+  }
+}
+```
+
+`latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
+
+**`textus pulse` output shape:**
+
+```json
+{
+  "cursor":         1845,
+  "changed":        [ { "seq": 1843, "key": "working.x", "verb": "put", "role": "human", "ts": "..." } ],
+  "stale":          [ "output.marketplace" ],
+  "pending_review": [ "review.proposal.123" ],
+  "doctor":         { "ok": true, "warn": 0, "fail": 0 }
+}
+```
+
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the review zone. `doctor` is an `{ok, warn, fail}` count summary. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+
 **`put` input** (read from stdin when `--stdin` is given):
 
 ```json
@@ -798,6 +831,12 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 The reference Ruby gem follows semver independently and speaks `textus/3`.
 
+## 11.1 Agent integration
+
+Agents interact with a textus store through two verbs: `boot` (once per session, for orientation) and `pulse` (per turn, for deltas). The `boot` envelope's `agent_quickstart` block gives the agent its starting cursor (`latest_seq`), its writable zones, and its propose zone. The `pulse` verb returns a delta envelope keyed on that cursor. When audit log rotation expires a cursor, `CursorExpired` signals the agent to call `boot` again.
+
+For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/agent-integration.md`](docs/agent-integration.md).
+
 ## 12. Conformance fixtures
 
 A conformant implementation MUST pass these fixtures (the reference test suite ships a YAML file listing inputs and expected envelopes):
@@ -849,10 +888,10 @@ Given a review entry `review.identity.self.patch` proposing a change to `identit
 
 Textus internals are organized into four layers. The dependency rule is one-way — each layer may only import from the layer beneath it.
 
-- **Interface** (`lib/textus/cli/`) — CLI verbs. Parses flags, calls a use case, formats JSON.
-- **Application** (`lib/textus/application/`) — Use cases: `Reads::Get`, `Refresh::Worker`, `Refresh::Orchestrator`, `Refresh::All`. Orchestrate domain + infra; no business rules.
-- **Domain** (`lib/textus/domain/`) — Pure values: `Freshness::Policy`, `Action`, `Outcome`, `Freshness::Verdict`, `Freshness::Evaluator`. No I/O, no globals, testable without disk.
-- **Infrastructure** (`lib/textus/infra/`) — Adapters: `EventBus`, `Clock`, `Refresh::Lock`, `Refresh::Detached`. Wrap OS / library primitives.
+- **Interface** (`lib/textus/cli/`, `lib/textus/mcp/`) — CLI verbs and the MCP gate. Parses flags / RPC, calls a use case, formats JSON.
+- **Application** (`lib/textus/application/`) — Use cases: `Read::Get`, `Write::Put`, `Write::RefreshWorker`, `Write::RefreshOrchestrator`, `Write::RefreshAll`, `Maintenance::Migrate`, etc. Orchestrate domain + infra; no business rules.
+- **Domain** (`lib/textus/domain/`) — Pure values: `Authorizer`, `Permission`, `Freshness::{Policy,Verdict,Evaluator}`, `Action`, `Outcome`, `Sentinel`, `Staleness`. No I/O, no globals, testable without disk.
+- **Infrastructure** (`lib/textus/infra/`) — Adapters: `Storage::FileStore`, `AuditLog`, `AuditSubscriber`, `Publisher`, `Clock`, `Refresh::Lock`, `Refresh::Detached`, `BuildLock`. Wrap OS / library primitives.
 
 The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces are infrastructure adapters that predate this split and remain at their existing paths for backward-compat with the plugin DSL.
 
@@ -860,14 +899,14 @@ Plugin authors interact only with the Hook DSL (`Textus.hook { |reg| reg.on(:res
 
 Both read and write paths flow through the application layer:
 
-- **Reads** flow through `Application::Reads::Get`, which takes a `Context` and dispatches refresh via `Application::Refresh::Orchestrator`.
-- **Writes** flow through `Application::Writes::{Put,Delete,Build,Accept,Publish}`, each taking a `Context`. Permission checks happen at the use-case layer (via `Context#can_write?`); I/O happens at `Store::Writer#write_envelope_to_disk` (pure).
-- `Application::Context` is the universal request object: it carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. Use cases never thread these as separate kwargs.
-- `Textus::Operations` is the factory CLI verbs (and future MCP server / HTTP shim)
-  use to construct Contexts and use cases. `Operations.for(store, role:)` returns
-  a flat facade exposing one method per use case (`#put`, `#get`, `#refresh`, …);
-  internal use-case instances are memoized via `||=` and live under
-  `lib/textus/application/{reads,writes,refresh}/`.
+- **Reads** flow through `Application::Read::Get` (pure read + freshness annotation) or `Read::GetOrRefresh` (composes Get with `Write::RefreshOrchestrator`). Each takes a `caps:` slice and an `Application::Context`.
+- **Writes** flow through `Application::Write::{Put,Delete,Mv,Accept,Reject,Publish,RefreshWorker}`. Permission checks happen at the use-case layer (via `Domain::Authorizer#authorize_write!`); the audit-append invariant lives in `Application::Envelope::Writer`.
+- `Application::Context` is the slim request record: `role`, `correlation_id`, `now`, `dry_run`. Ports come from a `Caps` record (Read/Write/Hook), not from the Context.
+- `Textus::Session` is the factory CLI verbs and the MCP gate use to dispatch
+  use cases. `Session.for(store, role:)` returns a per-call object exposing one
+  method per registered use case (`#put`, `#get`, `#refresh`, …); methods are
+  generated from `Application::UseCase.entries` so adding a use case is a
+  single `UseCase.register(...)` line.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.