textus 0.30.0 → 0.35.1

data/SPEC.md

@@ -8,11 +8,75 @@
 
 ---
 
+## Table of contents
+
+- [Conventions](#conventions)
+- [1. What textus is](#1-what-textus-is)
+  - [1.1 Vocabulary axes](#11-vocabulary-axes)
+  - [1.2 The five layers](#12-the-five-layers)
+- [2. Goals and non-goals](#2-goals-and-non-goals)
+- [3. Storage layout](#3-storage-layout)
+  - [3.1 Store location precedence](#31-store-location-precedence)
+- [4. Manifest](#4-manifest)
+- [5. Zones and capability-based write gates](#5-zones-and-capability-based-write-gates)
+  - [5.1 Role resolution](#51-role-resolution)
+    - [5.1.1 Capabilities](#511-capabilities)
+  - [5.2 Compute layer (derived entries)](#52-compute-layer-derived-entries)
+    - [5.2.1 Projection compute](#521-projection-compute-kind-projection)
+    - [5.2.2 External compute](#522-external-compute-kind-external)
+  - [5.3 Publish layer](#53-publish-layer-publish_to)
+  - [5.4 Intake](#54-intake-declared-fetched-via-registered-intake-handler)
+  - [5.5 Pending / accept workflow](#55-pending--accept-workflow)
+  - [5.6 Audit log](#56-audit-log)
+  - [5.7 Security bounds](#57-security-bounds)
+  - [5.8 Schema evolution](#58-schema-evolution)
+  - [5.9 Row transforms](#59-row-transforms)
+  - [5.10 Hooks](#510-hooks)
+  - [5.11 Rules](#511-rules)
+  - [5.12 Storage formats](#512-storage-formats)
+- [6. Schemas](#6-schemas)
+- [7. Entry file format](#7-entry-file-format)
+- [8. Envelope (the wire format)](#8-envelope-the-wire-format)
+- [9. CLI surface](#9-cli-surface)
+- [10. ETag semantics](#10-etag-semantics)
+  - [10.1 Errors carry hints](#101-errors-carry-hints)
+  - [10.2 `textus doctor`](#102-textus-doctor)
+- [11. Versioning](#11-versioning)
+  - [11.1 Agent integration](#111-agent-integration)
+- [12. Conformance fixtures](#12-conformance-fixtures)
+- [13. Why not X?](#13-why-not-x)
+  - [13.1 Layered architecture (internal)](#131-layered-architecture-internal)
+- [14. Open questions (v3.x scope)](#14-open-questions-v3x-scope)
+- [15. Implementation checklist](#15-implementation-checklist)
+- [16. Migrating from textus/2](#16-migrating-from-textus2)
+  - [16.1 Breaking changes in 0.31.0 (capability-based roles)](#161-breaking-changes-in-0310-capability-based-roles)
+  - [16.2 Breaking changes in 0.33.0 (workspace/keep + Setup-1 scaffold)](#162-breaking-changes-in-0330-workspacekeep--setup-1-scaffold)
+  - [16.3 Breaking changes in 0.35.0 (proposal target-canon + `author_held`)](#163-breaking-changes-in-0350-proposal-target-canon--author_held)
+
+---
+
+## Conventions
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
+**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this
+document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
+and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174): with their normative
+meaning **only** when they appear in uppercase. The same words in lowercase
+carry their ordinary English sense and impose no requirement.
+
+Requirements are stated against any **conforming implementation** of the
+`textus/3` protocol. The Ruby gem `textus` is the reference implementation, but
+the contract is the protocol defined here — not the gem. Where this document and
+the implementation disagree, this document is the source of truth and the
+implementation is the bug.
+
+---
+
 ## 1. What textus is
 
-A storage convention and JSON wire protocol for humans, agents, and runners to read and write structured project memory **deterministically**. It provides addressable dotted keys, schema validation, role-based write gates, declarative compute, and copy-based publish targets.
+A storage convention and JSON wire protocol for humans, agents, and automation to read and write structured project memory **deterministically**. It provides addressable dotted keys, schema validation, capability-based write gates, declarative compute, and copy-based publish targets.
 
-The storage lives in a `.textus/` directory at the project root. Each entry is a Markdown file with YAML frontmatter. A manifest binds dotted keys to subtrees and declares which roles may write to each zone. Schemas (also YAML) define what frontmatter shape each entry must have. Derived entries are computed from other entries via pure projections and a vendored Mustache template engine, then optionally published to repo-relative paths as byte-for-byte file copies. The CLI surface (`textus get/put/list/where/schema/build/...` `--output=json`) returns a versioned envelope any caller can parse without knowing Markdown.
+The storage lives in a `.textus/` directory at the project root. Each entry is a Markdown file with YAML frontmatter. A manifest binds dotted keys to subtrees, declares the capabilities each role holds, and declares each zone's kind — write authority for a zone is derived from the role's capabilities and the zone's kind. Schemas (also YAML) define what frontmatter shape each entry must have. Derived entries are computed from other entries via pure projections and a vendored Mustache template engine, then optionally published to repo-relative paths as byte-for-byte file copies. The CLI surface (`textus get/put/list/where/schema/build/...` `--output=json`) returns a versioned envelope any caller can parse without knowing Markdown.
 
 You **shape your own memory structure** inside `.textus/`. The protocol manages how it's read, written, addressed, validated, gated, computed, and published. The contents are entirely yours.
 
@@ -20,10 +84,10 @@ You **shape your own memory structure** inside `.textus/`. The protocol manages
 
 textus/3 names its concepts along six axes. Reviewers who internalize these can map any part of the spec to the right category:
 
-- **Actor** — who is interacting: `human`, `agent`, `runner`, `builder`.
-- **Place** — where data lives: zones such as `identity`, `working`, `intake`, `review`, `output`.
+- **Actor** — who is interacting: roles such as `human`, `agent`, `automation`, each holding a set of capabilities (`propose`, `author`, `keep`, `fetch`, `build`).
+- **Place** — where data lives: zones such as `knowledge`, `notebook`, `feeds`, `proposals`, `artifacts`.
 - **Thing** — what is stored: entries, fields, keys.
-- **Operation** — how you act on things: RPC and CLI verbs (`get`, `put`, `refresh`, `build`, …).
+- **Operation** — how you act on things: RPC and CLI verbs (`get`, `put`, `fetch`, `build`, …).
 - **Event** — what gets fired after an operation: hook event names, split into RPC events (`:resolve_intake`, `:transform_rows`, `:validate`) and pub-sub events (`:entry_put`, `:build_completed`, …).
 - **Rule** — constraints declared in the top-level `rules:` array of the manifest.
 
@@ -34,7 +98,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 | Layer | Name | Responsibility |
 |---|---|---|
 | L1 | **Store** | Plain-file backend: `.textus/zones/<zone>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
-| L2 | **Sources** | Declared external inputs (the `intake` zone in the default scaffold; any zone writable by `runner`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external runners fetch and pipe results through `textus put`. |
+| L2 | **Sources** | Declared external inputs (the `feeds` zone in the default scaffold; any `quarantine` zone, writable by a role with `fetch`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external automation fetches and pipes results through `textus put`. |
 | L3 | **Compute** | Pure transforms from store entries to derived entries. Projections (select/pluck/sort/limit/format) plus a vendored Mustache template subset. No shell execution. |
 | L4 | **Publish** | Byte-for-byte file copy from derived entries to repo-relative paths declared via `publish_to:`. The in-store artifact is the consumer-shaped output; the published file is an identical copy. A sentinel under `.textus/sentinels/<target-rel-path>.textus-managed.json` records the source, sha256, and `mode: "copy"`. |
 | L5 | **Consumers** | Anything that reads the published files or calls the CLI — editors, LLM tools, MCP servers, CI jobs, dashboards. textus is agnostic about who consumes; the envelope is the contract. |
@@ -45,7 +109,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 - Stable wire format (`textus/3`) any language can speak.
 - Deterministic read/write of structured Markdown via a CLI returning JSON.
 - Schema-validated frontmatter using YAML schemas as data.
-- Role-based write gates (humans, agents, runners, builders get different permissions per zone).
+- Capability-based write gates (roles hold capabilities; write authority per zone is derived from the role's capabilities and the zone's kind).
 - Optimistic concurrency via ETags.
 - Pure declarative compute: derived entries computed from projections + Mustache, no shell-out.
 - Publish derived entries to well-known paths as body-only plain files.
@@ -57,7 +121,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 invoke actions to materialize them.
+- Not a fetcher. textus declares sources; external automation invokes actions to materialize them.
 - Not an executor. textus computes pure projections but never spawns shell commands.
 
 ## 3. Storage layout
@@ -66,23 +130,23 @@ The root is `.textus/` at the project working directory. A typical tree:
 
 ```
 .textus/
-  manifest.yaml          # internal: key → subtree mapping + zones declarations
+  manifest.yaml          # internal: key → subtree mapping + role/zone declarations
   audit.log              # internal, append-only NDJSON log of every successful write
   schemas/               # internal: YAML schema files
   templates/             # internal: Mustache templates referenced by derived entries
   hooks/                 # internal: one Ruby file per hook
   sentinels/             # internal: bookkeeping for byte-copied publish targets (see §5.3)
   zones/                 # ALL user content lives here
-    identity/            # zone: identity (human-only)
-    working/             # zone: working (human, agent, runner)
-    intake/              # zone: intake (runner — declared external inputs)
-    review/              # zone: review (agent/human — proposals awaiting accept)
-    output/              # zone: output (builder only — computed outputs)
+    knowledge/           # zone: knowledge (kind: canon — author-holders write; knowledge.identity.* is the identity convention)
+    notebook/            # zone: notebook (kind: workspace — keep-holders write; agent's own durable lane)
+    feeds/               # zone: feeds (kind: quarantine — fetch-holders write)
+    proposals/           # zone: proposals (kind: queue — propose-holders write)
+    artifacts/           # zone: artifacts (kind: derived — build-holders write)
 ```
 
 Textus internals (`manifest.yaml`, `audit.log`, `schemas/`, `templates/`, `hooks/`, `sentinels/`) live directly under `.textus/`. **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
 
-Zone directories under `zones/` are conventional; their write semantics are declared in the manifest, not the directory name.
+Zone directories under `zones/` are conventional; their write semantics are derived from the zone's declared `kind:` (and the capabilities roles hold), not the directory name.
 
 `.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `delete`, `accept`, and `build`. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
 
@@ -98,58 +162,60 @@ When (1) or (2) names a path that has no `manifest.yaml`, the CLI exits with `io
 
 ## 4. Manifest
 
-The manifest declares: (a) which zones exist and which roles may write to each, (b) the key-to-subtree mapping, (c) the schema applied to entries in each subtree, and (d) the owner string recorded in writes.
+The manifest declares: (a) which roles exist and the capabilities each holds, (b) which zones exist and each zone's `kind:`, (c) the key-to-subtree mapping, (d) the schema applied to entries in each subtree, and (e) the owner string recorded in writes. Write authority is **derived** — a role may write a zone iff it holds the capability the zone's kind requires (§5).
 
 ```yaml
 # .textus/manifest.yaml
 version: textus/3
 
+roles:
+  - { name: human,      can: [author, propose] }
+  - { name: agent,      can: [propose] }
+  - { name: automation, can: [fetch, build] }
+
 zones:
-  - name: identity
-    kind: origin
-    write_policy: [human]
-  - name: working
-    kind: origin
-    write_policy: [human, agent, runner]
-  - name: intake
+  - name: knowledge
+    kind: canon
+  - name: notebook
+    kind: workspace
+    owner: agent              # optional, informational — agent's own lane
+    desc: "agent's durable working memory; bytes climb to knowledge only via propose→accept"
+  - name: feeds
     kind: quarantine
-    write_policy: [runner]
-  - name: review
+  - name: proposals
     kind: queue
-    write_policy: [agent, human]
-  - name: output
+  - name: artifacts
     kind: derived
-    write_policy: [builder]
 
 entries:
-  - key: identity.self
-    path: identity/self.md
-    zone: identity
+  - key: knowledge.identity.self
+    path: knowledge/identity/self.md
+    zone: knowledge
     schema: identity
 
-  - key: working.network.org
-    path: working/network/org
-    zone: working
+  - key: knowledge.network.org
+    path: knowledge/network/org
+    zone: knowledge
     schema: person
     owner: textus:network
     nested: true
 
-  - key: output.catalogs.people
-    path: output/catalogs/people.md
-    zone: output
+  - key: artifacts.catalogs.people
+    path: artifacts/catalogs/people.md
+    zone: artifacts
     schema: null
     owner: textus:build
 
 rules:
-  - match: intake.**
-    refresh: { ttl: 6h, on_stale: warn }
+  - match: feeds.**
+    fetch: { ttl: 6h, on_stale: warn }
 
 audit:
   max_size: 10485760   # bytes before rotating (default: 10 485 760 = 10 MiB)
   keep: 5              # rotated files to retain (default: 5)
 ```
 
-Zone names are conventional — the manifest is the source of truth for write permissions; rename freely.
+Zone names are conventional — write authority comes from each zone's declared `kind:` crossed with the capabilities roles hold (§5); rename zones freely.
 
 **Key grammar:** dotted segments matching `/^[a-z0-9][a-z0-9-]*$/`. Segments are joined by `.`. A key has at most 8 segments; each segment is at most 64 characters. Segments MUST NOT contain dots, slashes, uppercase letters, or underscores. Example: `working.projects.acme.dashboard`. Enforcement points: manifest load (rejects illegal `key:` declarations and illegal nested file/directory names), `put` (rejects illegal keys before any write), `enumerate` (filters and warns on illegal filenames).
 
@@ -198,34 +264,49 @@ 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_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.
+**`inject_boot:`.** A derived entry with a `template:` MAY declare `inject_boot: true`. When `textus build` 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.
 
-## 5. Zones and role-based write gates
+## 5. Zones and capability-based write gates
 
-Each zone declares which **roles** may write to it via `write_policy:` in the manifest. An optional `read_policy:` (default `[all]`) gates reads. Writes are gated; reads are unrestricted by default.
+Write authority is **derived**, never declared per-zone. Each zone declares a `kind:`; each zone-kind requires one capability to write to it. A role may write a zone iff its capability set (`role.can`) contains the verb that zone-kind requires. textus gates **writes, not reads**: reads are unrestricted at the protocol layer (the `.textus/` files are on disk). Per-role read-scoping, if needed, is an agent-surface projection, not a manifest field.
+
+The kind→verb mapping is closed:
+
+| Zone `kind` | Required capability | Meaning |
+|---|---|---|
+| `canon` | `author` | Authored truth — only the trust anchor writes directly. |
+| `workspace` | `keep` | Agent's own durable lane — bytes never auto-promote; climb to `canon` only via propose→accept. |
+| `quarantine` | `fetch` | External bytes pending validation. |
+| `queue` | `propose` | Proposals awaiting promotion. |
+| `derived` | `build` | Computed from other zones. |
 
-| Zone | `kind` | `write_policy` | Use case |
-|---|---|---|---|
-| `identity` | `origin` | `[human]` | Identity, voice, immutable principles — things only a human edits. |
-| `working` | `origin` | `[human, agent, runner]` | Active project state: notes, decisions, network — what humans and agents update day-to-day. |
-| `intake` | `quarantine` | `[runner]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or agents directly. |
-| `review` | `queue` | `[agent, human]` | Agent-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. |
-| `output` | `derived` | `[builder]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. |
+`owner:` on a zone is OPTIONAL, INFORMATIONAL metadata (not enforced in 0.33.0 — owner-scoped enforcement is deferred). `desc:` on a zone is optional; the value surfaces as the `purpose` field in `textus boot` zone rows.
 
-A write is gated by the caller's **role**, supplied via `--as=<role>`. If the role is not in the target zone's `write_policy` list, the write returns `write_forbidden`.
+Default scaffold — Setup-1 (roles `human=[author, propose]`, `agent=[propose, keep]`, `automation=[fetch, build]`):
+
+| Zone | `kind` | Required capability | Writable by (default) | Use case |
+|---|---|---|---|---|
+| `knowledge` | `canon` | `author` | `human` | Authored truth: identity, voice, decisions, network. `knowledge.identity.*` is the identity key convention. |
+| `notebook` | `workspace` | `keep` | `agent` | Agent's own durable working memory. Bytes climb to `knowledge` only via propose→accept. |
+| `feeds` | `quarantine` | `fetch` | `automation` | Declared external inputs (calendar, feeds, scraped pages). Fetched by external automation; never by humans or agents directly. |
+| `proposals` | `queue` | `propose` | `agent`, `human` | Proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `knowledge`. |
+| `artifacts` | `derived` | `build` | `automation` | Computed outputs (catalogs, indexes, published context). Written via `textus build`. |
+
+A write is gated by the caller's **role**, supplied via `--as=<role>`. If the role does not hold the capability the target zone-kind requires, the write returns `write_forbidden` with the message `writing '<key>' (zone '<zone>') needs capability '<verb>'` and a hint naming the roles that hold it (`held by: <roles>`, or `held by: no declared role` when none do).
 
 Every zone MUST declare a `kind:` describing its role in the data-flow graph.
-The vocabulary is closed: `origin` (authored truth), `quarantine` (external
-bytes pending validation), `queue` (proposals awaiting promotion), `derived`
-(computed from other zones). A manifest MUST declare at most one `queue` zone,
-and a zone's `kind:` MUST agree with its writers (`derived` ⇒ a `generator`
-writer, `queue` ⇒ a `proposer`, `quarantine` ⇒ a `runner`; `origin` is
-unconstrained). Coordination is keyed off the declared kind: a zone is derived
-only if it declares `kind: derived`, and proposals route to the declared
-`queue` zone — there is no name-based fallback. A manifest with a kind-less
-zone is rejected at load.
+The vocabulary is closed: `canon` (authored truth), `workspace` (agent's own
+durable lane), `quarantine` (external bytes pending validation), `queue`
+(proposals awaiting promotion), `derived` (computed from other zones). A
+manifest MUST declare at most one `queue` zone. Because authority is derived, a
+manifest is rejected at load if it declares a zone whose required verb is held
+by **no** declared role (`derived` ⇒ a role with `build`, `queue` ⇒ `propose`,
+`quarantine` ⇒ `fetch`, `workspace` ⇒ `keep`, `canon` ⇒ `author`). Coordination
+is keyed off the declared kind: a zone is derived only if it declares
+`kind: derived`, and proposals route to the declared `queue` zone — there is no
+name-based fallback. A manifest with a kind-less zone is rejected at load.
 
 ### 5.1 Role resolution
 
@@ -236,56 +317,72 @@ The effective role for any CLI invocation is resolved in this order; the first m
 3. `.textus/role` file (one line, role name) at the project root.
 4. Default: `human`.
 
-**Canonical actors (textus/3):**
+**Canonical roles (default scaffold):**
 
-| Actor | Meaning |
-|---|---|
-| `human` | Interactive user at a terminal. |
-| `agent` | Long-running AI or LLM process. |
-| `runner` | Scheduled or one-shot automation script. |
-| `builder` | Build/derive output (catalogs, indexes). |
+| Role | Capabilities (`can`) | Meaning |
+|---|---|---|
+| `human` | `[author, propose]` | Interactive user at a terminal; the single trust anchor. |
+| `agent` | `[propose]` | Long-running AI or LLM process; stages proposals. |
+| `automation` | `[fetch, build]` | Scheduled or one-shot scripts: fetch external sources, build derived outputs. |
 
-Unknown role values are rejected with `invalid_role`.
+Roles are declared in the manifest's `roles:` block (§5.1.1); the names above are the default mapping when `roles:` is omitted. Unknown role values are rejected with `invalid_role`.
 
 Every successful write records the resolved role and a wall-clock timestamp in `.textus/audit.log`, so reviewers can later distinguish a human edit from an agent edit even though both live in the same file.
 
-#### 5.1.1 Role kinds (engine semantics)
+#### 5.1.1 Capabilities
 
-Internally the engine recognizes four **role kinds** — abstract capability
-markers — rather than the four default role names. A manifest may declare a
-`roles:` block to map any role name to a kind:
+Roles declare **capabilities** — verbs from a closed five-element set. A
+manifest declares a `roles:` block mapping each role name to the capabilities
+it holds via `can:`:
 
 ```yaml
 roles:
-  - { name: owner,    kind: accept_authority }
-  - { name: compiler, kind: generator }
-  - { name: proposer, kind: proposer }
-  - { name: fetcher,  kind: runner }
+  - { name: owner,    can: [author, propose] }
+  - { name: proposer, can: [propose] }
+  - { name: fetcher,  can: [fetch] }
+  - { name: compiler, can: [build] }
+  - { name: keeper,   can: [keep] }
 ```
 
-Kind allow-list: `accept_authority`, `generator`, `proposer`, `runner`.
-At most one role may have `accept_authority`. When `roles:` is declared,
-every entry in `zones[*].write_policy` must be a declared role name.
+Capability allow-list: `propose`, `author`, `keep`, `fetch`, `build`. Each verb is the
+required capability for exactly one zone-kind:
+
+| Capability | Authorizes writes to zone-kind |
+|---|---|
+| `author` | `canon` |
+| `keep` | `workspace` |
+| `propose` | `queue` |
+| `fetch` | `quarantine` |
+| `build` | `derived` |
+
+`author` is the single **trust anchor**: **at most one role may hold `author`**
+(a manifest declaring two or more is rejected at load). The `accept` and
+`reject` transitions also require the `author` capability — `accept` is a
+transition verb, not a capability. Because write authority is derived, there is
+no `write_policy:` — instead, every declared zone-kind's required verb MUST be
+held by at least one role, or the manifest is rejected at load.
 
 When the `roles:` block is omitted, the default mapping applies:
 
-| Default name | Kind |
+| Default name | Capabilities (`can`) |
 |---|---|
-| `human`   | `accept_authority` |
-| `agent`   | `proposer` |
-| `builder` | `generator` |
-| `runner`  | `runner` |
+| `human`      | `[author, propose]` |
+| `agent`      | `[propose, keep]` |
+| `automation` | `[fetch, build]` |
 
-This means existing manifests continue to work byte-for-byte. Wire protocol
-`textus/3` is unchanged — kinds are an internal-semantics concept and never
-appear on the wire.
+Wire protocol `textus/3` is unchanged — capabilities are a manifest/semantics
+concept and never appear on the wire.
 
-The promotion DSL predicate `:human_accept` is now `:accept_authority_signed`;
-the old symbol works as an alias for backwards compatibility.
+Every write transition is authorized by **one Guard** (ADR 0031): an ordered
+list of predicates over a single evaluation context. Predicate #0 of every write
+guard is `zone_writable_by` (the capability gate above); the `author_held`
+predicate keys on the `author` capability and is named `author_held` (it passes
+when the acting role holds `author`). See §5.11 for composing extra predicates via
+`rules[].guard:`.
 
 ### 5.2 Compute layer (derived entries)
 
-Derived entries live in a zone whose `write_policy:` list includes `builder` — `output` in the default scaffold. They are not authored by hand; their body is produced by projecting over other entries. A derived entry declares a `compute:` block with a `kind:` discriminator.
+Derived entries live in a `derived` zone (writable by a role holding `build`; `automation` by default) — `output` in the default scaffold. They are not authored by hand; their body is produced by projecting over other entries. A derived entry declares a `compute:` block with a `kind:` discriminator.
 
 #### 5.2.1 Projection compute (`kind: projection`)
 
@@ -320,7 +417,7 @@ No partials. No lambdas. No HTML escaping (output is raw text, intended for Mark
 
 #### 5.2.2 External compute (`kind: external`)
 
-A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `compute: { kind: external, ... }`. textus does **not** execute the command (consistent with §2); the external runner is responsible for writing the file. textus records `sources:` so `textus freshness` can compare source mtimes against the derived file's `_meta.generated.at` and report staleness.
+A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `compute: { kind: external, ... }`. textus does **not** execute the command (consistent with §2); the external automation is responsible for writing the file. textus records `sources:` so `textus freshness` can compare source mtimes against the derived file's `_meta.generated.at` and report staleness.
 
 ```yaml
 - key: output.catalogs.skills
@@ -329,7 +426,7 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
   owner: build:catalog-skills
   compute:
     kind: external
-    command: "rake catalog:skills"   # informational; the runner invokes it
+    command: "rake catalog:skills"   # informational; external automation invokes it
     sources:                          # dotted keys OR repo-relative paths
       - working.projects
       - working.network
@@ -337,14 +434,14 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 
 **`sources:`** is a list. Each element is either a dotted key prefix (matched against manifest entries) or a filesystem path (relative to the repo root, or absolute). For each key prefix, every matching entry's file mtime is checked. For each path, file or directory mtime is checked.
 
-**`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `textus freshness` output can carry a hint about how to refresh.
+**`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `textus freshness` output can carry a hint about how to fetch.
 
 **Freshness contract.** An entry with `compute: { kind: external }` is reported by `textus freshness` as `stale` when:
 - The derived file does not exist, OR
 - `_meta.generated.at` is missing or unparseable, OR
 - Any `sources:` element has been modified after `_meta.generated.at`.
 
-**Frontmatter contract.** The external runner is responsible for writing the `generated:` frontmatter block when it produces the file:
+**Frontmatter contract.** The external automation is responsible for writing the `generated:` frontmatter block when it produces the file:
 
 ```yaml
 generated:
@@ -355,7 +452,7 @@ generated:
 
 `generated.from` SHOULD match `compute.sources` — they're the same list, recorded twice so a diff proves what was actually consumed.
 
-`kind: external` and `kind: projection` are alternatives — exactly one per entry. Templates are not required for `kind: external`: the runner produces the bytes directly.
+`kind: external` and `kind: projection` are alternatives — exactly one per entry. Templates are not required for `kind: external`: the external automation produces the bytes directly.
 
 ### 5.3 Publish layer (`publish_to:`)
 
@@ -373,21 +470,21 @@ 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 intake handler)
+### 5.4 Intake (declared, fetched via registered intake handler)
 
-Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus refresh KEY --as=runner` (or by `textus refresh stale`). The declaration is data only:
+Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus fetch KEY --as=automation` (or by `textus fetch stale`). The declaration is data only:
 
 ```yaml
-- key: intake.calendar.events
-  zone: intake
+- key: feeds.calendar.events
+  zone: feeds
   intake:
     handler: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
 
 rules:
-  - match: intake.calendar.**
-    refresh:
+  - match: feeds.calendar.**
+    fetch:
       ttl: 6h
       on_stale: warn            # warn | sync | timed_sync (default: warn)
       sync_budget_ms: 500       # only used when on_stale: timed_sync (default: 500)
@@ -401,9 +498,9 @@ rules:
 
 | Value | Behaviour |
 |---|---|
-| `warn` (default) | Return the entry immediately with `stale: true`, `stale_reason:` populated, and `refreshing: false`. No blocking. |
-| `sync` | Block the `get` call, run the intake handler in-process, write the refreshed result, then return the fresh envelope. The caller waits. |
-| `timed_sync` | Like `sync`, but with a `sync_budget_ms` deadline (default 500 ms). If the handler finishes within the budget the fresh envelope is returned. If it does not finish in time, return the stale envelope (with `stale: true`, `refreshing: true`) and let the refresh complete in the background. Fires `:refresh_backgrounded` when the deadline is exceeded. |
+| `warn` (default) | Return the entry immediately with `stale: true`, `stale_reason:` populated, and `fetching: false`. No blocking. |
+| `sync` | Block the `get` call, run the intake handler in-process, write the fetched result, then return the fresh envelope. The caller waits. |
+| `timed_sync` | Like `sync`, but with a `sync_budget_ms` deadline (default 500 ms). If the handler finishes within the budget the fresh envelope is returned. If it does not finish in time, return the stale envelope (with `stale: true`, `fetching: true`) and let the fetch complete in the background. Fires `:fetch_backgrounded` when the deadline is exceeded. |
 
 > **Note:** `list`/`where` paths do **not** annotate freshness — only `get` does.
 
@@ -415,16 +512,16 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 
 **Built-in intake handlers.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured `_meta`/body. Built-ins do not perform I/O themselves — the caller (or an outer hook) is responsible for supplying bytes.
 
-**Refresh paths.** Two are supported:
+**Fetch paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=runner` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under role `runner`.
-2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=runner --stdin`. The CLI verb `textus refresh stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
+1. **In-process** — `textus fetch KEY --as=automation` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under a role holding `fetch` (`automation` by default).
+2. **External automation** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`. The CLI verb `textus fetch stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
 
-Both paths share the same role gate, audit-log entry, and `:entry_refreshed` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
+Both paths share the same write gate, audit-log entry, and `:entry_fetched` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
 ### 5.5 Pending / accept workflow
 
-Proposal entries are full patches authored into a zone whose `write_policy:` list includes `agent` — `review` in the default scaffold — typically by agents or runners. The entry's frontmatter describes the patch it proposes against another zone:
+Proposal entries are full patches authored into the `proposals` queue zone (writable by `propose`-holders: `agent` and `human` by default) — `proposals` in the default scaffold (Setup-1) — typically by agents. The entry's frontmatter describes the patch it proposes against another zone:
 
 ```yaml
 ---
@@ -439,9 +536,9 @@ frontmatter:
 Proposed body content.
 ```
 
-`proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The remaining frontmatter and body are the proposed new content.
+`proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The remaining frontmatter and body are the proposed new content. A proposal's `target_key` MUST resolve to a `canon` zone; `accept` refuses any other target (`target_is_canon`, ADR 0035).
 
-`textus accept <proposal-key>` is **human-only**: the resolved role must be `human`. It copies the patch into the target zone, records provenance (originating proposal key, original role, original timestamp) in the audit log, and removes the proposal entry. Agents and runners can propose but cannot accept.
+`textus accept <proposal-key>` is a **transition** (not a capability) that requires the **`author` capability**: the resolved role must hold `author` (the single trust anchor — `human` by default). It copies the patch into the target zone, records provenance (originating proposal key, original role, original timestamp) in the audit log, and removes the proposal entry. The `reject` transition likewise requires `author`. Roles holding only `propose` (e.g. `agent`) can propose but cannot accept or reject.
 
 ### 5.6 Audit log
 
@@ -508,10 +605,10 @@ Schemas may declare per-field ownership and version history. The `fields:` and `
 fields:
   full_name: { type: string, maintained_by: human }
   embedding: { type: array,  maintained_by: agent }
-  updated_at: { type: time,  maintained_by: runner }
+  updated_at: { type: time,  maintained_by: automation }
 ```
 
-`maintained_by` values are free-form strings. The recognized set is `human | agent | runner | builder | derived`. Unrecognized values do not affect role-authority validation; they pass through unchanged.
+`maintained_by` values are free-form role-name strings (e.g. `human | agent | automation`). They name the role expected to own a field; values that match no declared role do not affect role-authority validation and pass through unchanged.
 
 **`evolution:` block** — top-level, declares the schema's history and migration intent:
 
@@ -527,7 +624,7 @@ evolution:
 
 **Defaults:** when `fields:` and `evolution:` are absent, `schema.maintained_by(field)` returns `nil` for every field and `schema.evolution` returns `{}`.
 
-**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. Humans override agent-maintained fields by design: schema field ownership (`maintained_by:`) makes the boundary explicit, not implicit. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
+**Override rule:** a role holding the `author` capability (the trust anchor — `human` by default) is permitted to write any `maintained_by` field, regardless of declared owner. The trust anchor overrides agent-maintained fields by design: schema field ownership (`maintained_by:`) makes the boundary explicit, not implicit. 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 Row transforms
 
@@ -535,6 +632,8 @@ Row transforms are RPC hooks on the `:transform_rows` event. See §5.10.
 
 ### 5.10 Hooks
 
+This section is the normative event table. For the hook-author's guide (how to define and test hooks), see [`docs/events.md`](docs/events.md).
+
 textus has a single hook registration verb: `Textus.hook { |reg| reg.on(event, name, **opts) { ... } }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path; the store-scoped loader drains the queued blocks and invokes each with its own registry.
 
 The subdirectory layout under `hooks/` is organizational only; the registered event and name come from the DSL call, not the file path.
@@ -563,24 +662,24 @@ end
 | `:validate`             | rpc     | caps:                                                     | issues array          | aborts doctor |
 | `:entry_put`            | pubsub  | ctx:, key:, envelope:                                     | (discarded)           | logged        |
 | `:entry_deleted`        | pubsub  | ctx:, key:                                                | (discarded)           | logged        |
-| `:entry_refreshed`      | pubsub  | ctx:, key:, envelope:, change:                            | (discarded)           | logged        |
+| `:entry_fetched`        | pubsub  | ctx:, key:, envelope:, change:                            | (discarded)           | logged        |
 | `:build_completed`      | pubsub  | ctx:, key:, envelope:, sources:                           | (discarded)           | logged        |
 | `:proposal_accepted`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
 | `:file_published`       | pubsub  | ctx:, key:, envelope:, source:, target:                   | (discarded)           | logged        |
 | `:entry_renamed`        | pubsub  | ctx:, key:, from_key:, to_key:, envelope:                 | (discarded)           | logged        |
 | `:proposal_rejected`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
 | `:store_loaded`         | pubsub  | ctx:                                                      | (discarded)           | logged        |
-| `:refresh_started`      | pubsub  | ctx:, key:, mode:                                         | (discarded)           | logged        |
-| `:refresh_failed`       | pubsub  | ctx:, key:, error_class:, error_message:                  | (discarded)           | logged        |
-| `:refresh_backgrounded` | pubsub  | ctx:, key:, started_at:, budget_ms:                       | (discarded)           | logged        |
+| `:fetch_started`        | pubsub  | ctx:, key:, mode:                                         | (discarded)           | logged        |
+| `:fetch_failed`         | pubsub  | ctx:, key:, error_class:, error_message:                  | (discarded)           | logged        |
+| `:fetch_backgrounded`   | pubsub  | ctx:, key:, started_at:, budget_ms:                       | (discarded)           | logged        |
 
-The three `:refresh_*` lifecycle events report the progress and failures of background (timed_sync) refreshes.
+The three `:fetch_*` lifecycle events report the progress and failures of background (timed_sync) fetches.
 
-**`:refresh_started`** fires immediately before an intake handler is invoked. `mode:` is one of `"sync"` or `"timed_sync"`.
+**`:fetch_started`** fires immediately before an intake handler is invoked. `mode:` is one of `"sync"` or `"timed_sync"`.
 
-**`:refresh_failed`** fires when an intake handler raises. `error_class:` is the exception class name string; `error_message:` is `e.message`.
+**`:fetch_failed`** fires when an intake handler raises. `error_class:` is the exception class name string; `error_message:` is `e.message`.
 
-**`:refresh_backgrounded`** fires when a `timed_sync` refresh exceeds its budget and is handed off to a background thread. `started_at:` is an ISO-8601 UTC string; `budget_ms:` is the configured deadline as an integer.
+**`:fetch_backgrounded`** fires when a `timed_sync` fetch exceeds its budget and is handed off to a background thread. `started_at:` is an ISO-8601 UTC string; `budget_ms:` is the configured deadline as an integer.
 
 **Signature invariant** — hooks receive a capability handle as their first keyword argument; the name depends on the mode:
 
@@ -603,25 +702,25 @@ A manifest MAY declare a top-level `rules:` block — a list of rule blocks matc
 
 ```yaml
 rules:
-  - match: intake.**
-    refresh: { ttl: 6h, on_stale: warn }
+  - match: feeds.**
+    fetch: { ttl: 6h, on_stale: warn }
 
-  - match: intake.calendar.**
-    refresh: { ttl: 30m, on_stale: timed_sync, sync_budget_ms: 800 }
+  - match: feeds.calendar.**
+    fetch: { ttl: 30m, on_stale: timed_sync, sync_budget_ms: 800 }
     intake_handler_allowlist: [ical-events]
 
-  - match: review.**
-    promotion:
-      requires: [schema_valid, human_accept]
+  - match: proposals.**
+    guard:
+      accept: [schema_valid, author_held]
 ```
 
 **Slots (all optional within a block):**
 
 | Slot | Type | Meaning |
 |---|---|---|
-| `refresh` | `{ ttl, on_stale, sync_budget_ms }` | Freshness budget for intake entries. `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
+| `fetch` | `{ ttl, on_stale, sync_budget_ms, fetch_timeout_seconds }` | Freshness budget for intake entries. `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
 | `intake_handler_allowlist` | list of strings | Constrains which `intake.handler:` names may be used by entries matched by this block. Enforced by `textus doctor`. |
-| `promotion` | `{ requires: [...] }` | Predicates a `review` entry must satisfy before `textus accept` will promote it. Built-in predicates: `schema_valid` (entry passes schema validation) and `human_accept` (the accepting role must be `human`). Additional predicates may be registered via `:validate` hooks. Enforced — `textus accept` refuses if any predicate fails. |
+| `guard` | `{ <transition>: [predicates] }` | Extra predicates composed (AND) onto a write transition's built-in **base** guard (ADR 0031). Keyed by transition (`put`, `delete`, `mv`, `accept`, `reject`, `fetch`). Predicate names are drawn from the closed vocabulary (`zone_writable_by`, `schema_valid`, `author_held`, `target_is_canon`, `etag_match`, `fresh_within`); parameterized predicates use `{ name: param }` form, e.g. `{ fresh_within: "1h" }`. Enforced — the transition refuses (`guard_failed`) if any predicate fails; the topology refusal keeps the `write_forbidden` code. |
 | `retention` | `{ expire_after:, archive_after: }` | Pruning policy for matched leaves. Duration strings: `30s`, `90m`, `12h`, `30d`, or bare integer seconds. `textus retain --as=ROLE` sweeps matched leaves: `expire_after` is checked first, so a leaf older than `expire_after` is deleted (and audited); otherwise a leaf older than `archive_after` is copied to `<store>/archive/<relative-path>` and then deleted. Age is measured from the leaf file's modification time. The `--as` role must be allowed to write the matched zone. |
 
 Both retention windows are optional, and `expire_after` is evaluated before
@@ -634,9 +733,9 @@ than aborting the run.
 
 **Match grammar.** `match:` is a single glob using `*` (single segment) and `**` (any depth). A literal segment ranks more specifically than `*`; `*` ranks more specifically than `**`.
 
-**Resolution.** For each key textus computes a `RuleSet { refresh, intake_handler_allowlist, promotion, retention }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`rule_ambiguity`).
+**Resolution.** For each key textus computes a `RuleSet { fetch, intake_handler_allowlist, guard, retention }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`rule_ambiguity`).
 
-**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key plus which block won each slot.
+**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key plus the effective guard predicate names for every write transition.
 
 ### 5.12 Storage formats
 
@@ -706,7 +805,7 @@ The frontmatter `name:` field, when present, must match the file's basename (wit
 - Existing files without a uid continue to work. The envelope shows `"uid": null` until a put mints one.
 - `text` entries have no metadata channel and therefore no uid; their envelope always shows `"uid": null`.
 
-Entries in `zone: derived` SHOULD additionally carry the `generated:` block defined in §5.2. Implementations MUST treat unknown frontmatter fields as warnings, not errors, so build runners can extend the metadata without breaking conformance.
+Entries in a `derived` zone SHOULD additionally carry the `generated:` block defined in §5.2. Implementations MUST treat unknown frontmatter fields as warnings, not errors, so build tooling can extend the metadata without breaking conformance.
 
 ## 8. Envelope (the wire format)
 
@@ -715,10 +814,10 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 ```json
 {
   "protocol": "textus/3",
-  "key": "working.network.org.jane",
-  "zone": "working",
+  "key": "knowledge.network.org.jane",
+  "zone": "knowledge",
   "owner": "textus:network",
-  "path": "/absolute/path/to/.textus/zones/working/network/org/jane.md",
+  "path": "/absolute/path/to/.textus/zones/knowledge/network/org/jane.md",
   "format": "markdown",
   "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
   "body": "Short body in Markdown.\n",
@@ -727,14 +826,14 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "uid": "a1b2c3d4e5f60718",
   "stale": false,
   "stale_reason": null,
-  "refreshing": false
+  "fetching": false
 }
 ```
 
 **Field rules:**
 - `protocol` MUST be the exact string `textus/3`.
 - `key` MUST be the canonical resolved key.
-- `zone` MUST be one of the zones declared in the manifest (`identity`, `working`, `intake`, `review`, `output` in the default scaffold).
+- `zone` MUST be one of the zones declared in the manifest (`knowledge`, `notebook`, `feeds`, `proposals`, `artifacts` in the default Setup-1 scaffold).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
@@ -742,11 +841,11 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
-- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been refreshed; `false` otherwise. Only populated for entries matched by a `refresh:` rule slot (typically `intake` zone); always `false` elsewhere.
-- `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_refreshed"`), or `null` when `stale` is `false`.
-- `refreshing` is `true` when a `timed_sync` background refresh is in flight for this entry; `false` otherwise. Callers observing `stale: true, refreshing: true` SHOULD retry after a short delay.
+- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been fetched; `false` otherwise. Only populated for entries matched by a `fetch:` rule slot (typically `feeds` / quarantine zone); always `false` elsewhere.
+- `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_fetched"`), or `null` when `stale` is `false`.
+- `fetching` is `true` when a `timed_sync` background fetch is in flight for this entry; `false` otherwise. Callers observing `stale: true, fetching: true` SHOULD retry after a short delay.
 
-> **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `refreshing` — freshness annotation is only provided by `get`.
+> **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `fetching` — freshness annotation is only provided by `get`.
 
 Errors use a distinct envelope:
 
@@ -755,8 +854,9 @@ Errors use a distinct envelope:
   "protocol": "textus/3",
   "ok": false,
   "code": "write_forbidden",
-  "message": "zone 'identity' is not writable by role 'agent' for key 'identity.self'",
-  "details": { "key": "identity.self", "zone": "identity", "role": "agent" }
+  "message": "writing 'knowledge.identity.self' (zone 'knowledge') needs capability 'author'",
+  "hint": "held by: human; pass --as=<role>",
+  "details": { "key": "knowledge.identity.self", "zone": "knowledge", "verb": "author", "holders": ["human"] }
 }
 ```
 
@@ -767,7 +867,7 @@ Errors use a distinct envelope:
 | `unknown_key` | Key does not resolve | 1 |
 | `bad_frontmatter` | YAML parse failed or `name:` mismatch | 1 |
 | `schema_violation` | Required field missing or wrong type | 1 |
-| `write_forbidden` | Resolved role is not in the zone's `write_policy` | 1 |
+| `write_forbidden` | Resolved role lacks the capability the zone-kind requires | 1 |
 | `etag_mismatch` | Concurrent write detected | 1 |
 | `io_error` | Filesystem failure | 64 |
 | `usage` | CLI argument error | 2 |
@@ -797,24 +897,24 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `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`) |
-| `refresh stale [--prefix=K] [--zone=Z] [--as=runner]` | write | per zone (typically `runner`) |
-| `build [--prefix=K] [--dry-run]` | write | `builder` (default) |
-| `accept K --as=human` | write | `human` |
+| `fetch KEY --as=automation` | write | `fetch`-holder (typically `automation`) |
+| `fetch stale [--prefix=K] [--zone=Z] [--as=automation]` | write | `fetch`-holder (typically `automation`) |
+| `build [--prefix=K] [--dry-run]` | write | `build`-holder (typically `automation`) |
+| `accept K --as=human` | write | `author`-holder (typically `human`) |
 | `init` | write | `human` |
 | `schema {show,init,diff,migrate}` | read/write | `human` for writes |
 | `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:
+**`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 capabilities:
 
 ```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",
+    "write_verbs":    ["put KEY --as=agent --stdin"],
+    "writable_zones": ["proposals"],
+    "propose_zone":   "proposals",
     "latest_seq":     1842
   }
 }
@@ -827,14 +927,14 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 ```json
 {
   "cursor":         1845,
-  "changed":        [ { "seq": 1843, "key": "working.x", "verb": "put", "role": "human", "ts": "..." } ],
-  "stale":          [ "output.marketplace" ],
-  "pending_review": [ "review.proposal.123" ],
+  "changed":        [ { "seq": 1843, "key": "knowledge.notes.x", "verb": "put", "role": "human", "ts": "..." } ],
+  "stale":          [ "artifacts.marketplace" ],
+  "pending_review": [ "proposals.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`.
+`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 queue 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):
 
@@ -852,9 +952,9 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 {
   "verb": "freshness",
   "rows": [
-    { "key": "intake.upstream.notes",
-      "zone": "intake",
-      "last_refreshed_at": "2026-05-21T13:21:17Z",
+    { "key": "feeds.upstream.notes",
+      "zone": "feeds",
+      "last_fetched_at": "2026-05-21T13:21:17Z",
       "age_seconds": 65000,
       "ttl_seconds": 43200,
       "on_stale": "warn",
@@ -864,9 +964,9 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 }
 ```
 
-Each row reports one entry's verdict (`fresh`, `stale`, `never_refreshed`, or `no_policy`) against its matched `refresh:` rule. `textus build` consumes its own staleness signal and executes derived entries' projections under the `builder` role; `--dry-run` prints the plan without executing.
+Each row reports one entry's verdict (`fresh`, `stale`, `never_fetched`, or `no_policy`) against its matched `fetch:` rule. `textus build` consumes its own staleness signal and executes derived entries' projections under a `build`-holding role (`automation` by default); `--dry-run` prints the plan without executing.
 
-`textus accept K --as=human` promotes a pending entry into its target zone: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only the `human` role may invoke `accept`.
+`textus accept K --as=human` promotes a pending entry into its target zone: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only a role holding the `author` capability (the trust anchor — `human` by default) may invoke `accept`.
 
 `textus init` scaffolds a fresh `.textus/` tree (manifest, zones, schemas, audit log) under the current directory with a default manifest. Customize by editing `.textus/manifest.yaml` after init.
 
@@ -882,7 +982,7 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 ## 10.2 `textus doctor`
 
-`textus doctor` returns a health-check envelope: `{ "protocol": "textus/3", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `intake_handler_allowlist`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/3", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `protocol_version`, `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `intake_registration`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `handler_allowlist`, `fetch_locks`, `proposal_targets`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 
@@ -897,7 +997,7 @@ The reference Ruby gem follows semver independently and speaks `textus/3`.
 
 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).
+For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/agents-mcp.md`](docs/agents-mcp.md).
 
 ## 12. Conformance fixtures
 
@@ -907,13 +1007,13 @@ A conformant implementation MUST pass these fixtures (the reference test suite s
 Given a manifest with `working.network.org` → `working/network/org` (nested), schema `person`, and a file `.textus/zones/working/network/org/jane.md` with valid frontmatter, `textus get working.network.org.jane --output=json` returns the canonical envelope with `etag` matching the file's sha256.
 
 **Fixture B — Role gate on write:**
-Given a manifest entry where `key: identity.self` lives in the `identity` zone (human-only), `textus put identity.self --stdin --as=agent` (with any valid input) returns the error envelope with `code: "write_forbidden"` and exit code 1.
+Given a manifest entry where `key: identity.self` lives in the `identity` zone (`kind: canon`, requiring the `author` capability), `textus put identity.self --stdin --as=agent` (where `agent` holds only `propose`) returns the error envelope with `code: "write_forbidden"` and exit code 1.
 
 **Fixture C — Schema violation:**
 Given the `person` schema and a `put` whose frontmatter omits `relationship`, the result is the error envelope with `code: "schema_violation"`, `details.missing: ["relationship"]`, and exit code 1.
 
 **Fixture D — Staleness detection:**
-Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, refresh: { ttl: 1h } }]` block and an envelope on disk whose `_meta.last_refreshed_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "stale"`. Calling `textus freshness` does NOT trigger a refresh.
+Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, fetch: { ttl: 1h } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "stale"`. Calling `textus freshness` does NOT trigger a fetch.
 
 **Fixture E — Projection build:**
 Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: projection }` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape, and updates `generated.at` to the build timestamp.
@@ -928,13 +1028,13 @@ Given a manifest entry with `publish_to: <path>`, a successful `textus build` fo
 Every successful write verb (`put`, `delete`, `build`, `accept`, `schema migrate`) appends exactly one line per affected key to the audit log, in the canonical format defined in §audit (timestamp, actor role, verb, key, etag-before, etag-after). No write produces zero or multiple lines per key.
 
 **Fixture I — Pending → accept:**
-Given a review entry `review.identity.self.patch` proposing a change to `identity.self`, `textus accept identity.self --as=human` copies the patch body into `identity.self`, deletes the review entry, and appends two audit lines (one for the identity write, one for the review delete) in that order.
+Given a proposal entry `proposals.knowledge.self.patch` proposing a change to `knowledge.identity.self`, `textus accept proposals.knowledge.self.patch --as=human` copies the patch body into the target key, deletes the proposal entry, and appends two audit lines (one for the target write, one for the proposals delete) in that order.
 
 ## 13. Why not X?
 
 - **Why not MCP?** MCP is a transport; textus is a data model. The two compose: a 50-line MCP server can wrap `textus get/put` as tools. textus exists because the *shape* of agent-readable project memory deserves a standalone spec, separate from how it's served.
 
-- **Why doesn't textus execute generator commands itself?** textus is a dataflow oracle, not a build runner. The moment a spec includes process execution, it inherits shell-injection surface, OS-portability concerns, and signal-handling semantics — and ends up duplicating whatever build system the consumer already runs (make, rake, just, lefthook, CI). Keeping execution external means a Python or TypeScript port of `textus/3` only has to parse YAML and emit JSON; it doesn't have to spawn processes safely. Build runners stay the executor; textus stays a data tool.
+- **Why doesn't textus execute external build commands itself?** textus is a dataflow oracle, not a build runner. The moment a spec includes process execution, it inherits shell-injection surface, OS-portability concerns, and signal-handling semantics — and ends up duplicating whatever build system the consumer already runs (make, rake, just, lefthook, CI). Keeping execution external means a Python or TypeScript port of `textus/3` only has to parse YAML and emit JSON; it doesn't have to spawn processes safely. External build systems stay the executor; textus stays a data tool.
 
 - **Why not plain Markdown vaults (Obsidian / Foam)?** No schema enforcement, no write-gating, no addressable wire format. Fine for human notes; underspecified for agents that must act on the contents deterministically.
 
@@ -948,28 +1048,9 @@ Given a review entry `review.identity.self.patch` proposing a change to `identit
 
 ## 13.1 Layered architecture (internal)
 
-Textus internals are organized into four layers. The dependency rule is one-way — each layer may only import from the layer beneath it.
-
-- **Interface** (`lib/textus/cli/`, `lib/textus/mcp/`) — CLI verbs and the MCP gate. Parses flags / RPC, calls a use case, formats JSON.
-- **Application** (`lib/textus/application/`) — Use cases: `Read::Get`, `Write::Put`, `Write::RefreshWorker`, `Write::RefreshOrchestrator`, `Write::RefreshAll`, `Maintenance::Migrate`, etc. Orchestrate domain + infra; no business rules.
-- **Domain** (`lib/textus/domain/`) — Pure values: `Authorizer`, `Permission`, `Freshness::{Policy,Verdict,Evaluator}`, `Action`, `Outcome`, `Sentinel`, `Staleness`. No I/O, no globals, testable without disk.
-- **Infrastructure** (`lib/textus/infra/`) — Adapters: `Storage::FileStore`, `AuditLog`, `AuditSubscriber`, `Publisher`, `Clock`, `Refresh::Lock`, `Refresh::Detached`, `BuildLock`. Wrap OS / library primitives.
-
-The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces are infrastructure adapters that predate this split and remain at their existing paths for backward-compat with the plugin DSL.
-
-Plugin authors interact only with the Hook DSL (`Textus.hook { |reg| reg.on(:resolve_intake, ...) }`, `reg.on(:entry_refreshed, ...)`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
-
-Both read and write paths flow through the application layer:
-
-- **Reads** flow through `Textus::Read::Get` (pure read + freshness annotation) or `Read::GetOrRefresh` (composes Get with `Write::RefreshOrchestrator`). Each takes a `container:` and a `call:`.
-- **Writes** flow through `Textus::Write::{Put,Delete,Mv,Accept,Reject,Publish,RefreshWorker}`. Permission checks happen at the use-case layer (via `Domain::Authorizer#authorize_write!`); the audit-append invariant lives in `Textus::Envelope::IO::Writer`.
-- `Textus::Call` is the slim per-invocation record: `role`, `correlation_id`, `now`, `dry_run`. Ports come from `Textus::Container`, not from the Call.
-- `Textus::Store` is the composition root and verb dispatcher. CLI verbs and the
-  MCP gate call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`).
-  Verbs are looked up in the static `Textus::Dispatcher::VERBS` table; adding a
-  use case is a single entry in `VERBS` plus the class.
+Textus internals are organized into four one-way layers — **Interface** (`cli/`, `mcp/`) → **Application** (`application/` use cases) → **Domain** (`domain/` pure values) → **Infrastructure** (`infra/` adapters). Each layer imports only from the one beneath it. Plugin authors touch only the Hook DSL and the manifest YAML; the layering is internal and may evolve.
 
-See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
+See [`docs/architecture/README.md`](docs/architecture/README.md) for an ASCII diagram and the full read-path walkthrough.
 
 ## 14. Open questions (v3.x scope)
 
@@ -987,10 +1068,10 @@ A `textus/3` implementation MUST:
 - [ ] Read `_meta` + body from `.md` files; validate against the named schema.
 - [ ] Read `_meta` from the top-level `_meta` hash in `.json` / `.yaml` files; validate against the named schema.
 - [ ] Compute `sha256:<hex>` etags over raw file bytes.
-- [ ] Refuse writes whose resolved role is not in the target zone's `write_policy` list with `write_forbidden`.
+- [ ] Refuse writes whose resolved role lacks the capability the target zone-kind requires with `write_forbidden`.
 - [ ] Return envelopes matching the shape in §8 exactly (with `_meta`, not `frontmatter`).
 - [ ] Use the error codes in §8 and the exit-code table.
-- [ ] Implement `textus freshness` per §5.1 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|stale|never_refreshed|no_policy` without invoking any refresh.
+- [ ] Implement `textus freshness` per §5.1 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|stale|never_fetched|no_policy` without invoking any fetch.
 - [ ] Pass the conformance fixtures A–I in §12.
 
 A `textus/3` implementation MAY:
@@ -1001,27 +1082,20 @@ A `textus/3` implementation MAY:
 
 ## 16. Migrating from textus/2
 
-textus 0.12.0 does not ship a built-in migrator. Upgrade path:
-
-1. Install textus **0.11.x** first.
-2. Run `textus migrate --to=textus/3` (available in 0.11.x only). This rewrites `manifest.yaml`, renames the `inbox/` zone directory to `intake/`, sweeps frontmatter `owner:` fields, writes an audit-log marker, and reports legacy hook-DSL call sites for manual review.
-3. Upgrade to textus **0.12.0**.
-4. If `.textus/audit.log` contains pre-0.11.0 rows with `role: ai|script|build`, run `textus audit-rewrite-legacy-roles` once (one-shot verb; removed in 0.13.0).
-
-**textus doctor refuses textus/2 stores.** The doctor check `protocol_version` emits an `error`-level issue when `manifest.yaml` carries `version: textus/2`. Install 0.11.x and migrate before upgrading to 0.12.0.
+textus does not ship a built-in textus/2 → textus/3 migrator. The historical upgrade path (via the one-shot `textus migrate` in the 0.11.x line) is recorded in `CHANGELOG.md` §0.11.0. `textus doctor` refuses a store still declaring `version: textus/2`. The textus/2 → textus/3 rename table is kept below for reference.
 
 **Vocabulary summary** (textus/2 → textus/3 rename table, for reference):
 
-| Category | textus/2 | textus/3 |
+| Category | textus/2 | textus/3 (current) |
 |---|---|---|
 | Actor | `ai` | `agent` |
-| Actor | `script` | `runner` |
-| Actor | `build` | `builder` |
+| Actor | `script` | `automation` |
+| Actor | `build` | `automation` |
 | Zone | `inbox` | `intake` |
-| Manifest | `writable_by:` | `write_policy:` |
+| Manifest | `writable_by:` | (removed — authority is derived from `kind:` × `can:`) |
 | Manifest | `policies:` | `rules:` |
 | Manifest | `handler_allowlist:` | `intake_handler_allowlist:` |
-| Manifest | `promote_requires:` | `promotion: { requires: [...] }` |
+| Manifest | `promote_requires:` | `guard: { accept: [...] }` |
 | Manifest | `projection:` | `compute: { kind: projection, ... }` |
 | Manifest | `generator:` | `compute: { kind: external, ... }` |
 | Hook event | `:intake` | `:resolve_intake` |
@@ -1029,24 +1103,91 @@ textus 0.12.0 does not ship a built-in migrator. Upgrade path:
 | Hook event | `:check` | `:validate` |
 | Hook event | `:put` | `:entry_put` |
 | Hook event | `:deleted` | `:entry_deleted` |
-| Hook event | `:refreshed` | `:entry_refreshed` |
+| Hook event | `:refreshed` | `:entry_fetched` |
 | Hook event | `:built` | `:build_completed` |
 | Hook event | `:accepted` | `:proposal_accepted` |
 | Hook event | `:reject` | `:proposal_rejected` |
 | Hook event | `:published` | `:file_published` |
 | Hook event | `:mv` | `:entry_renamed` |
 | Hook event | `:loaded` | `:store_loaded` |
-| Hook event | `:refresh_began` | `:refresh_started` |
-| Hook event | `:refresh_detached` | `:refresh_backgrounded` |
-| Hook event | `:refresh_failed` | `:refresh_failed` (unchanged) |
+| Hook event | `:refresh_began` | `:fetch_started` |
+| Hook event | `:refresh_detached` | `:fetch_backgrounded` |
+| Hook event | `:refresh_failed` | `:fetch_failed` |
 | Hook DSL | `Textus.hook(ev, name)` / sugar | `Textus.on(ev, name)` |
 | Compute field | `projection.reduce:` | `compute.transform:` |
 | `_meta` key | `reducer` | `transform` |
 | CLI flag | `--format=json` (envelope) | `--output=json` |
-| CLI verb | `refresh-stale` | `refresh stale` |
+| CLI verb | `refresh-stale` | `fetch stale` |
 | CLI verb | `policy list/explain` | `rule list/explain` |
 
-**Notes on hook migration.** The 0.11.x migrator scanner reports each file and call site that uses a legacy event name or DSL method. No automatic rewrite is performed. Update each hook to use `Textus.on(:new_event_name, ...)` before re-enabling the hook. See CHANGELOG §0.11.0 for the full event rename table.
+**Hook migration.** Legacy event names / DSL methods must be renamed to the textus/3 forms above before a hook will load; see `CHANGELOG.md` §0.11.0 for the full event-rename detail.
+
+### 16.1 Breaking changes in 0.31.0 (capability-based roles)
+
+0.31.0 replaced declared per-zone write policies with **derived** authority and renamed the `refresh` transition to `fetch`. These keys/values are no longer accepted:
+
+| Removed / renamed (≤ 0.30) | 0.31.0 form |
+|---|---|
+| `zones[*].write_policy:` | (removed) authority is derived: `role.can ⊇ { verb_for(zone.kind) }` |
+| `roles[*].kind:` (`accept_authority`/`generator`/`proposer`/`runner`) | `roles[*].can:` (subset of `propose`, `author`, `fetch`, `build`) |
+| Actors `runner`, `builder` | `automation` (`can: [fetch, build]`) by default |
+| `rules[*].refresh:` slot | `rules[*].fetch:` slot |
+| CLI `textus refresh` / `refresh stale` | `textus fetch` / `fetch stale` |
+| `_meta.last_refreshed_at` | `_meta.last_fetched_at` |
+| Promotion predicate `:human_accept` / `:accept_authority_signed` | `:author_signed` |
+| Envelope `refreshing` | `fetching` |
+
+A manifest still declaring `write_policy:` or a role `kind:` is rejected at load. There is no compatibility alias — the breaking change requires a new wire-compatible manifest. (Wire string `textus/3` is unchanged: capabilities are a manifest concept and never appear on the wire.)
+
+### 16.2 Breaking changes in 0.33.0 (workspace/keep + Setup-1 scaffold)
+
+0.33.0 adds the fifth coordination primitive (`workspace` zone-kind + `keep` capability), renames the capability `accept` → `author` (and predicate `accept_signed` → `author_signed`), renames zone-kind `origin` → `canon`, and renames the default scaffold zones to the Setup-1 names. These changes affect **manifest files and tooling** only — the `textus/3` wire format is **UNCHANGED** (envelope shape, audit-log schema, key grammar, and the `version: textus/3` field are all identical to 0.32.x).
+
+**Renames (manifest and predicate vocabulary):**
+
+| Removed / renamed (≤ 0.32) | 0.33.0 form |
+|---|---|
+| Zone-kind `origin` | `canon` |
+| Capability `accept` | `author` |
+| Promotion predicate `accept_signed` | `author_signed` |
+| Default scaffold zone `identity` | `knowledge` (identity keys live under `knowledge.identity.*`) |
+| Default scaffold zone `working` | `knowledge` (merged into the same `canon` zone) |
+| Default scaffold zone `intake` | `feeds` |
+| Default scaffold zone `review` | `proposals` |
+| Default scaffold zone `output` | `artifacts` |
+
+**New in 0.33.0:**
+
+| Addition | Detail |
+|---|---|
+| Zone-kind `workspace` | Agent's own durable lane. Required capability: `keep`. Bytes never auto-promote; climb to `canon` only via propose→accept. |
+| Capability `keep` | Authorizes writes to `workspace` zones. Default scaffold: `agent` holds `[propose, keep]`. |
+| Default scaffold zone `notebook` | `kind: workspace`, default owner `agent`. |
+| `owner:` on a zone | OPTIONAL, INFORMATIONAL — not enforced in 0.33.0 (owner-scoped enforcement is deferred). |
+| `desc:` on a zone | OPTIONAL — surfaces as the `purpose` field in `textus boot` zone rows. |
+
+**Clarification (not a breaking change):** `accept` and `reject` are **transition verbs** (CLI commands), not capabilities. Both require the `author` capability. This has always been true; 0.33.0 makes it explicit by removing `accept` from the capability vocabulary.
+
+A manifest declaring `kind: origin` or capability `accept` (in a `can:` list) is rejected at load.
+
+### 16.3 Breaking changes in 0.35.0 (proposal target-canon + `author_held`)
+
+0.35.0 constrains a proposal's target to a `canon` zone and renames the anchor-gate predicate. No `textus/3` wire change; no manifest-schema change.
+
+**Renames (predicate vocabulary):**
+
+| Removed / renamed (≤ 0.34) | 0.35.0 form |
+|---|---|
+| Promotion predicate `author_signed` | `author_held` |
+
+**New in 0.35.0:**
+
+| Addition | Detail |
+|---|---|
+| Floor predicate `target_is_canon` | On the `accept` base guard. A proposal's `target_key` MUST resolve to a `canon` zone; `accept` refuses any other target with `guard_failed` naming `target_is_canon`. Floor-only — not relaxable via `rules[].guard`. |
+| `doctor` check `proposal_targets` | Warns on queued proposals whose `target_key` is non-canon (`proposal.target_not_canon`) or unresolvable (`proposal.target_unresolved`). |
+
+A `rules[].guard` block referencing the predicate by its old name `author_signed` is rejected at load (unknown predicate).
 
 ---