textus 0.38.0 → 0.39.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 020c9cf77e098bd7099a5cd0871801b40d7be8266b2942c8ddb6cfed60c85af0
-  data.tar.gz: d4bfacdf7f6049df88e37b53e24ff4927f4bfd20f3d0ff55d5ed4d54ecbfb1fd
+  metadata.gz: af15d8a77f0d71c3fab21dc246545b3a7b84242361c518b1d901c491c63e55c4
+  data.tar.gz: 4644479ed6df331a6973806fed302b29446d3806d1793d8ea9d9fa661000e986
 SHA512:
-  metadata.gz: aefe80bba5a38c4db29fe663cf3f41c77229075cc5b02b95b9fac0c8df62b81aed936bef95dd610becb6c700238936ddd8dd528762dae576747552ab4e9acbac
-  data.tar.gz: 6d342cad8cb4dd0d3f320990c45ca0c4a996e5499dafd9c90f72b53731d53294f57b8dea2b4c625d96e43245da2138f3df8971d9ba416940cdc59a390754f577
+  metadata.gz: ee1cf4024e3583c1e59791b279a2fd0f8c00e426f05391267db0239d1a7d2909c521b94bc27caf62d549d902b0dc7f62847178f0ea17973e14b26689a981302a
+  data.tar.gz: 775daa6d3992b0b93d2a57c230fbfc5705b50fec592327356f4fa6ccc4dc39aaacdcbd1c24d2dd878a1b6612fd5e9c3416ede0b42d9ba90978dc8f8461c6d014

data/CHANGELOG.md

@@ -11,6 +11,60 @@ tracks both additive improvements and breaking protocol bumps independently.
 
 ## Unreleased
 
+## 0.39.1 — 2026-06-01 — Feed ergonomics: `feeds.machine` env snapshot + intake cookbook ([ADR 0043](docs/architecture/decisions/0043-feed-ergonomics-without-breaking-core-purity.md))
+
+No `textus/3` wire-format change. `textus init` scaffolds an additional
+`nested` feed entry; core intake still makes no implicit network calls
+(SPEC §5.4).
+
+### Added
+
+- **`textus init` scaffolds `feeds.machines.*` with a local env snapshot
+  (ADR 0043).** Generated stores get a `nested` feed entry capturing ambient
+  machine context (git HEAD/branch/dirty state, `now`, versions) as an explicit,
+  user-owned snapshot — keeping ambient state out of `boot`/`pulse` (which stay
+  side-effect-free per ADR 0037) and out of `quarantine` (which means external
+  bytes pending validation, where the freshness model does not apply).
+
+### Documentation
+
+- **Multi-machine environment-scan cookbook recipe** demonstrating the nested
+  `feeds.machines.*` pattern.
+- **Examples** updated to use the `feeds.machine` env snapshot, matching
+  `textus init` output.
+- **README flow diagram** redesigned to group writers and colour-code roles.
+- **How-to fixes** for zone-rename drift in the agents-mcp guide and the
+  `:publish` event name.
+
+### Internal
+
+- Removed the legacy `ARCHITECTURE.md` redirect stub.
+
+## 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 +505,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

@@ -27,15 +27,50 @@ Three actors write to your repo today:
 
 ```mermaid
 flowchart LR
-    human(["human"]) -->|author| knowledge["knowledge<br/>(canon)"]
-    agent(["agent"]) -->|keep| notebook["notebook<br/>(workspace)"]
+    subgraph writers["writers — who can write"]
+        direction TB
+        human(["human"])
+        agent(["agent"])
+        automation(["automation"])
+    end
+
+    human -->|author| knowledge["knowledge<br/>(canon)"]
+    agent -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    proposals -->|human accepts| knowledge
-    automation(["automation"]) -->|fetch| feeds["feeds<br/>(quarantine)"]
+    automation -->|fetch| feeds["feeds<br/>(quarantine)"]
     automation -->|build| artifacts["artifacts<br/>(derived)"]
+
+    proposals ==>|human accept| knowledge
+    feeds -.->|projection source| artifacts
+    knowledge -.->|projection source| artifacts
+
+    classDef actor fill:#238636,stroke:#2ea043,color:#fff;
+    classDef gate fill:#9e6a03,stroke:#bb8009,color:#fff;
+    classDef anchor fill:#1f6feb,stroke:#388bfd,color:#fff;
+    class human,agent,automation actor;
+    class proposals gate;
+    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`).*
+*Colour legend: **green** = writers · **amber** = the review gate (`proposals`) · **blue** = the trust anchor (`knowledge`).*
+
+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 +103,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 +185,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 +193,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 +248,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/init/templates/machine_intake.rb

@@ -0,0 +1,45 @@
+# .textus/hooks/machine_intake.rb
+# Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
+# entry from manifest.yaml if you don't want it.
+# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus fetch` (never
+# on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
+# `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
+# (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
+# ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
+Textus.hook do |reg|
+  reg.on(:resolve_intake, :machines) do |config:, args:, **|
+    machine = args[:leaf_segments].first or
+      raise "fetch a host leaf, e.g. `textus fetch feeds.machines.local`"
+    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
+    unless (spec["via"] || "local").to_s == "local"
+      raise "machine #{machine}: only `via: local` is scaffolded — see " \
+            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
+    end
+
+    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
+    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
+    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
+    { content: {
+      # git_* describe THIS repo on the control host — only meaningful for `local`.
+      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
+      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
+      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
+      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
+      "captured_at"    => Time.now.utc.iso8601,
+      "os"             => RbConfig::CONFIG["host_os"],
+      "arch"           => RbConfig::CONFIG["host_cpu"],
+      "ruby_version"   => RUBY_VERSION,
+      "runtimes"       => {                                 # versions only; nil when not installed
+        "node"   => ver.call("node --version"),
+        "python" => ver.call("python3 --version"),
+        "go"     => ver.call("go version"),
+      },
+      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
+        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
+        "apt"  => count.call("dpkg-query -f '.\n' -W"),
+      },
+      "textus_version" => Textus::VERSION,
+      "protocol"       => Textus::PROTOCOL,
+    } }
+  end
+end

data/lib/textus/init.rb

@@ -1,4 +1,5 @@
 require "fileutils"
+require "pathname"
 
 module Textus
   module Init
@@ -21,6 +22,26 @@ module Textus
         - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
         - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
         - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
+        # A per-host snapshot, pulled by `textus fetch feeds.machines.local --as=automation`.
+        # Nested so it grows to a fleet — add feeds.machines.<host> leaves over SSH
+        # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
+        # gitignored (machine info can be sensitive/noisy) but still protocol-readable
+        # via `textus get feeds.machines.local`. Delete to opt out. (ADR 0043)
+        - key: feeds.machines
+          path: feeds/machines
+          zone: feeds
+          format: yaml
+          nested: true
+          tracked: false
+          kind: intake
+          intake:
+            handler: machines
+            config:
+              machines:
+                local: { via: local }
+      rules:
+        - match: feeds.machines.**
+          fetch: { ttl: 1h, on_stale: warn } # meaningful on a long-running server
     YAML
 
     HOOKS_README = <<~MD
@@ -91,12 +112,31 @@ module Textus
         File.write(File.join(dir, ".gitkeep"), "")
       end
       File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
+      scaffold_dir = File.expand_path("init/templates", __dir__)
+      File.write(File.join(target_root, "hooks", "machine_intake.rb"),
+                 File.read(File.join(scaffold_dir, "machine_intake.rb")))
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
-      File.write(File.join(target_root, ".gitignore"), Textus::Layout::GITIGNORE)
+      File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end
+
+    # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now
+    # derived from the manifest: the run subtree plus every `tracked: false`
+    # entry's resolved path (ADR 0043).
+    def self.derived_gitignore(target_root)
+      manifest = Textus::Manifest.load(target_root)
+      root = Pathname.new(target_root)
+      untracked = manifest.data.entries.reject(&:tracked?).map do |e|
+        if e.nested? # a whole subtree of leaf files (feeds.machines.* → zones/feeds/machines/)
+          "#{File.join("zones", e.path)}/"
+        else
+          Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
+        end
+      end
+      Textus::Layout.gitignore_body(untracked_paths: untracked)
+    end
   end
 end

data/lib/textus/layout.rb

@@ -33,9 +33,22 @@ module Textus
       File.join(audit_dir(root), "audit.log")
     end
 
-    GITIGNORE = <<~GITIGNORE
-      # textus runtime artifacts — safe to delete, never commit
-      #{RUN}/
-    GITIGNORE
+    # The store's `.gitignore` body. Always ignores the runtime subtree
+    # (`.run/`, ADR 0038); when given untracked entry paths (entries marked
+    # `tracked: false`), it also lists those so they stay protocol-readable but
+    # uncommitted (ADR 0043, refining 0038). Generated, never hand-kept — no
+    # drift between the manifest and the ignore file.
+    def self.gitignore_body(untracked_paths: [])
+      lines = ["# textus runtime artifacts — safe to delete, never commit",
+               "#{RUN}/"]
+      unless untracked_paths.empty?
+        lines << "# tracked:false entries — protocol-readable, not committed (sensitive)"
+        lines.concat(untracked_paths)
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    # Back-compat constant: the no-untracked-entries body (just the run subtree).
+    GITIGNORE = gitignore_body
   end
 end

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

@@ -31,6 +31,12 @@ module Textus
         def intake?  = false
         def leaf?    = false
 
+        # Whether git should track this entry's file. Default true; an entry
+        # marked `tracked: false` in the manifest stays protocol-readable but is
+        # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
+        # reads from raw here rather than threading through every constructor.
+        def tracked? = @raw["tracked"] != false
+
         # Nil stubs for cross-cutting optional attrs. Subclasses override the
         # ones they own. Validators and serializers can call these directly
         # without `respond_to?` guards.
@@ -39,6 +45,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 tracked
       ].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.1"
   PROTOCOL = "textus/3"
 end

data/lib/textus.rb

@@ -17,6 +17,10 @@ loader.inflector.inflect(
 loader.ignore(File.expand_path("textus/errors.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp/errors.rb", __dir__))
+# Scaffold sources copied verbatim into user stores by `textus init`. They are
+# file templates (one calls `Textus.hook` at load time), not gem constants —
+# Zeitwerk must not manage or eager-load them (ADR 0043).
+loader.ignore(File.expand_path("textus/init/templates", __dir__))
 loader.setup
 loader.eager_load
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.1
 platform: ruby
 authors:
 - Patrick
@@ -103,11 +103,9 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ARCHITECTURE.md
 - CHANGELOG.md
 - README.md
 - SPEC.md
-- docs/conventions.md
 - exe/textus
 - lib/textus.rb
 - lib/textus/boot.rb
@@ -235,6 +233,7 @@ files:
 - lib/textus/hooks/rpc_registry.rb
 - lib/textus/hooks/signature.rb
 - lib/textus/init.rb
+- lib/textus/init/templates/machine_intake.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.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/ARCHITECTURE.md

@@ -1,3 +0,0 @@
-# Architecture
-
-Moved to [`docs/architecture/README.md`](docs/architecture/README.md).

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.