textus 0.54.0 → 0.54.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f98dbc5f461b8cffaa4cf8fb17c8b79cf51f4c5f78af62527e0abe27d84d828
-  data.tar.gz: 0bfd928765a9797078f7534aecbf89321de754a4d56ee71986c00fb6a3a7b255
+  metadata.gz: 53f01828833f9c5e6cb0249fe513b92d6afbb210d90cfca10f51c560c8b2e2ca
+  data.tar.gz: 1956232435c941479290225e20168979beb270a6e2f5874df37c302e170a43e7
 SHA512:
-  metadata.gz: 32fd23741a0f3e69368dfde1fb8733381190b17eb592c459079020a692c98c181a689ab5a83af6b3bf2d16c37ab2b52e40faf6a47ce876e4bafc0709e082ebed
-  data.tar.gz: daadc9db41cf87e2a348ddf9b4472fc515a48b4f5e7ca77d9c00a6c95ed736d26c59b3ad1ec799a42e3eba940052236dc77e5ee3edaf4737150e8f030a5fbcaa
+  metadata.gz: c086755b90faab7ecebdeebd722e9458dbede54c5efa9be212d6d861c999655093166a1f61826aa9e09ebee8cd1cf57996d958bd410c3b682763d911ed44abe5
+  data.tar.gz: aad04f9470c3de178ad6c762ef3102528cbdc94922fedb79d121ffbadc23acc5dd3f52871f6b3c0c75664afdb968c12fa814b88fbedcbd0d914161e4e1f337ab

data/CHANGELOG.md

@@ -9,6 +9,37 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.54.2 — 2026-06-18 — ingest dedup, .run → .state rename
+
+### Added
+
+- **Content-hash dedup in `Action::Ingest`**: re-ingesting the same URL or file bytes silently creates a supersede chain — new entry with full content, old stripped to tombstone with a `superseded_by` pointer.
+- **`Ports::RawIndex`**: lightweight YAML-based O(1) index for raw lane content-hash/URL lookups, stored at `.textus/.state/indexes/raw.yaml`.
+- **`content_hash` field**: every new raw entry stores a `sha256:` content hash for fast dedup lookups.
+- **Asset file move on re-ingest**: asset files are moved (not copied) to the new date path on supersede.
+
+### Changed
+
+- **`.run` → `.state` rename**: the runtime artifact directory is renamed from `.textus/.run/` to `.textus/.state/`. The `state/` subdirectory becomes `cursors/`. Layout path methods follow automatically. Manual migration step: `mv .textus/.run .textus/.state`.
+
+## 0.54.1 — 2026-06-17 — MCP SDK, dry ecosystem, ERB templates
+
+### Added
+
+- **`Textus::Types` module**: shared `dry-types` constrained types (`RoleName`, `Cursor`, `FormatName`) used across all dry-struct structs.
+
+### Changed
+
+- **MCP surface → official `mcp` SDK** (PR #223): the hand-rolled JSON-RPC 2.0 stdio loop is replaced by the official `mcp` gem (`~> 0.20`). Protocol version auto-negotiates up to `2025-11-25` (was hardcoded `2024-11-05`). `Catalog.build_tools` generates `MCP::Tool` instances from verb contracts; `Server` manages session lifecycle and delegates dispatch. `routing.rb`, the `MCP::Session` alias, and `ToolSchemas` are deleted.
+- **`Session`, `Envelope`, `Container` → `Dry::Struct`** (PR #223): `Data.define` replaced with `Dry::Struct` for typed, loudly-failing construction at object creation time. `Session` enforces `RoleName` and non-negative `Cursor`; `Envelope` enforces known `FormatName`; `Container` has typed port references.
+- **Manifest validator → dry-schema + Semantics** (PR #223): the 318-line programmatic validator is split into `contract.rb` (dry-schema structural contract) and `semantics.rb` (cross-field rules, `walk`-based unknown-key detection, ADR migration hints). Public interface `Validator.validate!` unchanged.
+- **Mustache → ERB** (PR #223): `mustache` gem removed; all 8 `.mustache` templates converted to `.erb` using `ERB#result_with_hash`. `Produce::Render` now uses `ERB.new(template, trim_mode: "-").result_with_hash(ctx)`.
+
+### Removed
+
+- `mustache` runtime dependency (replaced by Ruby stdlib ERB).
+- `MCP::Routing` module, `MCP::Session` alias, `MCP::ToolSchemas` module — superseded by the SDK.
+
 ## 0.54.0 — 2026-06-16 — Workflow system, raw ingest pipeline, MCP resources
 
 ### Added
@@ -388,7 +419,7 @@ No `textus/3` wire-format change. Manifest schema gains one optional, backward-c
   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).
+  [`docs/reference/zones.md`](docs/reference/lanes.md#nested-entries).
 
 ### Internal
 

data/README.md

@@ -39,6 +39,9 @@ flowchart LR
     agent -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
     automation -->|drain| artifacts["artifacts<br/>(machine)"]
+    human -->|ingest| raw["raw<br/>(intake)"]
+    agent -->|ingest| raw
+    automation -->|ingest| raw
 
     proposals ==>|human accept| knowledge
     knowledge -.->|projection source| artifacts
@@ -46,13 +49,15 @@ flowchart LR
     classDef actor fill:#238636,stroke:#2ea043,color:#fff;
     classDef gate fill:#9e6a03,stroke:#bb8009,color:#fff;
     classDef anchor fill:#1f6feb,stroke:#388bfd,color:#fff;
+    classDef intake fill:#6e40c9,stroke:#8b5cf6,color:#fff;
     class human,agent,automation actor;
     class proposals gate;
     class knowledge anchor;
+    class raw intake;
 ```
 
 *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`).*
+*Colour legend: **green** = writers · **amber** = the review gate (`proposals`) · **blue** = the trust anchor (`knowledge`) · **purple** = write-once intake (`raw`).*
 
 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.
 
@@ -64,22 +69,21 @@ DURABLE       │  notebook                │  knowledge  ★ the goal
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
-TRANSIENT     │  artifacts.feeds.*       │  proposals  (queue)           │
-(staging)     │  raw external input,     │  a candidate, in review       │
-              │  unverified (machine)    │  ▲ climbs via human accept    │
+TRANSIENT     │  artifacts  (outputs)    │  proposals  (queue)           │
+(staging)     │  computed, machine-made  │  a candidate, in review       │
+              │  raw        (inputs)     │  ▲ climbs via human accept    │
+              │  ingested, write-once    │                               │
               └──────────────────────────┴───────────────────────────────┘
                 raw material ──── propose ────► a human accept lifts it to canon
 ```
 
-*(The `machine` lane's other half, `artifacts.derived.*`, isn't on this grid — it's a computed **output** projected from the lanes, not an input climbing toward trust.)*
-
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — enforced at the protocol level, not by convention — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**.
 
 ```
-knowledge/   author only        — who you are, what you decide, how you sound (knowledge.identity.* for identity facts)
-notebook/    keep only          — agent's own durable lane (agents keep theirs; bytes climb to knowledge only via propose→accept)
-proposals/   propose (agent + human) — proposals waiting on a human accept
-artifacts/   converge only     — machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
+knowledge/   author only            — who you are, what you decide, how you sound
+notebook/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
+proposals/   propose (agent+human) — proposals waiting on a human accept
+artifacts/   converge only         — machine-maintained: computed outputs + external inputs
 ```
 
 An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
@@ -109,12 +113,12 @@ 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), drain/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`.textus/`](.textus/)
+- **Worked end-to-end store** — the role gate (propose → accept), drain/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, ERB templates, and workflows: [`.textus/`](.textus/)
 - **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
 
-This Ruby gem is the reference implementation of **`textus/3`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/3`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
+This Ruby gem is the reference implementation of **`textus/4`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/4`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
 
 - Specification: [`SPEC.md`](SPEC.md)
 - Architecture: [`docs/architecture/README.md`](docs/architecture/README.md)
@@ -137,7 +141,7 @@ bundle exec exe/textus --help
 
 ## What `textus init` gives you
 
-You get `.textus/` with all four lane directories under `data/`, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, produce locks). Roles declare capabilities; each lane declares a `kind:`, and write authority is derived from the role's capabilities crossed with the lane's kind:
+You get `.textus/` with all five lane directories under `data/`, baseline schemas, a starter manifest, and a gitignored `.state/` for disposable runtime state (the audit log, per-role cursors, produce locks). Roles declare capabilities; each lane declares a `kind:`, and write authority is derived from the role's capabilities crossed with the lane's kind:
 
 ```yaml
 roles:
@@ -146,29 +150,30 @@ roles:
   - { name: automation, can: [converge] }
 
 lanes:
-  - { name: knowledge, kind: canon }      # author    — canonical truth
-  - { name: notebook,  kind: workspace }  # keep      — agent's own durable lane
-  - { name: proposals, kind: queue }      # propose   — proposals awaiting accept
-  - { name: artifacts, kind: machine }    # converge — external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
+  - { name: knowledge, kind: canon }      # author   — canonical truth
+  - { name: notebook,  kind: workspace }  # keep     — agent's own durable lane
+  - { name: proposals, kind: queue }      # propose  — proposals awaiting accept
+  - { name: artifacts, kind: machine }    # converge — computed outputs + external inputs
 ```
 
 ```
 .textus/
   manifest.yaml          # role capabilities + lane kinds + key-to-path mapping
   schemas/               # YAML field shapes per entry family
-  templates/             # mustache templates for derived entries
-  steps/                 # step subclasses: fetch/, transform/, validate/, observe/
-  .gitignore             # generated — ignores .run/ and any tracked:false entries
+  templates/             # ERB templates for produced entries
+  workflows/             # Ruby workflow files (Textus.workflow DSL) for data acquisition
+  .gitignore             # generated — ignores .state/ and any tracked:false entries
   data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
     notebook/
     proposals/
-    artifacts/           # machine lane: feeds/ (external inputs) + derived/ (computed outputs)
-  .run/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
-    audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~50 MB)
-    state/cursor.<role>  # per-role pulse cursor — where `pulse --since` resumes
+    artifacts/           # machine lane: computed outputs + external inputs
+  .state/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
+    audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~10 MB)
+    cursors/<role>       # per-role pulse cursor — where `pulse --since` resumes
     locks/               # per-key produce locks + the produce mutex
     sentinels/           # publish bookkeeping (target sha) — regenerated on drain (ADR 0070)
+    indexes/raw.yaml     # raw lane content-hash/URL index — regenerable cache
 ```
 
 Manifest `path:` fields are relative to `.textus/data/`. So `knowledge.notes.org.jane` lives at `.textus/data/knowledge/notes/org/jane.md`.
@@ -181,104 +186,106 @@ textus list --lane=knowledge
 printf '%s' '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put knowledge.notes.bob --as=human --stdin
 textus drain --as=automation     # re-pull stale inputs + recompute derived outputs
-textus rule list                     # show every rule block
-textus audit --limit=20              # query the audit log
+textus rule list                  # show every rule block
+textus audit --limit=20           # query the audit log
 ```
 
-(All verbs return JSON envelopes; `--output=json` is the default and the only format in v1.)
+(All verbs return JSON envelopes; `--output=json` is the default and the only format.)
 
-For a worked store — knowledge entries, a staged proposal, schemas, a template, and a `drain` that publishes `CLAUDE.md` / `AGENTS.md` — see [`.textus/`](.textus/).
+For a worked store — knowledge entries, a staged proposal, schemas, ERB templates, and a `drain` that publishes `CLAUDE.md` / `AGENTS.md` — see [`.textus/`](.textus/).
 
 ## What's shipped
 
 - **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies 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 × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). 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/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
-- **`textus doctor`.** Health checks across schemas, step registrations, keys, sentinels, and the audit log.
+- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
+- **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
+- **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
+- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; notebook stub per ingest. See "Intake and ingest" section below.
 
 ## CLI and lanes
 
 Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` ([SPEC §3.1](SPEC.md)). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` ([SPEC §5.1](SPEC.md)). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md).
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Lane semantics and the capability × lane-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.md).
+- Lane semantics and the capability × lane-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/lanes.md`](docs/reference/lanes.md).
 
-`textus boot` prints the same information for the current store: lanes, entry families with schemas, registered steps, 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.
+`textus boot` prints the same information for the current store: lanes, entry families with schemas, registered workflows, 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.
 
 ## Produce and publish
 
-Produced entries (`kind: produced`) declare how they're acquired in one `source:` block (ADR 0093/0094); `drain` materialises them:
+Produced entries (`kind: produced`) declare how they're acquired in one `source:` block; `drain` materialises them. Two built-in modes, plus workflows for custom data acquisition:
 
-- **`source: { from: derive, select: [...], pluck:, sort_by:, limit:, transform: name }`** — a *derived* entry: textus computes its data from other entries, then renders it through a template under `.textus/templates/` (markdown/text) or a templateless path that lets a transform hook shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.
-- **`source: { from: fetch, handler: name, ttl: 1h, config: {...} }`** — *intake*: a Step::Fetch handler pulls external bytes on a `ttl` cadence; `drain` re-pulls when the entry goes stale.
-- **`source: { from: external, sources: [...] }`** — *externally managed*: an out-of-band command writes the file; textus tracks the declared `sources` for staleness.
+- **`source: { from: external, command: "...", sources: [...] }`** — *externally managed*: an out-of-band command or workflow writes the file; textus tracks staleness via declared `sources`.
+- **`source: { from: external, command: "true", sources: [] }` + a workflow** — *workflow-driven*: a `Textus.workflow` block (in `.textus/workflows/`) acquires and shapes the data on `drain`.
 
-Publishing is one typed `publish:` block (ADR 0052). `publish: { to: [path, ...] }` byte-copies a single produced file to one or more targets. `publish: { tree: "dir" }` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/.run/sentinels/` (git-ignored runtime state, regenerated on drain — ADR 0070). See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/.state/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
 
-## Extension points
+Templates live in `.textus/templates/` as ERB files (`.erb`). The template receives the entry's `content` hash as local variables via `ERB#result_with_hash`. If `inject_boot: true`, a `boot` variable is also available with the live orientation context.
 
-textus extends through **steps** — subclass the right base, place the file in `.textus/steps/<kind>/`, and `drain` discovers it. Three kinds:
+## Workflows
 
-**`Step::Fetch`** — acquires bytes for an intake entry (`from: fetch`). One class per named handler; `drain` invokes it when the entry is stale.
+textus extends through **workflows** — a `Textus.workflow` block placed in `.textus/workflows/**/*.rb`. Each workflow matches a produced entry by key glob, then runs one or more named steps to acquire its data:
 
 ```ruby
-# .textus/steps/fetch/local_file.rb
-module Textus
-  module Step
-    class LocalFileFetch < Fetch
-      def call(config:, args:, **)
-        path = config["path"] or raise "local-file requires source.config.path"
-        { "_meta" => { "last_fetched_at" => Time.now.utc.iso8601 },
-          "body"  => File.read(File.expand_path(path)) }
-      end
-    end
+# .textus/workflows/docs/my_report.rb
+Textus.workflow "my_report" do
+  match "artifacts.my-report"
+
+  step :build do |_, ctx|
+    # read from knowledge, fetch external data, compute anything
+    rows = ctx.container.manifest.resolver
+              .enumerate(prefix: "knowledge.notes")
+              .map { |r| { "key" => r[:key], "title" => r[:entry].schema } }
+    { "content" => { "entries" => rows } }
   end
 end
 ```
 
-**`Step::Transform`** — reshapes projected rows for a `from: derive` entry.
+`drain` discovers all workflow files, matches them against produced entries, and runs the steps. The result is written back to the entry's data path; `publish:` then copies it to its consumer paths.
 
-```ruby
-# .textus/steps/transform/rank_by_recency.rb
-module Textus
-  module Step
-    class RankByRecencyTransform < Transform
-      def call(rows:, config:, **)
-        rows.sort_by { |r| r["updated_at"].to_s }.reverse
-      end
-    end
-  end
-end
-```
+## Intake and ingest
 
-**`Step::Observe`** — reacts to lifecycle events (fire-and-forget, 0..N per event):
+The `raw` lane is the inbound counterpart to `artifacts`: where `drain` materialises
+**outbound** computed outputs, `ingest` receives **inbound** external source material.
 
-```ruby
-# .textus/steps/observe/log_writes.rb
-module Textus
-  module Step
-    class LogWritesObserve < Observe
-      on :entry_written
-
-      def call(key:, envelope:, **)
-        $textus_event_log << [key, envelope.etag]
-      end
-    end
-  end
-end
-```
+**The ingest principle:** prefer a reference over a copy. Store body or asset only when the
+content itself is the value — human-authored notes, brainstorm outputs, context you want to
+annotate. For everything else, the URL is enough. If the source is private or
+access-restricted, set `access: private` in `source:` so downstream workflows can handle it
+appropriately.
+
+**Three source kinds:**
+
+| Kind | Stores | Use when |
+|------|--------|----------|
+| `url` | URL reference only (`body: null`) | Bookmarking a page, skill, or doc for later annotation |
+| `file` | File body text | Valuable human-authored content (brainstorm notes, meeting summaries) |
+| `asset` | Binary at `assets/raw/` | Screenshots, PDFs — only when the asset itself is the artefact |
+
+**Write-once** — the same slug on the same day cannot be overwritten. Delete and re-ingest to replace.
 
-Observable events: `:entry_written`, `:entry_deleted`, `:entry_fetched`, `:entry_renamed`, `:entry_produced`, `:entry_published`, `:produce_failed`, `:proposal_accepted`, `:proposal_rejected`, `:store_loaded`, `:session_opened`, `:entry_fetch_started`, `:entry_fetch_failed`.
+```sh
+# bookmark a skill reference — URL only, body stays null
+textus ingest url agentskills-io-brainstorming \
+  --url=https://agentskills.io/skills/brainstorming \
+  --label="brainstorming skill" \
+  --as=agent
+
+# see what landed in the raw lane
+textus list --lane=raw
+
+# a notebook stub was created alongside — annotate it
+textus get notebook.notes.raw
+```
 
-Stale intake entries are re-pulled by `drain`, not by reads — `get` is a pure
-read that annotates the returned envelope with a freshness verdict (ADR 0089).
-`drain` re-pulls anything past its `source.ttl` and recomputes derived outputs:
+Stale produced entries are re-materialised by `drain`, not by reads — `get` is a pure read (ADR 0089).
 
 ```sh
-textus drain --as=automation                  # re-pull every stale intake + recompute derived
-textus drain artifacts.feeds --as=automation  # scope to one prefix
-textus get artifacts.feeds.calendar.events    # a pure read; carries a freshness verdict
+textus drain --as=automation                  # re-materialise every stale produced entry
+textus drain artifacts.feeds.skills --as=automation # scope to one prefix
+textus get artifacts.feeds.skills                  # a pure read; carries a freshness verdict
 ```
 
 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.
@@ -287,7 +294,7 @@ See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot
 
 ## Examples
 
-[`.textus/`](.textus/) — textus as a project's own context store (a fictional Rails service, `ledger`). Human-authored `knowledge/` (project facts, runbooks), a staged ADR in `proposals/` showing the agent-propose / human-accept loop, schemas validating each family, a mustache template plus a `Step::Transform` step, and a `drain` that publishes the `artifacts.derived.orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
+[`.textus/`](.textus/) — textus as a project's own context store. Human-authored `knowledge/` (project facts, runbooks, ADRs), a staged proposal showing the agent-propose / human-accept loop, schemas validating each family, ERB templates and workflows, and a `drain` that publishes the orientation artifact to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
 
 ## Tests