textus 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 020c9cf77e098bd7099a5cd0871801b40d7be8266b2942c8ddb6cfed60c85af0
-  data.tar.gz: d4bfacdf7f6049df88e37b53e24ff4927f4bfd20f3d0ff55d5ed4d54ecbfb1fd
+  metadata.gz: 15b2e8bcfb3e83425617ee187705b88ad99c1f96671a7ad04a8394073f98065d
+  data.tar.gz: e0711f287c8739fcc2e5f9507fd5637b9c63159b2d8e364f9d65f338138ff432
 SHA512:
-  metadata.gz: aefe80bba5a38c4db29fe663cf3f41c77229075cc5b02b95b9fac0c8df62b81aed936bef95dd610becb6c700238936ddd8dd528762dae576747552ab4e9acbac
-  data.tar.gz: 6d342cad8cb4dd0d3f320990c45ca0c4a996e5499dafd9c90f72b53731d53294f57b8dea2b4c625d96e43245da2138f3df8971d9ba416940cdc59a390754f577
+  metadata.gz: 74ec9edba22fdd7884c7bf1a16b9f73a636524c11f889824a516775857294ea674ebd6f6fe9b0a4d98028d30cf5673b51c376760968baa4d8413c83a33475484
+  data.tar.gz: c097ccd942039828754bd70ae2f457e172ca88166c318c72199138e126301aa4432cec318ff77c456a73de4176c0e6fe65160cca899111dcd27785adc9eff62c

data/CHANGELOG.md

@@ -11,6 +11,31 @@ tracks both additive improvements and breaking protocol bumps independently.
 
 ## Unreleased
 
+## 0.39.0 — 2026-06-01 — Native ignore patterns for entry enumeration ([ADR 0042](docs/architecture/decisions/0042-native-ignore-patterns-for-entry-enumeration.md))
+
+No `textus/3` wire-format change. Manifest schema gains one optional, backward-compatible key (`ignore:`); existing manifests are unaffected.
+
+### Added
+
+- **Per-entry `ignore:` globs on `nested` entries (ADR 0042).** A `nested`
+  entry may declare a list of gitignore-style globs (e.g.
+  `["**/node_modules/**", "**/dist/**"]`) to keep vendored or generated
+  subtrees out of the store. Patterns are honoured by **one shared filter
+  seam** consulted by both resolver enumeration (`list`, `build`) and
+  `textus doctor`, evaluated *above* key-legality: an ignored path is excluded,
+  never judged. This closes the prior divergence where a store could `list`
+  cleanly while `doctor` was red on the same vendored paths. Matching is
+  segment-wise globstar — `**` spans zero or more path segments; within a
+  segment `*` is anchored and `{a,b}` alternates (stdlib `File.fnmatch`,
+  no new dependency). Documented in
+  [`docs/reference/zones.md`](docs/reference/zones.md#nested-entries).
+
+### Internal
+
+- **Dogfood textus in its own repo ([ADR 0041](docs/architecture/decisions/0041-dogfood-textus-in-its-own-repo.md)).**
+  A self-development store and MCP wiring for textus's own repository. No change
+  to the published gem's behavior.
+
 ## 0.38.0 — 2026-05-31 — MCP serve acts as agent by default ([ADR 0040](docs/architecture/decisions/0040-mcp-connection-role-and-two-channels.md))
 
 No `textus/3` wire-format change; no manifest-schema change.
@@ -451,7 +476,7 @@ Protocol remains `textus/3`.
   `refresh`, `refresh_stale`, `schema`, `rules`). Session state (cursor,
   role, manifest_etag) held server-side. Manifest drift surfaces as
   `ContractDrift` (-32001); cursor expiry as `CursorExpired` (-32002).
-  See [`docs/mcp.md`](docs/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
+  See [`docs/reference/mcp.md`](docs/reference/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
 - `examples/claude-plugin/.mcp.json` and migrated skills/commands/agents —
   zero `textus <verb>` shell strings remain in plugin markdown.
 

data/README.md

@@ -30,13 +30,35 @@ flowchart LR
     human(["human"]) -->|author| knowledge["knowledge<br/>(canon)"]
     agent(["agent"]) -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    proposals -->|human accepts| knowledge
+    proposals ==>|human accept| knowledge
     automation(["automation"]) -->|fetch| feeds["feeds<br/>(quarantine)"]
     automation -->|build| artifacts["artifacts<br/>(derived)"]
+    feeds -.->|projection source| artifacts
+    knowledge -.->|projection source| artifacts
+
+    classDef anchor fill:#1f6feb,stroke:#1f6feb,color:#fff;
+    class knowledge anchor;
 ```
 
 *Each actor writes only into its own lane; low-trust input climbs to authoritative lanes only by passing a guarded transition (an agent's proposal needs a human `accept`).*
 
+The point of those lanes is to **build context you can trust**. Place each lane on two axes — how durable it is, and how much you can rely on it without review — and the value shows up as a climb: the high-trust corner (durable *and* authoritative = `knowledge`) is the one place nothing is *written* directly. It's *earned* by crossing the `accept` gate.
+
+```
+                       LOW TRUST                     HIGH TRUST
+                      (unreviewed)                (authoritative)
+              ┌──────────────────────────┬───────────────────────────────┐
+DURABLE       │  notebook                │  knowledge  ★ the goal        │
+(kept)        │  agent's working truth   │  canon — a human authors      │
+              │  durable, but low-trust  │  here · the context you ship  │
+              ├──────────────────────────┼───────────────────────────────┤
+TRANSIENT     │  feeds                   │  proposals  (queue)           │
+(staging)     │  raw external input,     │  a candidate, in review       │
+              │  unverified              │  ▲ climbs via human accept    │
+              └──────────────────────────┴───────────────────────────────┘
+                raw material ──── propose ────► a human accept lifts it to canon
+```
+
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — called a **zone** in the manifest and CLI, the term used everywhere technical from here on — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
 
 ```
@@ -68,7 +90,7 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 ## Try it
 
 - **Worked end-to-end store** — the role gate (propose → accept), build/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`examples/project/`](examples/project/)
-- **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/agents-mcp.md`](docs/agents-mcp.md)
+- **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md)
 
 ## Protocol, not just a gem
 
@@ -150,7 +172,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, a template
 - **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; `publish_to:`/`publish_each:` byte-copy derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × zone-kind gate.** Writes carry `--as=<role>`; a role may write a zone iff it holds the capability the zone's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `quarantine`→`fetch`, `queue`→`propose`, `derived`→`build`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
-- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/agents-mcp.md](docs/agents-mcp.md))
+- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
 - **`textus doctor`.** Health checks across schemas, hooks, keys, sentinels, and the audit log.
 
 ## CLI and zones
@@ -158,7 +180,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, a template
 All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block).
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
+- Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.md).
 
 `textus boot` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
@@ -213,7 +235,7 @@ See SPEC.md §5.10 for the full hook contract.
 
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
-See [`docs/agents-mcp.md`](docs/agents-mcp.md) for the agent boot → pulse loop.
+See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot → pulse loop.
 
 ## Examples
 

data/SPEC.md

@@ -632,7 +632,7 @@ 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).
+This section is the normative event table. For the hook-author's guide (how to define and test hooks), see [`docs/how-to/writing-hooks.md`](docs/how-to/writing-hooks.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.
 
@@ -1003,7 +1003,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/agents-mcp.md`](docs/agents-mcp.md).
+For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md).
 
 ## 12. Conformance fixtures
 

data/lib/textus/doctor/check/illegal_keys.rb

@@ -11,15 +11,18 @@ module Textus
             next unless File.directory?(base)
 
             index_fn = entry.respond_to?(:index_filename) ? entry.index_filename : nil
-            index_fn ? check_index_paths(entry, index_fn, base, out) : check_all_paths(base, out)
+            index_fn ? check_index_paths(entry, index_fn, base, out) : check_all_paths(entry, base, out)
           end
           out
         end
 
         private
 
-        def check_all_paths(base, out)
+        def check_all_paths(entry, base, out)
           walk_nested(base) do |abs_path, is_dir|
+            rel = abs_path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            next if entry.ignored?(rel)
+
             basename = File.basename(abs_path)
             stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
             next if stem.match?(Key::Grammar::SEGMENT)
@@ -31,10 +34,13 @@ module Textus
         # When the entry uses `index_filename:`, only the parent-directory
         # segments leading to each index file participate in keys. Sibling
         # files and unrelated subtrees are not enumerated and must not be
-        # flagged. Each illegal segment is reported once per path.
-        def check_index_paths(_entry, index_fn, base, out)
+        # flagged. Each illegal segment is reported once per path. Paths under
+        # an ignored subtree (ADR 0042) are excluded before any segment check.
+        def check_index_paths(entry, index_fn, base, out)
           Dir.glob(File.join(base, "**", index_fn)).each do |fp|
             rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            next if entry.ignored?(rel)
+
             File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
               next if seg.match?(Key::Grammar::SEGMENT)
 

data/lib/textus/manifest/entry/base.rb

@@ -39,6 +39,11 @@ module Textus
         def events         = {}
         def publish_each   = nil
         def index_filename = nil
+        def ignore         = []
+
+        # Per-entry ignore (ADR 0042). Base entries enumerate no tree, so
+        # nothing is ever ignored; Nested overrides with real patterns.
+        def ignored?(_rel_path) = false
 
         # Minimal context object passed into entry `publish_via` hooks.
         # Everything beyond the three primitives is derived. Data.define

data/lib/textus/manifest/entry/ignore_matcher.rb

@@ -0,0 +1,46 @@
+module Textus
+  class Manifest
+    class Entry
+      # Pure glob matcher backing per-entry `ignore:` patterns (ADR 0042).
+      # `rel_path` is the slash-joined path of a candidate file relative to the
+      # entry's base directory.
+      #
+      # Matching is segment-wise so the `**` globstar means "zero or more path
+      # segments" — `File.fnmatch` alone cannot express this (under
+      # FNM_PATHNAME a trailing `**` will not cross a `/`; without it a leading
+      # `**/` will not match zero leading segments). So `**/node_modules/**`
+      # catches the `node_modules` subtree at any depth, including the store
+      # root, and the directory entry itself.
+      #
+      # Within a single segment, matching delegates to `File.fnmatch` with
+      # FNM_EXTGLOB, so a single `*` is anchored to that segment (it does not
+      # cross `/`) and `{a,b}` alternation works.
+      module IgnoreMatcher
+        SEGMENT_FLAGS = File::FNM_EXTGLOB
+
+        def self.match?(patterns, rel_path)
+          path_segs = rel_path.split("/").reject(&:empty?)
+          Array(patterns).any? do |pat|
+            match_segments(pat.split("/").reject(&:empty?), path_segs)
+          end
+        end
+
+        # Classic globstar matcher. `**` matches zero or more whole segments;
+        # any other pattern segment matches exactly one path segment via fnmatch.
+        def self.match_segments(pat_segs, path_segs)
+          return path_segs.empty? if pat_segs.empty?
+
+          if pat_segs.first == "**"
+            match_segments(pat_segs[1..], path_segs) ||
+              (!path_segs.empty? && match_segments(pat_segs, path_segs[1..]))
+          else
+            !path_segs.empty? &&
+              File.fnmatch?(pat_segs.first, path_segs.first, SEGMENT_FLAGS) &&
+              match_segments(pat_segs[1..], path_segs[1..])
+          end
+        end
+        private_class_method :match_segments
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/nested.rb

@@ -5,16 +5,22 @@ module Textus
         PUBLISH_EACH_VARS   = Validators::PublishEach::KNOWN_VARS
         PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
 
-        attr_reader :index_filename, :publish_each
+        attr_reader :index_filename, :publish_each, :ignore
 
-        def initialize(index_filename: nil, publish_each: nil, **rest)
+        def initialize(index_filename: nil, publish_each: nil, ignore: nil, **rest)
           super(**rest)
           @index_filename = index_filename
           @publish_each = publish_each
+          @ignore = Array(ignore)
         end
 
         def nested? = true
 
+        # True when `rel_path` (slash-joined, relative to the entry base) matches
+        # any configured ignore glob. Evaluated ABOVE key-legality (ADR 0042):
+        # an ignored path is excluded, never judged.
+        def ignored?(rel_path) = IgnoreMatcher.match?(@ignore, rel_path)
+
         def publish_target_for(full_key)
           return nil if @publish_each.nil?
 
@@ -65,6 +71,7 @@ module Textus
           new(
             index_filename: raw["index_filename"],
             publish_each: raw["publish_each"],
+            ignore: raw["ignore"],
             **common,
           )
         end

data/lib/textus/manifest/entry/validators/ignore.rb

@@ -0,0 +1,28 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        # Validates the per-entry `ignore:` field (ADR 0042): a list of
+        # non-empty glob strings, allowed only on nested entries.
+        module Ignore
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
+            patterns = entry.raw["ignore"]
+            return if patterns.nil?
+
+            raise UsageError.new("entry '#{entry.key}': ignore requires nested: true") unless entry.nested?
+
+            raise UsageError.new("entry '#{entry.key}': ignore must be a list of glob strings") unless patterns.is_a?(Array)
+
+            patterns.each do |pat|
+              next if pat.is_a?(String) && !pat.empty?
+
+              raise UsageError.new(
+                "entry '#{entry.key}': each ignore pattern must be a non-empty string (got #{pat.inspect})",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators.rb

@@ -7,6 +7,7 @@ module Textus
           PublishEach,
           InjectBoot,
           IndexFilename,
+          Ignore,
           FormatMatrix,
         ].freeze
 

data/lib/textus/manifest/resolver.rb

@@ -78,6 +78,8 @@ module Textus
 
       def nested_row_for(entry, base, path)
         rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+        return nil if entry.ignored?(rel)
+
         entry_if = entry.index_filename
         stripped = entry_if ? File.dirname(rel) : rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
         segs = stripped.split("/").reject { |s| s.empty? || s == "." }

data/lib/textus/manifest/schema.rb

@@ -25,7 +25,7 @@ module Textus
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
         compute template publish_to publish_each
-        intake events inject_boot index_filename
+        intake events inject_boot index_filename ignore
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.38.0"
+  VERSION = "0.39.0"
   PROTOCOL = "textus/3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Patrick
@@ -107,7 +107,6 @@ files:
 - CHANGELOG.md
 - README.md
 - SPEC.md
-- docs/conventions.md
 - exe/textus
 - lib/textus.rb
 - lib/textus/boot.rb
@@ -251,6 +250,7 @@ files:
 - lib/textus/manifest/entry.rb
 - lib/textus/manifest/entry/base.rb
 - lib/textus/manifest/entry/derived.rb
+- lib/textus/manifest/entry/ignore_matcher.rb
 - lib/textus/manifest/entry/intake.rb
 - lib/textus/manifest/entry/leaf.rb
 - lib/textus/manifest/entry/nested.rb
@@ -258,6 +258,7 @@ files:
 - lib/textus/manifest/entry/validators.rb
 - lib/textus/manifest/entry/validators/events.rb
 - lib/textus/manifest/entry/validators/format_matrix.rb
+- lib/textus/manifest/entry/validators/ignore.rb
 - lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_boot.rb
 - lib/textus/manifest/entry/validators/publish_each.rb

data/docs/conventions.md

@@ -1,148 +0,0 @@
-# Conventions
-
-> **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
-> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.35)
-
-Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
-
-## Key naming
-
-- **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
-- **Lead with the zone in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
-- **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
-- **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
-
-## Zone layout
-
-Recommended top-level layout — the spec allows alternatives, but this is what tooling will default to:
-
-```
-.textus/
-  manifest.yaml
-  schemas/        # YAML schema definitions
-  zones/
-    knowledge/    # authored truth: identity, voice, decisions — author-holders write
-    notebook/     # agent's own durable lane (workspace) — keep-holders write
-    feeds/        # automation-fed external inputs (fetch)
-    proposals/    # AI proposals awaiting accept (propose)
-    artifacts/    # generated by build automation — never edit by hand
-```
-
-Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
-
-## Schema design
-
-- **One schema per entry type, not per directory.** `person.yaml`, `project.yaml`, `decision.yaml` — applied across multiple subtrees if the shape matches.
-- **Required = "this entry is meaningless without it."** Everything else is `optional`. Resist the urge to mark organisational metadata (like `tags`) required.
-- **Prefer `enum` over free-text** for low-cardinality fields (relationship type, status, severity). Agents are far better at picking from a list than at producing exact strings.
-- **Cap string lengths** with `max:` where the field has a natural bound (names, summaries). Skip for prose body — bodies are not schema-validated, only frontmatter is.
-
-## Owner strings
-
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
-
-- `textus:network` — humans curate
-- `agent:planner` — a specific named agent
-- `build:catalog-skills` — a specific build job
-
-Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
-
-## Derived entries
-
-A derived entry declares a `compute:` block with a `kind:` discriminator. Two kinds:
-
-**`compute: { kind: projection }`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
-
-```yaml
-- key: artifacts.catalogs.people
-  path: artifacts/catalogs/people.md
-  zone: artifacts
-  schema: null
-  owner: build:catalog-people
-  compute:
-    kind: projection
-    select: knowledge.network.org   # prefix or list of prefixes
-    pluck:  [name, relationship, org]
-    sort_by: name
-  template: people.mustache         # under .textus/templates/
-  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
-```
-
-**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
-
-```yaml
-- key: artifacts.catalogs.skills
-  path: artifacts/catalogs/skills.md
-  zone: artifacts
-  owner: build:catalog-skills
-  compute:
-    kind: external
-    command: "rake catalog:skills"   # informational; the automation invokes it
-    sources: [knowledge.projects, knowledge.network]
-```
-
-The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `compute.sources` — same list, recorded twice so a diff proves what was consumed.
-
-Full contract for both shapes is in [`../SPEC.md` §5.2.1 and §5.2.2](../SPEC.md). Transforms (`compute.transform:`) and per-leaf publishing (`publish_each:`) are also covered there.
-
-## Intake and freshness
-
-External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
-
-```sh
-textus fetch feeds.notion.roadmap --as=automation
-textus fetch stale --zone=feeds --as=automation   # everything past its TTL
-```
-
-Freshness budgets live in the top-level `rules:` block, matched by glob:
-
-```yaml
-rules:
-  - match: feeds.notion.**
-    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
-```
-
-A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
-
-```sh
-textus fetch stale --zone=intake --as=automation   # in cron / CI
-```
-
-See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
-
-### Read vs. fetch
-
-There are two read operations, and the difference matters in custom code:
-
-| Operation | Triggers fetch? | Use for |
-|-----------|-----------------|---------|
-| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
-
-Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
-
-## Body content
-
-- **Bodies are Markdown.** Headings, lists, code fences — whatever a human or agent finds useful.
-- **The schema does not validate the body.** If a field belongs in structured data, put it in frontmatter, not the body.
-- **Keep entries short.** If a project entry hits 500 lines, it probably wants to be split into sub-entries (e.g. `working.projects.acme.dashboard` + `working.projects.acme.api`) rather than one mega-document.
-
-## Concurrency
-
-For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
-
-## Application layering
-
-The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](architecture/decisions/0018-manifest-carving.md), [ADR 0017](architecture/decisions/0017-envelope-io-split.md), [ADR 0022](architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](architecture/decisions/0023-uniform-use-case-shape.md).
-
-- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
-- **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
-
-The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
-
-## Pairing with other tools
-
-- **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
-- **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
-- **CI**: run `textus freshness` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.