textus 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c72c516279aeb0df734da1a72dd89fd033ebbed2e891444b71015e04fab73e75
-  data.tar.gz: a1075b8990c6c1749eb03f5042c1e5bd590456307cf9b3e1a9de9c33dcc0a862
+  metadata.gz: 997772ea1cfaafc9f28bd57eda51cde19911ca527893c658aa6edb1329b1e2e6
+  data.tar.gz: a134c101fedfb2cd84c6cc21ab0522597ee1252cdaeaa84bc1b25bf977676538
 SHA512:
-  metadata.gz: 2218efa63e1ae6f246af3341bbb27e713a71a381a4aa84d15d46e687b8585c3bb5f992d75456c6112c960fec8a286c3cb7e6e672af04db0d2657811b45627ffb
-  data.tar.gz: 98ec77bf76fe14c850470e9dee3aebe55bba44ae6d4aa6303951eab2d697f2eed4d8d2d44278615e7e80873704d41dcd46109f244414ca2d16c7a4c4a7c12e2a
+  metadata.gz: 666ac21f47159341408b2399f9051d0dad0fab406d08f73a83aa468ea245aa211f16b9749ccf80668dbdd304c5125fbd87644c7e16301c890538749c4a1c0b5e
+  data.tar.gz: f15b77854967509b1c4918dd8452557949f5f42ce6e1ebcd928b3225596d36dff043bf47eca632c8f46b8ba29873cd26792a09109430903402a6b52e3ac51d66

data/CHANGELOG.md

@@ -5,11 +5,89 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 The **gem version** (`0.x.y`) is distinct from the **protocol version**
-(currently `textus/1`, embedded in every envelope as `protocol`). The protocol
+(currently `textus/2`, embedded in every envelope as `protocol`). The protocol
 is additive within a major; a new major would change the wire string.
 
 ## [Unreleased]
 
+## 0.5.0 — Wire protocol `textus/2`; CLI restructure; Store split (breaking)
+
+This release reshapes the public surface ahead of 1.0. The wire protocol bumps to `textus/2`; the CLI grows nested subcommand groups; `Store` is decomposed into a thin facade plus four focused helpers; the audit log finally matches its documented NDJSON shape; and a pile of pre-0.4 cruft gets cut.
+
+### Wire protocol — `textus/1` → `textus/2`
+
+- **Breaking:** every envelope now carries `"_meta"` instead of `"frontmatter"`. For json/yaml entries, envelope `content` no longer carries a duplicate `_meta` — the metadata lives only at the envelope's top level.
+- **Breaking:** `Manifest.load` refuses `textus/1` manifests with a pointer at the new migration command. On-disk file shapes are unchanged — only the manifest version string changes.
+- **New:** `textus migrate v2` flips `version: textus/1` to `version: textus/2` in `.textus/manifest.yaml`. One command, no file edits.
+- **Internal cleanup:** `Store#extract_uid`, `enforce_name_match!`, `serialize_for_put`, `validate_all`, and `build_envelope` no longer format-switch — metadata access is uniform. Role-authority validation now works for json/yaml entries (was markdown-only).
+- **API:** `Store#put` keyword renamed from `frontmatter:` to `meta:`. Action callbacks return `_meta:` (formerly `frontmatter:`).
+
+### CLI — nested subcommand groups
+
+- **New:** `textus key {mv, uid, migrate}`, `textus schema {show, init, diff, migrate}`, `textus extension {list, run}`. Discoverable, groupable, scales.
+- **Deprecated (removed in 0.6):** the flat verbs `mv`, `uid`, `migrate-keys`, `schema-init`, `schema-diff`, `schema-migrate`, `extensions`, `action` still work but emit a stderr deprecation warning. `textus schema KEY` (positional dotted-key form) keeps working via a back-compat fallback in `SchemaGroup`.
+- **New:** `textus list`, `textus get`, etc. default to JSON output. `--format=json` is still accepted; non-json values still raise.
+- **CLI refactor:** `lib/textus/cli.rb` shrank from 434 LOC to ~100 LOC. Every verb is now a small command-object file under `lib/textus/cli/`. Dispatch is a frozen `VERBS` hash.
+
+### Audit log — true NDJSON
+
+- **Breaking:** `.textus/audit.log` rows are now one JSON object per line (`{"ts":..., "role":..., "verb":..., "key":..., "etag_before":..., "etag_after":...}`). Missing etags are `null`, not the string `"NULL"`.
+- **Structural shape:** `from_key`, `to_key`, `uid` (mv rows) live at the top level; arbitrary contextual data goes into an `extras` sub-object that is omitted when empty.
+- **Back-compat:** legacy TSV rows still parse during 0.5 — `AuditLog#last_writer_for` and `Doctor#check_audit_log` accept both formats. Legacy support removed in 0.6.
+
+### Doctor
+
+- **New:** `textus doctor --check=schema_violations[,name,…]` runs only the named built-in checks. The 9 built-ins are `manifest_files`, `schemas`, `templates`, `extensions`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`. Extension checks always run.
+- **Breaking:** the standalone `textus validate-all` verb is gone. Use `textus doctor --check=schema_violations` instead. The internal `Store#validate_all` Ruby method is unchanged.
+
+### Manifest / store cleanup
+
+- **Breaking:** `LEGACY_ZONES` fallback removed. Manifests must declare a `zones:` block explicitly (init scaffold does this).
+- **Breaking:** legacy syntax errors removed for `source.parse` / `source.from` / `source.fetcher` / top-level `hooks:`. Those names were rejected with helpful errors in 0.4; in 0.5 they get the generic "unknown key" error from YAML parsing.
+- **Internal:** `ManifestEntry` moved to its own file (`lib/textus/manifest_entry.rb`).
+
+### Store split
+
+- **Internal:** `lib/textus/store.rb` shrank from 617 LOC to ~312 LOC. Four focused helpers live under `lib/textus/store/`:
+  - `events.rb` (31 LOC) — `fire_event` hook plumbing
+  - `validator.rb` (53 LOC) — `validate_all` body
+  - `staleness.rb` (142 LOC) — `stale` body (was 5 rubocop disables)
+  - `mover.rb` (118 LOC) — `mv` body
+- No public-API change. `Store` facade delegates to each helper one-line.
+
+### Migration cheat-sheet
+
+```sh
+# 1. Upgrade the gem
+gem update textus           # ≥ 0.5.0
+
+# 2. Upgrade the store
+cd /path/to/your/store
+textus migrate v2           # flips manifest version
+
+# 3. Anything else?
+#    - Audit log: existing TSV rows still readable; new rows are NDJSON.
+#    - CLI scripts: replace `textus mv ...` with `textus key mv ...`
+#      (and 7 similar aliases). Old forms work through 0.5 with a stderr warning.
+#    - Ruby callers of Store#put: pass `meta:` instead of `frontmatter:`.
+#    - Anything reading envelope["frontmatter"]: read envelope["_meta"] instead.
+```
+
+## 0.4.0 — Extension API redesign (breaking)
+
+- **Breaking:** `Textus.fetcher` removed. Use `Textus.action` instead. The block signature changes from `|config:, store:|` to `|config:, store:, args:|`.
+- **Breaking:** Manifest field `source.fetcher` renamed to `source.action`. Legacy field is rejected with a migration error.
+- **Breaking:** CLI flag `textus put --fetcher=NAME` renamed to `textus put --action=NAME`.
+- **Breaking:** `BuiltinFetchers` module renamed to `BuiltinActions`.
+- **Breaking:** Synthesized frontmatter key `fetched_with` renamed to `actioned_with` on `put --action`.
+- **New:** `Textus.action` works in three invocation modes — intake refresh, the new `textus action NAME` verb, and `put --action`. See SPEC §5.11.
+- **New:** `Textus.doctor_check(:name) { |store:| ... }` primitive; contributed checks merge into the doctor report.
+- **New:** `textus action NAME [--key=val ...] [--as=ROLE]` CLI verb for invoking actions in verb mode.
+- **New:** `StoreView` gains a writable mode (`writable: true, as: ROLE`); intake and verb-mode actions receive a writable view bound to the calling role.
+- **New:** `extensions list` enumerates actions and doctor_checks.
+
+Migration: in every `.textus/extensions/*.rb`, rename `Textus.fetcher(:x)` to `Textus.action(:x)` and add `args:` to the block signature. In every manifest, rename `source.fetcher:` to `source.action:`. In CI/scripts using `textus put --fetcher=`, switch to `--action=`.
+
 ## [0.3.0] — 2026-05-20 — Configurable store root
 
 ### Added

data/README.md

@@ -45,12 +45,12 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   audit.log           # append-only NDJSON, every write
   schemas/            # YAML field shapes per entry family
   templates/          # mustache templates for derived entries
-  extensions/         # one .rb per fetcher / reducer / hook
+  extensions/         # one .rb per action / reducer / hook / doctor_check
   sentinels/          # publish bookkeeping
   zones/
     canon/            # human-only — identity, voice, decisions
     working/          # human / ai / script — day-to-day catalog
-    intake/           # script — declared external inputs (fetchers)
+    intake/           # script — declared external inputs (actions)
     pending/          # ai + human — proposals awaiting accept
     derived/          # build only — computed outputs
 ```
@@ -67,14 +67,14 @@ echo '{"frontmatter":{"name":"bob","org":"acme"},"body":"hi\n"}' \
 textus stale --zone=derived --format=json
 ```
 
-For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake fetcher — see [`examples/claude-plugin/`](examples/claude-plugin/).
+For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
 ## What 0.2 ships
 
 - **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/derived/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`, `reducer`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
-- **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus 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 migrate-keys --dry-run|--write` rewrites existing stores with illegal segments deterministically.
+- **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
+- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key migrate --dry-run|--write` rewrites existing stores with illegal segments deterministically.
 - **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded extensions, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
 - **`textus doctor`.** Health check across 8 categories: missing schemas/templates, broken extensions, illegal nested keys, sentinel drift, audit log readability. 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.
@@ -93,21 +93,22 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | `list [--prefix=K] [--zone=Z]` | Enumerate keys |
 | `where K` | Resolve a key to its filesystem path |
 | `get K` | Full envelope (frontmatter, body, uid, etag, format) |
-| `schema K` | Schema bound to an entry |
+| `schema show K` | Schema bound to an entry |
 | `stale [--prefix=K] [--zone=Z]` | List stale derived/intake entries |
 | `deps K` / `rdeps K` | Forward / reverse projection dependencies |
 | `published` | List `publish_to:` targets and their backing keys |
-| `validate-all` | Validate every entry against its schema |
-| `extensions list [--kind=K]` | Registered fetchers, reducers, declared hooks |
+| `doctor --check=schema_violations` | Validate every entry against its schema |
+| `extension list [--kind=K]` | Registered actions, reducers, hooks, doctor_checks |
 
 **Write:**
 
 | Verb | Role |
 |---|---|
-| `put K --stdin --as=R [--fetcher=NAME]` | per zone |
+| `put K --stdin --as=R [--action=NAME]` | per zone |
+| `extension run NAME [--key=val] [--as=R]` | per zone written (invoke a registered action) |
 | `delete K --if-etag=E --as=R` | per zone |
 | `refresh K --as=script` | per zone (typically `script`) |
-| `mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
+| `key mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
 | `build [--prefix=K] [--dry-run]` | `build` |
 | `accept K --as=human` | `human` only |
 
@@ -116,16 +117,18 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | Verb | Purpose |
 |---|---|
 | `doctor` | 8 health checks; `ok: true` when clean |
-| `migrate-keys [--dry-run]` | Rename files whose basenames violate the strict key grammar |
+| `key migrate [--dry-run]` | Rename files whose basenames violate the strict key grammar |
 
 **Scaffolding (human-only):**
 
 | Verb | Purpose |
 |---|---|
 | `init` | Scaffold a fresh `.textus/` |
-| `schema-init NAME` | Stub a schema |
-| `schema-diff NAME` | Compare a schema against entries that claim it |
-| `schema-migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
+| `schema init NAME` | Stub a schema |
+| `schema diff NAME` | Compare a schema against entries that claim it |
+| `schema migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
+
+**Deprecated (removed in 0.6):** `mv`, `uid`, `migrate-keys`, `schema-init`, `schema-diff`, `schema-migrate`, `extensions`, `action`.
 
 ## Zones and roles
 
@@ -133,7 +136,7 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 |---|---|---|
 | `canon` | `[human]` | Identity, voice, decisions — slow-changing |
 | `working` | `[human, ai, script]` | Active project state |
-| `intake` | `[script]` | Declared external inputs (fetchers) |
+| `intake` | `[script]` | Declared external inputs (actions) |
 | `pending` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
 | `derived` | `[build]` | Computed outputs from `textus build` |
 
@@ -147,17 +150,18 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 ## Extensions
 
-Three DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
+Four DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
 
-- **`Textus.fetcher(:name) do |config:, store:|`** — pulls data into an intake entry. Returns `{frontmatter:, body:}`, `{content:}` (for json/yaml entries), or `{body:}` (raw). The store normalizes all three shapes. Configured via `source.fetcher` in the manifest. Five built-ins ship: `json`, `csv`, `markdown-links`, `ical-events`, `rss`.
+- **`Textus.action(:name) do |config:, store:, args:|`** — runs in three invocation modes (intake refresh, `textus action` verb, `put --action`). Returns `{frontmatter:, body:}`, `{content:}`, or `{body:}` when its return is consumed (intake and put-fetch); writes via `store.put` for side-effectful work (verb mode). The store normalizes all three return shapes. Configured via `source.action` in the manifest for intake. Five built-ins ship: `json`, `csv`, `markdown-links`, `ical-events`, `rss`.
 - **`Textus.reducer(:name) do |rows:, config:|`** — shapes rows in a derived projection. Pure function. Configured via `projection.reducer`. May return an Array (templated builds) or a Hash (templateless json/yaml).
 - **`Textus.hook(:event, :name) do |kwargs|`** — fires on `:put`, `:delete`, `:refresh`, `:build`, or `:accept`. In-process; 2 s timeout per hook; failures land in the audit log as `event_error` rows.
+- **`Textus.doctor_check(:name) do |store:|`** — contributes whole-tree validators to `textus doctor`. Returns an array of issue hashes `{code, level, subject, message, fix}` that merge into the doctor report. Timeouts and exceptions surface as `doctor_check.*` issues; they do not abort the doctor run.
 
 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 and §5.11.
 
 ## 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 fetchers, in-process reducers and hooks, the AI-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 reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests
 

data/SPEC.md

@@ -46,7 +46,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 - Not a sync protocol. Single-writer per file, ETag-checked.
 - Not a transport. Spawn the CLI or wrap it in MCP/HTTP downstream.
 - Not a UI. Filesystem + CLI. Viewers ship elsewhere.
-- Not a fetcher. textus declares sources; external runners fetch them.
+- Not a fetcher. textus declares sources; external runners invoke actions to materialize them.
 - Not an executor. textus computes pure projections but never spawns shell commands.
 
 ## 3. Storage layout
@@ -250,38 +250,38 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 
 **Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
 
-### 5.4 Intake (declared, refreshed via registered fetcher)
+### 5.4 Intake (declared, refreshed via registered action)
 
-Intake entries declare an external source by naming a **fetcher** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: a fetcher only runs when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
+Intake entries declare an external source by naming an **action** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an action only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
 
 ```yaml
 - key: intake.calendar.events
   zone: intake
   source:
-    fetcher: ical-events
+    action: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
     ttl: 6h
 ```
 
-`fetcher` names a registered fetcher; `config` is an opaque hash handed to the fetcher; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from` and `source.parse` with a clear usage error.
+`action` names a registered action; `config` is an opaque hash handed to the action; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, and `source.fetcher` with a clear usage error.
 
-**Fetcher contract.** A fetcher is registered via `Textus.fetcher(:name) do |config:, store:| ... end` and MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
+**Action contract (intake mode).** An action is registered via `Textus.action(:name) do |config:, store:, args:| ... end`. In intake mode the action MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
 
-- `{ frontmatter:, body: }` — markdown-friendly (current shape).
+- `{ frontmatter:, body: }` — markdown-friendly.
 - `{ content: }` — for `format: json|yaml` entries; the parsed object becomes the entry's content.
 - `{ body: }` — raw bytes for `text` or for any format that prefers verbatim writes; the store re-parses and validates per `format:`.
 
-The `store:` argument is a read-only `Textus::StoreView` (§5.11). Every fetcher call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
+The `store:` argument is a writable `Textus::StoreView` (§5.11) bound to the calling role; the `args:` argument is `{}` in intake mode (it carries CLI flags in verb mode — §5.11). Every action call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
 
-**Built-in fetchers.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer fetcher) is responsible for supplying bytes.
+**Built-in actions.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer action) is responsible for supplying bytes.
 
 **Refresh paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.fetcher`, invokes it with `(config:, store:)`, and writes the result under role `script`.
+1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.action`, invokes it with `(config:, store:, args: {})`, and writes the result under role `script`.
 2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`.
 
-Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied fetchers live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
+Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied actions live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
 
 ### 5.5 Pending / accept workflow
 
@@ -306,15 +306,19 @@ Proposed body content.
 
 ### 5.6 Audit log
 
-Every successful write appends one line to an append-only TSV file at `.textus/audit.log`. The file is opened with `flock(LOCK_EX)` for the duration of each append so concurrent writers serialize cleanly.
+Every successful write appends one compact JSON object (NDJSON) to `.textus/audit.log`. The file is opened with `flock(LOCK_EX)` for the duration of each append so concurrent writers serialize cleanly.
 
-Schema (tab-separated, one record per line):
+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>}
 ```
-<iso8601-utc>\t<role>\t<verb>\t<key>\t<etag-before-or-NULL>\t<etag-after-or-NULL>
-```
 
-`<iso8601-utc>` is the wall-clock timestamp in UTC with second (or finer) precision. `<role>` is the resolved role for the invocation. `<verb>` is the CLI verb (`put`, `delete`, `accept`, `compute`, `migrate-keys`, `mv`, ...). `<key>` is the affected entry key. For `mv`, `<key>` is the **new** key, and an extras JSON column carries `from_key`, `to_key`, `from_path`, `to_path`, and `uid`. `<etag-before>` and `<etag-after>` are the entry etags before and after the write, or the literal string `NULL` when not applicable (e.g. create has no before-etag, delete has no after-etag). `migrate-keys --write` emits one line per renamed file using the new key as `<key>` and the file's pre- and post-rename etags.
+`ts` is the wall-clock timestamp in UTC with second precision. `role` is the resolved role for the invocation. `verb` is the CLI verb (`put`, `delete`, `accept`, `compute`, `migrate-keys`, `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). `migrate-keys --write` emits one line per renamed file using the new key as `key` and the file's pre- and post-rename etags.
+
+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.
+
+**Backward compatibility (v0.5):** files written by v0.4 and earlier contain TSV rows. Readers MUST accept mixed-format files: lines starting with `{` are parsed as JSON; other lines are treated as legacy TSV (`ts\trole\tverb\tkey\tetag_before\tetag_after[\tjson_extras]`). TSV write support is removed in v0.6.
 
 ### 5.7 Security bounds
 
@@ -355,7 +359,7 @@ evolution:
 
 **Backwards compat:** v1.0 schemas (no `fields:`, no `evolution:`) continue to parse and behave identically. `schema.maintained_by(field)` returns `nil` for every field; `schema.evolution` returns `{}`.
 
-**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over AI/script-managed data — humans curating canon over AI-written embeddings is a feature, not a bug. All other role mismatches are reported by `validate-all` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
+**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over AI/script-managed data — humans curating canon over AI-written embeddings is a feature, not a bug. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
 
 ### 5.9 Reducers (v1.2)
 
@@ -403,7 +407,7 @@ Lifecycle events fire in-process. Subscribers register via `Textus.hook(:event,
 
 `:refresh` with `change: :unchanged` does NOT fire — only `:created` and `:updated` are emitted. The `store:` kwarg is always a `Textus::StoreView` (§5.11).
 
-**Timeout and isolation.** Each hook runs under `Timeout.timeout(2)`. Hook errors and timeouts are recorded as `event_error` rows in `.textus/audit.log` (column 7, JSON-encoded extras with `event`, `hook`, `error`) but do NOT abort the triggering operation. The store write that fired the event is already committed by the time hooks run.
+**Timeout and isolation.** Each hook runs under `Timeout.timeout(2)`. Hook errors and timeouts are recorded as `event_error` rows in `.textus/audit.log` (NDJSON with an `extras` object carrying `event`, `hook`, `error`) but do NOT abort the triggering operation. The store write that fired the event is already committed by the time hooks run.
 
 **Manifest declarations.** A manifest entry MAY declare external-runner hooks under an `events:` block, keyed by event name:
 
@@ -419,29 +423,39 @@ Textus does NOT invoke these — they surface only through `textus extensions li
 
 **Removed.** The v1.1 `on_stale` event is removed in 0.2. Staleness is a poll, surfaced by `textus stale`. The `on_`-prefix convention from v1.1 is gone; events are bare symbols.
 
-### 5.11 Extension surface (v1.2)
+### 5.11 Extension surface (v1.3)
 
-Three DSL verbs cover all user-supplied code:
+Four DSL verbs cover all user-supplied code:
 
 ```
-Textus.fetcher(:name)       do |config:, store:|   ... end   # returns {frontmatter:, body:} | {content:} | {body:}
-Textus.reducer(:name)       do |rows:, config:|    ... end   # returns rows
-Textus.hook(:event, :name)  do |**kwargs|          ... end   # side effects; return ignored
+Textus.action(:name)         do |config:, store:, args:|  ... end   # intake mode: returns content; verb mode: writes via store.put
+Textus.reducer(:name)        do |rows:, config:|          ... end   # returns rows
+Textus.hook(:event, :name)   do |**kwargs|                ... end   # side effects; return ignored
+Textus.doctor_check(:name)   do |store:|                  ... end   # returns array of issue hashes
 ```
 
 Files in `.textus/extensions/*.rb` are loaded at `Store#initialize`, in lexical order, with the registry installed as the current registry for that store. Registries are per-Store: two Store instances in the same process do not share state.
 
-Failure modes:
+**Action invocation modes.**
+
+| Mode    | Invoked by                | `config:`              | `store:`               | `args:`              | Return                                  |
+|---------|---------------------------|------------------------|------------------------|----------------------|------------------------------------------|
+| intake  | `textus refresh KEY`      | manifest `source.config` | writable view (role from `--as`) | `{}`                | required; normalized into entry write    |
+| verb    | `textus action NAME ...`  | `{}`                   | writable view (role from `--as`) | parsed CLI kv hash   | ignored                                  |
+| put-fetch | `textus put K --action=N --stdin` | `{ "bytes" => stdin }` | read-only view         | `{}`                 | required; merged into the put payload    |
+
+**Failure modes:**
 
-| Surface  | Timeout    | Exception                                   | Bad return |
-|----------|------------|---------------------------------------------|------------|
-| fetcher  | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
-| reducer  | aborts op  | aborts op                                   | aborts op  |
-| hook     | logged     | logged (audit `event_error` row)            | n/a        |
+| Surface         | Timeout    | Exception                                   | Bad return |
+|-----------------|------------|---------------------------------------------|------------|
+| action          | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
+| reducer         | aborts op  | aborts op                                   | aborts op  |
+| hook            | logged     | logged (audit `event_error` row)            | n/a        |
+| doctor_check    | reported as `doctor_check.timeout` issue | reported as `doctor_check.failed` issue | reported as `doctor_check.bad_return` |
 
-Fetchers and reducers are pure transforms; return values flow into the store. Hooks are side effects; return values are discarded.
+Actions and reducers are pure transforms in modes where their return matters; their return values flow into the store. Hooks and doctor_checks shape side outputs (event chain, doctor report) — only doctor_check return values are merged.
 
-The `store:` argument is always a `Textus::StoreView` — a read-only proxy exposing `get`, `list`, `where`, `schema_envelope`, `deps`, `rdeps`, `published`, `stale`, `validate_all`. Write attempts raise `Textus::UsageError`.
+The `store:` argument is always a `Textus::StoreView`. In intake and verb modes it is writable and bound to the calling role; in put-fetch mode and inside doctor_checks it is read-only. Write attempts on a read-only view raise `Textus::UsageError`.
 
 ### 5.12 Storage formats (v1.2)
 
@@ -584,8 +598,8 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `stale [--prefix=K] [--strict]` | read | any |
 | `deps K` / `rdeps K` | read | any |
 | `published` | read | any |
-| `validate-all` | read | any |
-| `put K --stdin --as=R [--fetcher=NAME]` | write | per zone |
+| `doctor --check=schema_violations` | read | any |
+| `put K --stdin --as=R [--action=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh K --as=script` | write | per zone (typically `script`) |
 | `build [--prefix=K] [--dry-run]` | write | `build` (default) |
@@ -595,8 +609,8 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `migrate-keys [--dry-run\|--write]` | write (with `--write`) | `human` |
 | `mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `uid K` | read | any |
-| `extensions list [--kind=fetcher\|reducer\|hook]` | read | any |
-| `doctor [--format=json]` | read | any |
+| `extensions list [--kind=action\|reducer\|hook]` | read | any |
+| `doctor [--check=NAME[,NAME]] [--format=json]` | read | any |
 | `intro [--format=json]` | read | any |
 
 **`put` input** (read from stdin when `--stdin` is given):

data/docs/architecture.md

@@ -2,56 +2,91 @@
 
 How the reference Ruby implementation is organized. The wire protocol itself lives in [`../SPEC.md`](../SPEC.md); this document covers *how* the gem implements that spec.
 
-## Layering
+The codebase is a flat graph of small modules under one CLI dispatcher, not a strict pyramid. The clusters below describe what each module exists for and which other modules it talks to.
+
+## At a glance
 
 ```
-┌──────────────────────────────────────────────┐
-│ exe/textus                                   │  thin shim: load lib, call CLI.run
-├──────────────────────────────────────────────┤
-│ Textus::CLI                                  │  argv parsing, JSON I/O, exit codes
-├──────────────────────────────────────────────┤
-│ Textus::Store                                │  verb implementations (get/put/list/…)
-├───────────────┬───────────────┬──────────────┤
-│ Manifest      │ Schema        │ Entry        │  parse/resolve, validate, (de)serialize
-├───────────────┴───────────────┴──────────────┤
-│ Etag · Errors · version                      │  primitives
-└──────────────────────────────────────────────┘
+exe/textus  →  Textus::CLI  ──┬──►  Store          (verb impl: get/put/list/stale/refresh/accept/…)
+                              ├──►  Builder        (build verb)
+                              ├──►  Refresh        (refresh verb)
+                              ├──►  Doctor         (doctor verb)
+                              ├──►  Init           (init verb)
+                              ├──►  Intro          (intro verb)
+                              ├──►  MigrateKeys    (migrate-keys, mv verbs)
+                              ├──►  SchemaTools    (schema-init/diff/migrate verbs)
+                              ├──►  StoreView      (read-only projection over Store)
+                              └──►  Role           (role gate)
 ```
 
-Each layer talks only to the layer below it. `Store` is the only class that touches the filesystem for read/write; `Manifest` and `Schema` read at load time and are otherwise pure.
+CLI is the single entry point. It parses argv and dispatches each verb to whichever module owns that capability — there is no single mediator below CLI.
+
+## Module clusters
+
+### 1. Request path — core read/write verbs
 
-## Key resolution
+`Store` (617 LOC) owns the `get`, `put`, `list`, `delete`, `stale`, and proposal-acceptance verbs. It is the largest module and the only one that touches the working-store filesystem for primary read/write. It uses:
 
-`Manifest#resolve(key)` does **longest-prefix match** against `entries[].key`. The matched entry's `path:` is the base; if `nested: true`, remaining dotted segments become `/`-joined subdirectories under that path and a `.md` is appended.
+- **`Manifest`** — parses `.textus/manifest.yaml`; resolves a dotted key to a path via longest-prefix match. `nested: true` entries treat unmatched suffix segments as `/`-joined subdirs, with `.md` appended. Resolution is path-only; existence is the verb's concern.
+- **`Schema`** — loads YAML schema files; validates frontmatter shape and surfaces unknown-key warnings (the §6 forward-compat rule).
+- **`Entry`** + format adapters (`entry/markdown.rb`, `entry/text.rb`, `entry/json.rb`, `entry/yaml.rb`) — splits raw bytes on `---\n`, feeds the YAML chunk to `YAML.safe_load` (no aliases, restricted classes). The frontmatter `name:` field is enforced against the file basename inside `Store` (on read and on write) — mismatch raises `bad_frontmatter`.
+- **`Etag`** — `sha256:<hex>` over raw file bytes. `put` accepts optional `if_etag:`; mismatch raises `etag_mismatch`. No locking, no temp-file-and-rename — v1 leaves stronger guarantees to v1.x.
+- **`Role`** — agent-vs-human gate. `Store#put` checks `ManifestEntry#agent_writable?` (true only for `state`) before doing anything else; otherwise raises `write_forbidden`.
+- **`AuditLog`** — append-only NDJSON; every successful write emits one line.
+- **`Proposal`** — `accept` verb flow for promoting a pending entry into its target zone.
+- **`Dependencies`** — `deps`/`rdeps`/`published` verb backing; walks manifest declarations.
 
-Resolution is **path-only** — it does not check whether the file exists. Existence is the verb's concern: `get` raises `unknown_key` when the file is missing; `put` happily creates new files in nested entries.
+### 2. Build / publish pipeline
 
-## Frontmatter parsing
+Separate from the request path. Owns derived-entry materialization and byte-copy publish.
+
+```
+Builder ──► Projection ──► Mustache ──► Entry  ──► Publisher ──► (sentinel)
+```
 
-`Entry.parse` splits raw bytes on `---\n` boundaries and feeds the YAML chunk to `YAML.safe_load` (no aliases, restricted classes). Unknown top-level frontmatter keys are not rejected here — they are surfaced as warnings by `Schema#validate!`. This is the forward-compat rule from §6 of the spec.
+- **`Builder`** — iterates `zone: derived` entries, materializes each by running its declared template + projection, parses the rendered output back through `Entry`, and hands the bytes to `Publisher`.
+- **`Projection`** — collects rows from manifest-declared source keys, applies optional reducer, sorts and positions. Pure data shaping.
+- **`Mustache`** — minimal mustache renderer for templates in `.textus/templates/`.
+- **`Publisher`** — byte-copy from store path to external target path. Refuses to overwrite unmanaged targets; writes a sentinel in `.textus/sentinels/` to track managed targets.
 
-The frontmatter `name:` field is enforced against the file basename inside `Store` (both on read and on write) so a misnamed file or a mistyped `name:` in `put` payload fails fast with `bad_frontmatter`.
+### 3. Extension surface
 
-## Zone enforcement
+Declared in the manifest, loaded on demand, dispatched by `Store` and `Refresh`.
 
-Three zones (`fixed`, `state`, `derived`) declared per-entry in the manifest. `Store#put` checks `ManifestEntry#agent_writable?` (true only for `state`) before doing anything else and raises `write_forbidden` otherwise. Zone semantics live in the manifest, not directory names — a project can rename `state/` to whatever it wants.
+- **`Extensions`** — declarative manifest schema for action/reducer/hook/doctor_check extensions.
+- **`ExtensionRegistry`** — loads one `.rb` per extension from `.textus/extensions/`, registers callables under their declared names.
+- **`BuiltinActions`** — ships built-in actions (e.g. json, csv, ical-events, rss) available without user extensions.
+- **`Refresh`** — `refresh` verb: looks up the action for a key, invokes it, normalizes the result by declared format, writes through `Store` with an etag check.
 
-## ETag and concurrency
+### 4. Operational tooling
 
-`Etag.for_bytes` returns `sha256:<hex>` over the raw file bytes. `put` accepts an optional `if_etag:` — if provided and the on-disk file's etag differs, `etag_mismatch` is raised. No locking, no temp-file-and-rename — the v1 spec leaves stronger guarantees to v1.x (§14 open question).
+First-class CLI verbs that don't fit the read/write/build axes. Read-mostly; side modules off CLI.
 
-## Staleness (the dataflow oracle)
+- **`Doctor`** — `doctor` verb: validates manifest, schemas, extensions, and (via `MigrateKeys`) suggests key migrations. Talks to Manifest/Schema/Entry/ExtensionRegistry directly.
+- **`MigrateKeys`** — `migrate-keys` and `mv` verbs; computes renames against the manifest.
+- **`SchemaTools`** — `schema-init`, `schema-diff`, `schema-migrate` verbs.
+- **`Init`** — `init` verb: scaffolds `.textus/` with the five zone directories, baseline schemas, empty audit log, starter manifest.
+- **`Intro`** — `intro` verb: emits the human/agent-facing onboarding payload.
+- **`StoreView`** — read-only projection over `Store` for code that should not mutate.
+- **`KeyDistance`** — Levenshtein-ish suggestion for `did-you-mean` on unknown keys.
 
-`Store#stale` walks every `zone: derived` entry that declares a `generator:` block, reads its `generated.at` frontmatter timestamp, and compares against each `generator.sources` entry's current mtime. Returns the offenders **and their declared `command`**; it does **not** execute anything. This is the core "dataflow oracle, not executor" boundary from §5.1 of the spec.
+### 5. Primitives
 
-Sources are heuristically classified: a string matching the textus key grammar with no `/` is treated as a textus key (and enumerated via the manifest); anything else is treated as a repo-relative path.
+- **`Errors`** — `Textus::Error` subclasses, each carrying a stable `code`, a `details` hash, and an `exit_code`. `CLI` catches them at the top level and emits the §8 error envelope on stdout. In `--format=json` mode, errors are **never** written to stderr — agents read stdout.
+- **`version`** — gem semver string (independent of the wire protocol `textus/1`).
 
-## Errors → envelopes
+## Invariants
 
-All `Textus::Error` subclasses carry a stable error `code`, a `details` hash, and an `exit_code`. `CLI` catches them at the top level and emits the §8 error envelope on stdout; the exit code matches the §8 table. Errors are never written to stderr in `--format=json` mode — agents read stdout.
+- **CLI is the only entry point.** No public API surface guarantees outside the verbs CLI exposes.
+- **Manifest is pure.** Reads at load, no mutation.
+- **Store is the only module that writes to working-store entry files.** Init, MigrateKeys, Publisher, Builder, AuditLog write to **other** parts of `.textus/` (scaffolding, sentinels, audit log, derived targets) — they do not edit existing entry files behind Store's back.
+- **`name:` frontmatter matches file basename.** Enforced on read and write.
+- **Zone semantics live in the manifest, not in directory names.** A project may rename `state/` to anything; the manifest declares which zone each entry belongs to.
+- **`stale` does not execute anything.** It walks `zone: derived` entries with a `generator:` block, compares `generated.at` against source mtimes, and returns offenders **plus their declared `command`**. Build runners execute. This is the §5.1 "dataflow oracle, not executor" boundary.
 
 ## What this implementation deliberately leaves out
 
 - **No process spawning.** Even `stale` does not execute. Build runners do that.
 - **No transport.** No HTTP server, no socket, no MCP server in this gem. Those are downstream wrappers (see [`./conventions.md`](./conventions.md)).
 - **No indexes.** Listing walks the filesystem each time. Premature optimisation for v1.
+- **No locking.** Etag is advisory; concurrent writers can still race. Left to v1.x (§14 open question).

data/lib/textus/audit_log.rb

@@ -10,23 +10,58 @@ module Textus
     def last_writer_for(key)
       return nil unless File.exist?(@path)
 
-      File.foreach(@path).map { |l| l.chomp.split("\t") }
-                         .select { |row| row[3] == key && %w[put delete].include?(row[2]) }
-                         .last&.fetch(1)
+      last_role = nil
+      File.foreach(@path) do |line|
+        parsed = parse_row(line.chomp)
+        next unless parsed
+        next unless parsed["key"] == key
+        next unless %w[put delete].include?(parsed["verb"])
+
+        last_role = parsed["role"]
+      end
+      last_role
     end
 
     def append(role:, verb:, key:, etag_before:, etag_after:, extras: nil)
-      fields = [
-        Time.now.utc.iso8601, role, verb, key,
-        etag_before || "NULL",
-        etag_after  || "NULL"
-      ]
-      fields << JSON.generate(extras) if extras && !extras.empty?
-      line = fields.join("\t") + "\n"
+      row = {
+        "ts" => Time.now.utc.iso8601,
+        "role" => role,
+        "verb" => verb,
+        "key" => key,
+        "etag_before" => etag_before,
+        "etag_after" => etag_after,
+      }
+
+      if extras.is_a?(Hash) && !extras.empty?
+        extras = extras.dup
+        %w[from_key to_key uid].each do |k|
+          row[k] = extras.delete(k) if extras.key?(k)
+        end
+        row["extras"] = extras unless extras.empty?
+      end
+
       File.open(@path, File::WRONLY | File::APPEND | File::CREAT, 0o644) do |f|
         f.flock(File::LOCK_EX)
-        f.write(line)
+        f.write(JSON.generate(row) + "\n")
+      end
+    end
+
+    private
+
+    def parse_row(line)
+      return nil if line.empty?
+
+      if line.start_with?("{")
+        JSON.parse(line)
+      else
+        # Legacy TSV: ts, role, verb, key, etag_before, etag_after [, json_extras]
+        fields = line.split("\t")
+        return nil if fields.length < 4
+
+        { "ts" => fields[0], "role" => fields[1], "verb" => fields[2], "key" => fields[3] }
       end
+    rescue JSON::ParserError
+      nil
     end
   end
 end