textus 0.20.2 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35d3b6540fc043048133df0874e76b36e522d844da783b69a5e8993418157ae4
-  data.tar.gz: e0293b87efb32c1edf2d6c0103dcd94289d91031a4be570f8fdd40fb681c1e79
+  metadata.gz: 38a9a929bb63f94d5a3cdc4708f09ce5c8e0eca28928d5733b8d842d90ece8b8
+  data.tar.gz: 26a8aeb22666788cd30e949eb25c7336db1de9ef7f4110aaf700f7abecdec644
 SHA512:
-  metadata.gz: '039b6f44941ea52ac8d956297d9619c4cc8b2346e7d8bced24bc5671506726a44348da66791aa6d032e56dd403353d1b34e9b2fee37eaec05cd6c83d5defc715'
-  data.tar.gz: e6e5e8f97f5f9a07a03813d61f9efa2088fb8f1338af89ba1298bf307c6c72e89f1028aa5a67ffdf8f97f2151c0af1273f82ff80751c59c11aa93ef2953323a9
+  metadata.gz: 9b4ce0da2828f2623f60601cdd0ac8a69e51cc9670c5de80b92e3b41e0f955361154664b8cb0a7de0e838b5403336ff26589698201885b44001a83cfcd2c3f21
+  data.tar.gz: 672d948ab0ccdea1470dcb38c87c233ed717a538d4e4902191a32224dac8475fe1269b4569be00e5eb1f40e9c6146f8867d557d6455601c13fc2e0ce2c381cae

data/CHANGELOG.md

@@ -9,6 +9,98 @@ 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.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/).
 
@@ -83,7 +83,8 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 - **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):

data/lib/textus/application/reads/audit.rb

@@ -8,27 +8,36 @@ module Textus
       # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
       # rows produce nil and are skipped).
       class Audit
-        def initialize(manifest:, root:)
-          @manifest = manifest
-          @log_path = File.join(root, "audit.log")
+        def initialize(manifest:, root:, audit_log: nil)
+          @manifest  = manifest
+          @root      = root
+          @log_path  = File.join(root, "audit.log")
+          @audit_log = audit_log
         end
 
         # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, correlation_id: nil, limit: nil)
-          return [] unless File.exist?(@log_path)
+        def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+          check_cursor_expiry!(seq_since)
+
+          files = all_log_files
+          return [] if files.empty?
 
           rows = []
-          File.foreach(@log_path) do |line|
-            parsed = parse_row(line.chomp)
-            next unless parsed
-            next if key   && parsed["key"]  != key
-            next if role  && parsed["role"] != role
-            next if verb  && parsed["verb"] != verb
-            next if zone  && !key_in_zone?(parsed["key"], zone)
-            next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
-            next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
+          files.each do |file|
+            File.foreach(file) do |line|
+              parsed = parse_row(line.chomp)
+              next unless parsed
+              next if key && parsed["key"] != key
+              next if role && parsed["role"] != role
+              next if verb && parsed["verb"] != verb
+              next if zone && !key_in_zone?(parsed["key"], zone)
+              next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
+              next if seq_since && (parsed["seq"].nil? || parsed["seq"] <= seq_since)
+              next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
 
-            rows << parsed
+              rows << parsed
+              break if limit && rows.length >= limit
+            end
             break if limit && rows.length >= limit
           end
           rows
@@ -48,6 +57,22 @@ module Textus
 
         private
 
+        def check_cursor_expiry!(seq_since)
+          return unless seq_since
+
+          log = @audit_log || Textus::Infra::AuditLog.new(@root)
+          min = log.min_available_seq
+          raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
+        end
+
+        def all_log_files
+          rotated = Dir.glob(File.join(@root, "audit.log.*"))
+                       .reject { |p| p.end_with?(".meta.json") }
+                       .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
+          active = File.exist?(@log_path) ? [@log_path] : []
+          rotated + active
+        end
+
         def parse_row(line)
           return nil if line.empty?
           return nil unless line.start_with?("{")

data/lib/textus/application/reads/pulse.rb

@@ -0,0 +1,63 @@
+module Textus
+  module Application
+    module Reads
+      # Aggregator over audit + freshness + review + doctor. One round-trip
+      # for an agent's per-turn heartbeat. All component reads are existing
+      # APIs; pulse is sugar with a stable envelope shape and a monotonic
+      # cursor (seq).
+      class Pulse
+        def initialize(ctx:, manifest:, file_store:, audit_log:, root:, store:)
+          @ctx        = ctx
+          @manifest   = manifest
+          @file_store = file_store
+          @audit_log  = audit_log
+          @root       = root
+          @store      = store
+        end
+
+        def call(since: 0)
+          changed = audit_changes_since(since)
+          {
+            "cursor" => @audit_log.latest_seq,
+            "changed" => changed,
+            "stale" => stale_keys,
+            "pending_review" => review_keys,
+            "doctor" => doctor_summary,
+          }
+        end
+
+        private
+
+        def audit_changes_since(seq)
+          Reads::Audit.new(manifest: @manifest, root: @root, audit_log: @audit_log)
+                      .call(seq_since: seq)
+        end
+
+        def stale_keys
+          # Freshness rows use symbol keys: { key: "x.y", status: :stale, ... }
+          rows = Reads::Freshness.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call
+          rows.select { |r| r[:status] == :stale }.map { |r| r[:key] }
+        end
+
+        def review_keys
+          # List constructor takes only manifest:; returns hashes with string keys.
+          # Guard: zones is a Hash keyed by name string.
+          return [] unless @manifest.zones.key?("review")
+
+          rows = Reads::List.new(manifest: @manifest).call(zone: "review")
+          rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+        end
+
+        def doctor_summary
+          result  = Textus::Doctor.run(@store)
+          issues  = result["issues"] || []
+          {
+            "ok" => result["ok"],
+            "warn" => issues.count { |i| i["level"] == "warning" },
+            "fail" => issues.count { |i| i["level"] == "error" },
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/materializer.rb

@@ -32,7 +32,7 @@ module Textus
             transform_resolver: ->(name) { @bus.rpc_callable(:transform_rows, name) },
             template_loader: ->(name) { read_template(name) },
             transform_context: @store,
-            inject_intro: -> { Textus::Intro.run(@store) },
+            inject_boot: -> { Textus::Boot.run(@store) },
           )
         end
 

data/lib/textus/application/writes/publish.rb

@@ -1,13 +1,14 @@
 module Textus
   module Application
     module Writes
-      # Single-pass publish use case: materializes Derived entries (template +
-      # projection + external runner) AND copies Leaf/Nested entries to their
-      # publish targets. Replaces the former two-step Build + Publish split.
+      # Single-pass publish use case: dispatches polymorphically to each
+      # entry's `publish_via` method. Derived entries materialize their body
+      # via Materializer; Nested entries fan out via publish_each; Leaf and
+      # Intake entries copy their stored body to publish_to targets. The
+      # Publish layer owns wiring (context, accumulation) but not per-kind
+      # logic.
       #
       # Return shape: { "protocol", "built", "published_leaves" }
-      # — wire-compatible with what the `textus build` CLI verb previously
-      #   assembled by merging Build + old Publish results.
       class Publish
         def initialize(ctx:, manifest:, file_store:, bus:, root:, store:, hook_context:) # rubocop:disable Metrics/ParameterLists
           @ctx          = ctx
@@ -22,26 +23,17 @@ module Textus
         def call(prefix: nil)
           built  = []
           leaves = []
-          repo_root = File.dirname(@root)
+          context = build_context
 
           @manifest.entries.each do |mentry|
             next if prefix && !entry_matches_prefix?(mentry, prefix)
 
-            case mentry
-            when Textus::Manifest::Entry::Derived
-              next unless mentry.in_generator_zone?
+            result = mentry.publish_via(context, prefix: prefix)
+            next if result.nil?
 
-              result = materialize_derived(mentry, repo_root)
-              built << result if result
-            when Textus::Manifest::Entry::Nested
-              next unless mentry.publish_each
-
-              publish_nested(mentry, repo_root, prefix, leaves)
-            when Textus::Manifest::Entry::Leaf
-              next if Array(mentry.publish_to).empty?
-
-              result = publish_leaf_entry(mentry, repo_root)
-              built << result if result
+            case result[:kind]
+            when :built  then built << result[:value]
+            when :leaves then leaves.concat(result[:value])
             end
           end
 
@@ -50,86 +42,19 @@ module Textus
 
         private
 
-        # Materialize a Derived entry and copy to publish_to targets.
-        def materialize_derived(mentry, repo_root)
-          target_path = Materializer.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-            bus: @bus, root: @root, store: @store
-          ).run(mentry)
-
-          publish_derived_copies(mentry, target_path, repo_root)
-          fire_build_completed(mentry)
-
-          { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
-        end
-
-        def publish_derived_copies(mentry, target_path, repo_root)
-          envelope = reader.call(mentry.key)
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: target_path,
-                          target: target_abs)
-          end
-        end
-
-        def fire_build_completed(mentry)
-          envelope = reader.call(mentry.key)
-          src = mentry.source
-          selects = src.is_a?(Textus::Manifest::Entry::Derived::Projection) ? Array(src.select).compact : []
-          publish_event(:build_completed,
-                        key: mentry.key,
-                        envelope: envelope,
-                        sources: selects)
-        end
-
-        # Publish each leaf under a Nested entry's publish_each pattern.
-        def publish_nested(mentry, repo_root, prefix, accumulator)
-          @manifest.resolver.enumerate(prefix: mentry.key).each do |row|
-            next unless row[:manifest_entry].equal?(mentry)
-            next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-            accumulator << publish_nested_leaf(mentry, row, repo_root)
-          end
-        end
-
-        def publish_nested_leaf(mentry, row, repo_root)
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: @root)
-          publish_event(:file_published,
-                        key: row[:key],
-                        envelope: reader.call(row[:key]),
-                        source: row[:path],
-                        target: target_abs)
-          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-        end
-
-        # Publish a standalone Leaf entry that has publish_to targets.
-        def publish_leaf_entry(mentry, repo_root)
-          source_path = @manifest.resolver.resolve(mentry.key).path
-          envelope = reader.call(mentry.key)
-
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: source_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: source_path,
-                          target: target_abs)
-          end
-
-          { "key" => mentry.key, "path" => source_path, "published_to" => mentry.publish_to }
+        def build_context
+          Textus::Manifest::Entry::Base::PublishContext.new(
+            repo_root: File.dirname(@root),
+            manifest: @manifest,
+            file_store: @file_store,
+            root: @root,
+            store: @store,
+            ctx: @ctx,
+            bus: @bus,
+            hook_context: @hook_context,
+            reader: reader,
+            emit: ->(event, **payload) { @bus.publish(event, ctx: @hook_context, **payload) },
+          )
         end
 
         # Whether the entry should be processed for the given prefix filter.
@@ -138,8 +63,6 @@ module Textus
 
           case mentry
           when Textus::Manifest::Entry::Nested
-            # Nested: process if the entry key is a prefix of `prefix` or
-            # `prefix` is a prefix of the entry key (a leaf under it).
             mentry.key.start_with?(prefix) ||
               prefix.start_with?("#{mentry.key}.")
           else
@@ -152,10 +75,6 @@ module Textus
             ctx: @ctx, manifest: @manifest, file_store: @file_store,
           )
         end
-
-        def publish_event(event, **payload)
-          @bus.publish(event, ctx: @hook_context, **payload)
-        end
       end
     end
   end

data/lib/textus/{intro.rb → boot.rb}

@@ -4,8 +4,8 @@ module Textus
   # project: zones and their write authority, entries and their flags,
   # registered hooks, write flows, and the CLI verb catalog.
   #
-  # Intro is side-effect-free.
-  module Intro
+  # Boot is side-effect-free.
+  module Boot
     PROTOCOL_ID = PROTOCOL
 
     # Conventional zone purposes. Unknown zones (declared in the manifest
@@ -95,10 +95,10 @@ module Textus
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
-    # Agents that read intro should see a stable shape regardless of how
+    # Agents that read boot should see a stable shape regardless of how
     # verb implementations evolve.
     CLI_VERBS = [
-      { "name" => "intro",    "summary" => "this output — orientation for agents and tools" },
+      { "name" => "boot",     "summary" => "this output — orientation for agents and tools" },
       { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
       { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
@@ -116,8 +116,29 @@ module Textus
       { "name" => "doctor", "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "pulse",
+        "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
+    def self.agent_quickstart(manifest, store)
+      proposer_roles = manifest.roles_with_kind(:proposer)
+      agent_role = proposer_roles.first
+
+      writable_zones = manifest.zones.each_with_object([]) do |(zname, writers), acc|
+        acc << zname if agent_role && writers.include?(agent_role)
+      end
+
+      propose_zone = writable_zones.find { |z| z.include?("review") } || writable_zones.first
+
+      {
+        "read_verbs" => %w[boot get list audit pulse freshness doctor],
+        "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        "writable_zones" => writable_zones,
+        "propose_zone" => propose_zone,
+        "latest_seq" => store.audit_log.latest_seq,
+      }
+    end
+
     def self.agent_protocol(manifest)
       AGENT_PROTOCOL_TEMPLATE.merge(
         "role_resolution" => {
@@ -139,6 +160,7 @@ module Textus
         "write_flows" => write_flows_for(store.manifest),
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(store.manifest),
+        "agent_quickstart" => agent_quickstart(store.manifest, store),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
@@ -165,7 +187,7 @@ module Textus
           "derived" => derived,
           "intake" => e.is_a?(Textus::Manifest::Entry::Intake),
           "publish_to" => Array(e.publish_to),
-          "publish_each" => e.respond_to?(:publish_each) ? e.publish_each : nil,
+          "publish_each" => e.publish_each,
         }
       end
     end

data/lib/textus/builder/pipeline.rb

@@ -64,7 +64,7 @@ module Textus
 
       # rubocop:disable Metrics/ParameterLists
       def self.run(mentry:, manifest:, reader:, lister:, transform_resolver:, template_loader:,
-                   transform_context: nil, inject_intro: nil)
+                   transform_context: nil, inject_boot: nil)
         # 1. Load sources + project + reduce
         data =
           if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
@@ -78,7 +78,7 @@ module Textus
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end
-        data = data.merge("intro" => inject_intro.call) if mentry.inject_intro && inject_intro
+        data = data.merge("boot" => inject_boot.call) if mentry.inject_boot && inject_boot
 
         # 2. Render
         klass = renderers[mentry.format] or