textus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c2ce5525bbf9c05ebdb5eeaacde8e208253ee878d7d0722ff192435168f69f
-  data.tar.gz: c16cd5657396884c646331912d988838e0f8ed2002fc76d47cc54383dc434f19
+  metadata.gz: 997772ea1cfaafc9f28bd57eda51cde19911ca527893c658aa6edb1329b1e2e6
+  data.tar.gz: a134c101fedfb2cd84c6cc21ab0522597ee1252cdaeaa84bc1b25bf977676538
 SHA512:
-  metadata.gz: 7478459f9672474c32f37b59a7134309cf12f6a7455a808c24b6ac717820ff8c8aad5a5187a6dbe5e0c73f98c04296ce95eff2cac8ea75144f559df8cea3fe80
-  data.tar.gz: '08a29e9090f6558a010009e3562a7ec8d6ddf73454bb09b10b5aeaf3def24d9d11905078d62807b8e1f0936b00889a66df8c55d68b7dfc411addd90e60ae1a93'
+  metadata.gz: 666ac21f47159341408b2399f9051d0dad0fab406d08f73a83aa468ea245aa211f16b9749ccf80668dbdd304c5125fbd87644c7e16301c890538749c4a1c0b5e
+  data.tar.gz: f15b77854967509b1c4918dd8452557949f5f42ce6e1ebcd928b3225596d36dff043bf47eca632c8f46b8ba29873cd26792a09109430903402a6b52e3ac51d66

data/CHANGELOG.md

@@ -5,11 +5,74 @@ 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:|`.

data/README.md

@@ -73,8 +73,8 @@ 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/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,22 +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 actions, reducers, hooks, doctor_checks |
+| `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 [--action=NAME]` | per zone |
-| `action NAME [--key=val] [--as=R]` | per zone written (invoke a registered action) |
+| `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 |
 
@@ -117,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
 

data/SPEC.md

@@ -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:
 
@@ -594,7 +598,7 @@ 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 |
+| `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`) |
@@ -606,7 +610,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `uid K` | read | any |
 | `extensions list [--kind=action\|reducer\|hook]` | read | any |
-| `doctor [--format=json]` | 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

data/lib/textus/builder.rb

@@ -96,14 +96,14 @@ module Textus
           "from" => Array(mentry.projection&.fetch("select", nil)).compact,
         },
       }
-      Entry.for_format("markdown").serialize(frontmatter: frontmatter, body: body)
+      Entry.for_format("markdown").serialize(meta: frontmatter, body: body)
     end
 
     # Text: projection -> template -> text.serialize(body). No frontmatter, no _meta.
     def build_text(mentry, data)
       data = data.merge("intro" => Intro.run(@store)) if mentry.inject_intro
       body = render_template!(mentry, data)
-      Entry.for_format("text").serialize(frontmatter: {}, body: body)
+      Entry.for_format("text").serialize(meta: {}, body: body)
     end
 
     # JSON / YAML pipeline. Templateless = default; template = escape hatch.
@@ -127,7 +127,7 @@ module Textus
         end
 
       final = inject_meta(content, mentry)
-      strategy.serialize(frontmatter: {}, body: "", content: final)
+      strategy.serialize(meta: {}, body: "", content: final)
     end
 
     def render_template!(mentry, data)

data/lib/textus/builtin_actions.rb

@@ -11,14 +11,14 @@ module Textus
         _ = store
         _ = args
         data = JSON.parse(config["bytes"].to_s)
-        { frontmatter: {}, body: YAML.dump(data) }
+        { _meta: {}, body: YAML.dump(data) }
       end
 
       Textus.action(:csv) do |config:, store:, args:|
         _ = store
         _ = args
         rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
-        { frontmatter: {}, body: YAML.dump(rows) }
+        { _meta: {}, body: YAML.dump(rows) }
       end
 
       Textus.action(:"markdown-links") do |config:, store:, args:|
@@ -27,7 +27,7 @@ module Textus
         links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
           { "text" => text, "href" => href }
         end
-        { frontmatter: {}, body: YAML.dump(links) }
+        { _meta: {}, body: YAML.dump(links) }
       end
 
       Textus.action(:"ical-events") do |config:, store:, args:|
@@ -46,7 +46,7 @@ module Textus
             current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
           end
         end
-        { frontmatter: {}, body: YAML.dump(events) }
+        { _meta: {}, body: YAML.dump(events) }
       end
 
       Textus.action(:rss) do |config:, store:, args:|
@@ -60,7 +60,7 @@ module Textus
             "pubDate" => item.elements["pubDate"]&.text,
           }
         end
-        { frontmatter: {}, body: YAML.dump(items) }
+        { _meta: {}, body: YAML.dump(items) }
       end
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength

data/lib/textus/cli/accept.rb

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    class Accept < Verb
+      option :as_flag, "--as=ROLE"
+
+      def call(store)
+        key = positional.shift or raise UsageError.new("accept requires a key")
+        role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+        emit(store.accept(key, as: role))
+      end
+    end
+  end
+end

data/lib/textus/cli/action.rb

@@ -0,0 +1,51 @@
+module Textus
+  class CLI
+    class Action < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "action"
+      def self.replacement_path = "extension run"
+
+      def parse(argv)
+        @raw_argv = argv
+      end
+
+      def call(store)
+        name = @raw_argv.shift
+        raise UsageError.new("action requires a name") if name.nil?
+
+        as_flag = nil
+        args = {}
+        @raw_argv.each do |tok|
+          case tok
+          when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
+          when /\A--format=/           then next
+          when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
+          else
+            raise UsageError.new("unknown arg to 'action #{name}': #{tok}")
+          end
+        end
+
+        role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+        callable = store.registry.action(name)
+        view = StoreView.new(store, writable: true, as: role)
+
+        begin
+          Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+            callable.call(config: {}, store: view, args: args)
+          end
+        rescue Timeout::Error
+          raise UsageError.new(
+            "action '#{name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
+          )
+        rescue Textus::Error
+          raise
+        rescue StandardError => e
+          raise UsageError.new("action '#{name}' raised: #{e.class}: #{e.message}")
+        end
+
+        emit({ "action" => name, "ok" => true })
+      end
+    end
+  end
+end

data/lib/textus/cli/build.rb

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Build < Verb
+      option :prefix, "--prefix=K"
+
+      def call(store)
+        emit(Textus::Builder.new(store).build(prefix: prefix))
+      end
+    end
+  end
+end

data/lib/textus/cli/delete.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Delete < Verb
+      option :as_flag, "--as=ROLE"
+      option :if_etag, "--if-etag=E"
+
+      def call(store)
+        key = positional.shift or raise UsageError.new("delete requires a key")
+        role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+        emit(store.delete(key, if_etag: if_etag, as: role))
+      end
+    end
+  end
+end

data/lib/textus/cli/deprecated_alias.rb

@@ -0,0 +1,31 @@
+module Textus
+  class CLI
+    module DeprecatedAliasMixin
+      def self.prepended(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def deprecated_name
+          raise NotImplementedError.new("#{self}.deprecated_name must be defined")
+        end
+
+        def replacement_path
+          raise NotImplementedError.new("#{self}.replacement_path must be defined")
+        end
+      end
+
+      attr_writer :deprecated_alias
+
+      def call(store)
+        if @deprecated_alias
+          @stderr.puts(
+            "textus: '#{self.class.deprecated_name}' is deprecated; " \
+            "use 'textus #{self.class.replacement_path}' instead. Removed in 0.6.",
+          )
+        end
+        super
+      end
+    end
+  end
+end

data/lib/textus/cli/deps.rb

@@ -0,0 +1,10 @@
+module Textus
+  class CLI
+    class Deps < Verb
+      def call(store)
+        key = positional.shift or raise UsageError.new("deps requires a key")
+        emit({ "key" => key, "deps" => store.deps(key) })
+      end
+    end
+  end
+end