@north-light/crouter 0.3.208 → 0.3.210

package/dist/builtin-memory/insights/capture.md

@@ -2,8 +2,6 @@
 kind: knowledge
 when-and-why-to-read: When directly received user material supports a proposed reusable principle, this knowledge should be read because review by the user keeps durable guidance grounded in their actual judgment.
 short-form: Extract the why behind one user-derived principle, review its truth and destination, then write only what the user approves.
-system-prompt-visibility: none
-file-read-visibility: none
 rationale: Agents have missed deeper user insight hidden in ordinary feedback, saved their own unreviewed interpretation as fundamental truth, and — when the user corrected a behavior — proposed the corrected behavior itself as the insight when the durable truth was the reason the user made the correction. The earlier proposal template compounded this by framing capture as correction (a "Current truth" section) and burying destination and source in prose sections.
 ---
 
@@ -45,6 +43,6 @@ The review is asynchronous. Continue unrelated work or wait dormant, but do not
 
 Apply direct line edits and explicit comments. If feedback requires a materially new formulation, update the open review artifact or submit a replacement review; review the revised formulation before writing it. If no candidate survives, save nothing.
 
-Run `crtr memory write -h` for the authoring contract, then reach only the approved destination — `crtr memory write` to create it, `crtr memory edit` to revise one that exists. A new principle is normally knowledge, and a preference only when its use is behavioral; use `none` visibility on both axes unless review approves a flat boot-rung exception. Keep its body to the approved truth, any material boundary, and the concise why. Update the selected active listener or organizing router with the canonical link without duplicating the principle.
+Run `crtr memory write -h` for the authoring contract, then reach only the approved destination — `crtr memory write` to create it, `crtr memory edit` to revise one that exists. A new principle is normally knowledge, and a preference only when its use is behavioral; give it no `surfaces` routing unless review approves a boot entry. Keep its body to the approved truth, any material boundary, and the concise why. Update the selected active listener or organizing router with the canonical link without duplicating the principle.
 
 Source context and agent reasoning stay only in the review artifact. Do not copy them into semantic memory or provenance frontmatter. Run `crtr memory lint` after every create or rewrite and fix every finding.

package/dist/builtin-memory/insights/init.md

@@ -2,8 +2,6 @@
 kind: knowledge
 when-and-why-to-read: When the user invokes /insights:init to begin gathering user-derived insight about a domain, this knowledge should be read because a correctly scoped listener preserves uniquely valuable knowledge without creating a parallel store or background system.
 short-form: Initialize passive insight gathering for a domain at the narrowest durable scope; create one routed topic index that reviews user-derived principles before saving them.
-system-prompt-visibility: none
-file-read-visibility: none
 slash: true
 rationale: Ordinary conversations, corrections, answers to `crtr human send`, and review comments carry unique user knowledge that agents inconsistently recognize or save; when agents do infer a deeper principle, they have written it without first letting the user correct the extrapolation.
 ---
@@ -34,7 +32,7 @@ Search the chosen scope before creating. If `insights/<topic>` already represent
 
 ## Create the listener
 
-Run `crtr memory write -h`, then create `insights/<topic>/INDEX.md` at the chosen scope as a preference with system-prompt visibility `preview` and file-read visibility `none`.
+Run `crtr memory write -h`, then create `insights/<topic>/INDEX.md` at the chosen scope as a preference surfaced `{on: boot, at: preview}`.
 
 Its routing line must name the actual domain trigger: when user-supplied information, a correction, or a user response relates to this domain, read the preference because recognizing the underlying principle preserves knowledge future decisions can use.
 

package/dist/builtin-memory/insights/listen.md

@@ -1,9 +1,10 @@
 ---
 kind: preference
 when-and-why-to-read: When directly received user material may contain a reusable principle, this preference should be read because knowledge unavailable from model weights should guide future decisions instead of disappearing with the episode.
-system-prompt-visibility: content
-file-read-visibility: none
 rationale: Agents currently miss reusable alpha and sometimes save their own extrapolation without review.
+surfaces:
+  - on: boot
+    at: content
 ---
 
 When directly received user-supplied or user-validated material may contain a coherent reusable principle, follow [[insights/capture]]. Use an active domain listener's boundary when one matches; otherwise use the higher bar: the episode must justify a permanent reusable principle future agents should be routed to, and a new domain needs that principle as its first approved truth. Do not treat approval of an insight review as a fresh candidate, because user knowledge unavailable from model weights should not disappear with the episode.

package/dist/builtin-memory/internal/INDEX.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When you hit a question about how the crtr runtime itself works or how to extend it — how nodes and the canvas behave, where state lives on disk, how to add plugins/commands/marketplaces to crtr, or how the primitives compose into real systems — this index should be read so runtime-sensitive work follows the canonical model instead of fragile inferences from scattered command help.
 short-form: internal/ is the runtime's self- and developer-documentation — operational guides to nodes/canvas and the storage tiers, plugin command and marketplace authoring, plus worked example compositions. Open it to understand how crtr works or to extend it.
-system-prompt-visibility: preview
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: preview
 ---
 
 # internal/ — how the crtr runtime works, and how to extend it
@@ -14,13 +15,13 @@ Open this dir whenever a task turns on understanding the runtime itself or chang
 
 - **nodes-and-canvas** — the agent-runtime model: nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle (mode + lifecycle axes), and revive (manual + daemon auto-revive).
 - **storage-tiers** — where every kind of state lives: the two tiers (scope root and canvas home) and their durability/ownership contracts.
-- **memory-loading** — the memory load model: the two hooks (boot catalog, file-read), the four-rung ladder, gates, applies-to/read-when routing, boot-render ordering, and store mounting/precedence — read when diagnosing why a doc did or didn't load.
+- **memory-loading** — the memory load model: the five surface events, the rung ladder, gates, listings, boot-render ordering, and store mounting/precedence — read when diagnosing why a doc did or didn't load.
 - **agent-shaping** — the when-to-use-which layer over the four dials that shape a node: kinds (the builtin roster, sub-kinds, and custom personas), modes (base vs orchestrator), profiles, and the memory tiers (node/profile/project/user/builtin).
 - **plugins** — authoring a crtr plugin: the plugin.json manifest, directory layout, scopes, install mechanics, versioning, command-capable plugins (contributing top-level CLI commands through commands.json plus an exec or HTTP transport), and bare binaries a plugin or scope puts on every node's PATH.
 - **marketplaces** — authoring a crtr marketplace: the marketplace.json index, local-link and remote-Git plugin sources, auto-bump CI, dual-publishing.
 - **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
 
-Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on that `-h` surface so it surfaces exactly when you write.
+Adjacent, outside this dir: authoring memory documents (kind, surfaces routing, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on that `-h` surface so it surfaces exactly when you write.
 
 Briefly: **plugins** package docs and commands, with command execution selected by `plugin.json.transport` (`exec` for a trusted local executable or `http` for a fetched remote REST manifest); **marketplaces** index and distribute plugins. Plugin commands enter the **external-command** fallthrough, leaving the core fast-path untouched.
 

package/dist/builtin-memory/internal/agent-shaping.md

@@ -2,14 +2,15 @@
 kind: knowledge
 when-and-why-to-read: When you are choosing how to shape a node — which kind to spawn, base vs orchestrator, which profile, or which memory scope a doc belongs in — this reference should be read so each task gets the right role, orchestration depth, identity, and guidance reach instead of paying for a mismatched agent shape.
 short-form: The four orthogonal dials that shape a node — kind (role + model tier), mode (base vs orchestrator), profile (identity + purview), and memory tier (who sees a doc) — plus when to reach for each over its alternatives.
-system-prompt-visibility: name
-file-read-visibility: none
 rationale: Agents pick shaping dials by reflex from the one-line `-h` blurbs and get the discriminators wrong — delegating debugging to explore instead of advisor, grinding an orchestrator-shaped job in base, minting a duplicate memory doc at the wrong scope. The per-kind base docs carry the rationale but only the running node of that kind ever sees them; nothing gave a chooser the cross-cutting "which one, and why it's built this way" view before committing.
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # Agent shaping — kinds, modes, profiles, and memory tiers
 
-Four orthogonal dials shape every node. This is the **when-to-use-which** layer over them — the philosophy of each and how to choose between alternatives. It does not cover mechanics: the node/canvas/lifecycle model is `internal/nodes-and-canvas`, the physical disk layout of every store is `internal/storage-tiers`, and the authoring/routing/visibility contract for memory docs is `crtr memory write -h`. Point at those; this doc decides which dial to turn.
+Four orthogonal dials shape every node. This is the **when-to-use-which** layer over them — the philosophy of each and how to choose between alternatives. It does not cover mechanics: the node/canvas/lifecycle model is `internal/nodes-and-canvas`, the physical disk layout of every store is `internal/storage-tiers`, and the authoring/routing contract for memory docs is `crtr memory write -h`. Point at those; this doc decides which dial to turn.
 
 The dials are independent — you set each without constraining the others:
 
@@ -66,7 +67,7 @@ Reach for a **new** profile when a distinct body of work has its own set of dire
 
 ## Memory tiers — where a doc lives decides who sees it
 
-A memory doc's **scope** is a reach dial: the wider the scope, the more agents pay to carry it, forever. Choose the **narrowest scope that still reaches the next agent who needs it**. Physical paths and durability contracts are in `internal/storage-tiers`; the frontmatter/routing/visibility contract is `crtr memory write -h`. The scopes, narrowest reach to widest:
+A memory doc's **scope** is a reach dial: the wider the scope, the more agents pay to carry it, forever. Choose the **narrowest scope that still reaches the next agent who needs it**. Physical paths and durability contracts are in `internal/storage-tiers`; the frontmatter/routing contract is `crtr memory write -h`. The scopes, narrowest reach to widest:
 
 - **node** (`nodes/<id>/context/memory/`) — only *this* running node sees it; rides its boot context and dies with the node. Scratch memory for one goal's cross-refresh state.
 - **profile** (the profile's own store) — every node running under that profile, across all the dirs in its purview. Cross-repo conventions and the user's stance toward that bundle of work.

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When you want a worked end-to-end composition of crouter primitives — not what one command does but how several combine into a real standing system — open this dir so you can reuse a proven shape instead of re-deriving how the primitives fit or relying on unverified OS assumptions.
 short-form: Worked examples composing crouter primitives into complete systems (like pi's examples/ dir). Currently — the iMessage assistant node.
-system-prompt-visibility: name
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # internal/examples/ — worked compositions of crouter primitives

package/dist/builtin-memory/internal/examples/imessage-assistant.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When you are building a standing assistant node bridged to an external channel — iMessage, email, a chat service — this example should be read so you can reuse a proven event-driven shape and avoid rediscovering macOS messaging traps.
 short-form: Worked example — an always-on iMessage assistant built from crouter primitives. Resident root node + launchd watcher → node message send wakes + chat.db reads + osascript sends + substrate memory.
-system-prompt-visibility: name
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # Example: an iMessage assistant node (OpenClaw-style)

package/dist/builtin-memory/internal/marketplaces.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When creating a crtr marketplace or contributing plugins to one, this knowledge should be read so indexed plugins install and update coherently without release automation desynchronizing their versions.
 short-form: How to author a crtr marketplace — marketplace.json index, plugin entries, symlink-based install, auto-bump CI, dual-publishing. Use when creating a marketplace or contributing plugins to one.
-system-prompt-visibility: name
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # Authoring crtr marketplaces

package/dist/builtin-memory/internal/memory-loading.md

@@ -1,47 +1,58 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need to know why a memory doc did or didn't load — or are deciding how a new doc should surface — this reference should be read because it names the hook, rung, gate, and ordering that produced the behavior, so you fix loading by turning the right dial instead of guessing at frontmatter.
-short-form: The complete load model — two hooks (boot catalog, file-read), the four-rung ladder, gates, applies-to/read-when routing, boot-render ordering, and store mounting/precedence.
-system-prompt-visibility: name
-file-read-visibility: none
+when-and-why-to-read: When you need to know why a memory doc did or didn't load — or are deciding how a new doc should surface — this reference should be read because it names the event, rung, gate, and ordering that produced the behavior, so you fix loading by turning the right dial instead of guessing at frontmatter.
+short-form: The complete load model — the five surface events, the rung ladder, gates, listings, transcript dedup, boot-render ordering, and store mounting/precedence.
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # How memory loads
 
-Every memory doc declares its own loading policy in frontmatter; the runtime never guesses. Loading is two hooks, one four-rung dial per hook, an optional gate, and structural ordering. The authoring contract (flags, routing-line craft) is `crtr memory write -h`; which scope to write to is `internal/agent-shaping`; physical paths are `internal/storage-tiers`. This doc is the mechanics between those: what actually fires, when, and in what order.
+Every memory doc declares its own delivery in frontmatter `surfaces` entries; the runtime never guesses. Delivery is five events, one rung per entry, an optional gate, and structural ordering. The authoring contract (flags, routing-line craft) is `crtr memory write -h`; which scope to write to is `internal/agent-shaping`; physical paths are `internal/storage-tiers`. This doc is the mechanics between those: what actually fires, when, and in what order.
 
-## The two hooks
+## Surfaces entries
 
-- **System prompt** (`system-prompt-visibility`) — the boot catalog assembled into every node's system prompt at revive.
-- **File read** (`file-read-visibility`) — context attached to the workspace or to files. Two events: **workspace mount** during first-message assembly (docs routed `applies-to: "."`), and a later **matching file read** — docs routed by glob, and `.`-routed docs whose store's owning dir contains the read file. Nothing positional fires from where the doc happens to sit on disk — only from its declared route.
+A doc with no `surfaces` does exactly one thing: appears in its directory's listing. Everything beyond that is an explicit entry — `{on: <event>, match?, match-frontmatter?, at: <rung>}`. Entries OR across; multiple entries per event are legal. The events:
 
-Each doc sets both rungs explicitly; there is no kind-based default. Usually one axis carries a real rung and the other is `none`.
+- **boot** — the catalog assembled into every node's system prompt at revive. No match; the entry's presence is the match.
+- **workspace-open** — first-message context when cwd/profile mounts the doc's project store. Project stores only.
+- **read** — a `read` tool call returned a matching file: path globs vs the file's absolute path and basename, `./`-anchored globs vs its path relative to the store's owning repo dir, `match-frontmatter` predicates over the read file's own YAML frontmatter.
+- **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's own name directory.
+- **command** — a matching shell command ran: globs vs the whole command string, `*` crossing `/`. Delivery is post-execution — right for "you are now in this territory," never for "don't run this at all."
+
+Nothing positional fires from where a doc happens to sit on disk — only from its declared entries and its listing.
 
 ## The rung ladder
 
-`none` → `name` → `preview` → `content`, per hook:
+`at` sets how much delivers when an entry fires:
 
-- `none` — invisible on that hook; findable only by search/read. For archival docs and for the unused axis.
-- `name` — the bare title. The practical floor: an agent can't reach for a doc it has never seen named.
+- `name` — the bare title. The practical boot floor: an agent can't reach for a doc it has never seen named.
 - `preview` — name + the `when-and-why-to-read` routing line, rendered verbatim. The heart of progressive disclosure: one sentence that lets an agent decide whether to spend the read.
-- `content` — the full body inlined. Reserved for always-relevant docs that are either a bullet's worth of text or a wholly-important operating guide (the root INDEX shape below).
+- `content` — the full body inlined. Reserved for always-relevant docs that are either a bullet's worth of text or a wholly-important operating guide (the workspace front door below).
+
+Silence is the absence of an entry; there is no `none` rung. `short-form` is **not** a rung and never enters agent context — it exists for the user browsing `crtr memory list`. Disclosure is name → routing line → whole thing; there is deliberately no "just the summary" level, because agents satisfice on abbreviations and never read the rest.
+
+## Gates
+
+An optional `gate` predicates every entry on the node's own config — kind, mode, orchestration depth, scope, cwd — using the standard matcher vocabulary (`crtr memory write -h`). No gate means always eligible. Persona prose is just gated boot-content docs (`gate: {kind: developer, mode: base}`); guidance that should scale with effort is one predicate (`orchestration.depth: {gte: 2}`), not a mechanism.
 
-`short-form` is **not** a rung and never enters agent context — it exists for the user browsing `crtr memory list`. Disclosure is name → routing line → whole thing; there is deliberately no "just the summary" level, because agents satisfice on abbreviations and never read the rest.
+## Listings and dedup
 
-## Gates and read-when
+Reading a doc discloses where it sits: `crtr memory read <doc>` also renders, once per transcript, the listing of the doc's directory and each ancestor — one routing line per member doc, one bare name per subdirectory. `crtr memory read <dir>` (or a bare-dir `[[ref]]`) returns the listing itself; no doc answers for a directory. `unlisted: true` suppresses a doc from every listing. Store roots are never auto-listed — `crtr memory list` is the deliberate root browse.
 
-An optional `gate` predicates visibility on the node's own config — kind, mode, orchestration depth, scope, cwd — using the standard matcher vocabulary (`crtr memory write -h`). No gate means always eligible. Persona prose is just gated content-rung docs (`gate: {kind: developer, mode: base}`); guidance that should scale with effort is one predicate (`orchestration.depth: {gte: 2}`), not a mechanism. `read-when` additionally matches the *read file's* frontmatter on the file-read hook; it refines a route but never replaces the required `applies-to` boundary.
+Every delivery dedups per transcript keyed on (doc, rung), higher rungs piercing lower: a listing line is a preview-rank render, boot renders seed the set at their boot rung, and a content delivery silences everything after it.
 
 ## Store mounting and precedence
 
 At boot/first-message assembly the runtime mounts: builtin docs, the user store (`~/.crouter/memory/`), the selected profile's store, and every project store — ancestor `.crouter/memory/` dirs walking up from cwd plus each project in the profile's purview. Physical duplicates are deduplicated; name collisions resolve nearest-first (project over profile over user over builtin), which is what lets a project doc shadow a builtin one.
 
-A root `INDEX.md` is a workspace's front door: `system-prompt-visibility: none`, `file-read-visibility: content`, `applies-to: "."` — the operating guide loads when that workspace mounts, not in every boot catalog. Multiple mounted roots render broad-to-specific, each under its own envelope name.
+A workspace's front door is an ordinary doc carrying the entry pair `{on: workspace-open, at: content}` + `{on: read, match: "./**", at: content}` — the operating guide loads when that workspace mounts or its files are read, not in every boot catalog. `crtr memory lint` requires exactly one workspace-open content doc per profile-managed project store. Multiple mounted roots render broad-to-specific.
 
-A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its `.`-routed docs, deduplicated against everything already in the transcript. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's `system-prompt-visibility` rung is inert (lint warns; set `none`).
+A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, deduplicated against everything already in the transcript. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).
 
 ## Ordering
 
-The boot render is structural, never a per-doc knob: docs group by rung (content bodies as prose, then previews, then names), and within a group order general-to-specific — scope first (builtin → user → profile → outermost project root → nearest), then tree position (higher directories before deeper), then filename. A numeric `NN-` filename prefix (stripped from the doc's name) is the sparing escape hatch when an exact sequence must be pinned.
+The boot render is structural, never a per-doc knob: docs group by boot rung (content bodies as prose, then previews, then names), and within a group order general-to-specific — scope first (builtin → user → profile → outermost project root → nearest), then tree position (higher directories before deeper), then filename. A numeric `NN-` filename prefix (stripped from the doc's name) is the sparing escape hatch when an exact sequence must be pinned.
 
-`crtr memory lint` is the validator for all of the above: frontmatter schema, both rungs present, routes on every non-`none` file-read rung, rung-scaled body length, dangling `[[links]]`, and each profile-managed project's front door.
+`crtr memory lint` is the validator for all of the above: frontmatter schema, strict `surfaces` entries, rung-scaled body length, dangling `[[links]]`, and each profile-managed project's front door.

package/dist/builtin-memory/internal/nodes-and-canvas.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When you are operating the canvas — spawning or steering nodes, deciding how work reports up, recovering a dormant or crashed node, or reasoning about the daemon — this reference should be read so lifecycle and reporting operations preserve one live engine, deliver results reliably, and recover nodes without corrupting state.
 short-form: Operational model of the agent runtime — nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle states, and revive (manual + daemon auto-revive).
-system-prompt-visibility: name
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # How nodes and the canvas work (operational)

package/dist/builtin-memory/internal/plugins.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When creating a crtr plugin, packaging memory docs for distribution, adding top-level CLI commands via a command manifest, or debugging install/resolution, this knowledge should be read so installs resolve predictably across scopes and command surfaces do not fail from manifest drift or protocol mistakes.
 short-form: How to author a crtr plugin — plugin.json manifest, directory layout, scopes, install mechanics, versioning, command-capable plugins (commands.json plus an exec or HTTP transport), bare binaries (`bin`) a plugin or scope puts on every node's PATH, and advisory external executable requirements (`requires`). Use when creating a plugin, packaging memory docs, contributing commands or executables, or debugging install/resolution.
-system-prompt-visibility: name
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # Authoring crtr plugins
@@ -32,7 +33,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
 └── memory/
     ├── <name>.md                    # a kind:knowledge or kind:preference doc
     └── <area>/
-        ├── INDEX.md                 # optional — a dir surfaces as one entry at its INDEX rung
+        ├── INDEX.md                 # optional — an ordinary doc; a bare-dir read answers with the listing
         └── <name>.md
 ```
 
@@ -71,7 +72,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 
 ## Plugin kinds
 
-A plugin can ship a complete persona kind: declare the registry entry in the manifest's `kinds` block, and author the persona prose as ordinary plugin memory docs gated `{kind: <name>, mode: base}` (and `{kind: <name>, mode: orchestrator}`) with `system-prompt-visibility: content` — the same shape a builtin kind uses at `kinds/<kind>/00-base.md`. Nothing else is needed: gates evaluate uniformly over plugin docs, so the persona splices into any node launched with that kind.
+A plugin can ship a complete persona kind: declare the registry entry in the manifest's `kinds` block, and author the persona prose as ordinary plugin memory docs gated `{kind: <name>, mode: base}` (and `{kind: <name>, mode: orchestrator}`) surfaced `{on: boot, at: content}` — the same shape a builtin kind uses at `kinds/<kind>/00-base.md`. Nothing else is needed: gates evaluate uniformly over plugin docs, so the persona splices into any node launched with that kind.
 
 `readMergedLaunchConfig` layers an enabled plugin's `kinds` entries directly above the builtin registry and below its host scope's own `config.json` — full precedence: builtin → user-scope plugins → user config → profile → per project root (that root's plugins → that root's config). So a plugin kind appears in `crtr node new -h` and is launchable like any other, and a user or project `config.json` can still patch or shadow it. Plugins within one scope layer name-sorted; the scope's own config always wins.
 
@@ -157,7 +158,7 @@ Standard semver:
 
 `crtr pkg plugin disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin enable <name>`.
 
-Individual memory docs inside an enabled plugin are hidden by setting their frontmatter visibility rungs to `none` (or a gate that fails), not by a command — see `crtr memory write -h`.
+Individual memory docs inside an enabled plugin are hidden by giving them no `surfaces` entries plus `unlisted: true` (or a gate that fails), not by a command — see `crtr memory write -h`.
 
 ## What goes in a plugin
 
@@ -319,7 +320,7 @@ Two contributors at the same precedence claiming one name is a collision, not a
 - When the plugin (or a scope `config.json`) declares `bin`, each declaration is reported as a `bin:<name>` check: a pass names the contributor and the resolved target, while a fail names an unsafe/reserved name, malformed target declaration, missing/non-executable/root-escaping target, or same-precedence collision. Contributed binaries are never executed during validation. Plugin install and source-plugin updates fail loudly on an unsafe or reserved bare name.
 - When an enabled plugin declares `requires`, each `requires:<name>` check names the plugin and resolved executable path on pass, or carries its install hint as remediation on fail. The executable is never run; a malformed declaration fails source-plugin install and update, while an absent executable remains advisory.
 
-`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
+`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, valid `surfaces` entries. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
 
 ## Cross-publishing with Claude Code
 

package/dist/builtin-memory/internal/storage-tiers.md

@@ -3,9 +3,10 @@ name: internal/storage-tiers
 kind: knowledge
 description: Where crouter state belongs
 when-and-why-to-read: When locating crtr state or deciding where a new file belongs, this reference should be read so files are found or placed in the storage tier with the right ownership and durability.
-system-prompt-visibility: name
-file-read-visibility: none
 short-form: The two crtr storage tiers — scope root for durable user/repo content and canvas home for node-graph runtime state, node artifacts, and human tickets.
+surfaces:
+  - on: boot
+    at: name
 ---
 
 # Where everything lives (the two storage tiers)

package/dist/builtin-memory/plan/roadmap.md

@@ -2,11 +2,12 @@
 kind: knowledge
 when-and-why-to-read: When shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation, this knowledge should be read so implementation receives a right-sized, parallel-safe execution map whose gaps are caught while they are still cheap to fix.
 short-form: Use when shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation.
-system-prompt-visibility: preview
-file-read-visibility: none
 gate: {kind: plan}
 rationale: >-
   The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment.
+surfaces:
+  - on: boot
+    at: preview
 ---
 
 # Planning Playbook

package/dist/builtin-memory/spec/guide.md

@@ -2,8 +2,6 @@
 kind: knowledge
 when-and-why-to-read: When eliciting or writing a specification, this knowledge should be read because downstream design and planning need settled intent without making the user answer avoidable questions or forcing every request through the same ceremony.
 short-form: Elicit only consequential uncertainty, then write a right-sized behavioral contract a downstream reader can use without guessing.
-system-prompt-visibility: none
-file-read-visibility: none
 rationale: Specification quality and elicitation guidance lived inside an always-loaded spec persona while the lightweight /spec command had almost none, leaving agents to choose between a vague one-shot and a fixed discovery workflow.
 ---
 

package/dist/builtin-memory/spec/requirements.md

@@ -2,8 +2,6 @@
 kind: knowledge
 when-and-why-to-read: When writing or evaluating requirements, this knowledge should be read because implementation and validation need one complete behavioral contract rather than behavior scattered across design prose or silently filled in by the planner.
 short-form: Write complete, atomic, observable, testable requirements; use formal templates only when they make a conditional behavior clearer.
-system-prompt-visibility: none
-file-read-visibility: none
 rationale: The requirements persona made EARS mandatory and omitted behavior already stated by the design, which could produce a gap list instead of the complete behavioral contract downstream work needs.
 ---
 

package/dist/builtin-memory/spec/roadmap.md

@@ -2,10 +2,11 @@
 kind: knowledge
 when-and-why-to-read: When a specification effort contains independent discovery, design, or requirements surfaces large enough for worthwhile parallel work, this knowledge should be read because the handoffs must preserve one settled contract without turning sequential reasoning into coordination ceremony.
 short-form: Orchestrate a specification only for worthwhile parallel work, using canonical artifacts rather than conversation context for handoffs.
-system-prompt-visibility: preview
-file-read-visibility: none
 gate: {kind: spec}
 rationale: The prior roadmap required every large specification to follow exact stages, fresh-window yields, fixed delegation, and user approval gates; the resulting process treated ceremony as the quality bar instead of the clarity of the finished contract.
+surfaces:
+  - on: boot
+    at: preview
 ---
 
 # Orchestrating a specification

package/dist/builtin-memory/testing.md

@@ -2,8 +2,6 @@
 kind: knowledge
 when-and-why-to-read: When a repo has no recorded testing stance and you must decide whether a change carries a test, this knowledge should be read because eliciting the standard once and storing it settles every later change in that repo instead of each agent guessing differently and leaving the owner to strip out unwanted coverage.
 short-form: How to produce a repo's testing-stance memory — read what the repo already shows, draft a stance from that evidence, get the owner to confirm it, and store it.
-system-prompt-visibility: none
-file-read-visibility: none
 rationale: >-
   Agents defaulted to a coverage-first instinct in repos that had deliberately chosen otherwise, and to the opposite absolute in repos that wanted coverage — each inventing a stance rather than taking the repo's. The missing move was procedural, not a rule: read the standard the repo already shows, and when it shows none, ask once and store the answer where the next agent inherits it.
 ---
@@ -38,4 +36,4 @@ Put the draft to the owner through `crtr human send`, as one question answerable
 
 Save the confirmed stance as a `testing-stance` preference in that repo's own project store (`crtr memory write -h`), so every agent working there inherits it and no one repeats this workflow. Keep it to what earns a test, what proves a change instead, and the local-versus-CI split with any per-test bound — the decision, never the conversation that produced it.
 
-A one-or-two-sentence stance belongs at the `content` rung on the boot axis, because the decision it governs — should this change carry a test — happens before any test file is opened. Route it through file context instead only for conventions that matter while editing a test, matched to the repo's own test globs.
+A one-or-two-sentence stance belongs in a `{on: boot, at: content}` entry, because the decision it governs — should this change carry a test — happens before any test file is opened. Route it through a read entry instead only for conventions that matter while editing a test, matched to the repo's own test globs.

package/dist/builtin-memory/wedged-child-on-runaway-bash.md

@@ -2,8 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When a node is marked wedged or remains active without progress while its inbox accumulates, this reference should be read so recovery restores progress without losing context or killing the wrong process.
 short-form: A node stuck mid-turn is detected from a stale busy heartbeat plus near-zero process-tree CPU. Kill a runaway subprocess when one exists; when the broker itself is stuck, the daemon SIGTERMs it and applies bounded, conditional recovery.
-system-prompt-visibility: preview
-file-read-visibility: none
+surfaces:
+  - on: boot
+    at: preview
 ---
 
 A base node can wedge mid-turn on a runaway bash command (for example, an unbounded recursive scan from `/`). Its pi turn cannot push or finish while the tool call is blocked.

package/dist/builtin-pi-packages/pi-crtr-extensions/README.md

@@ -36,7 +36,7 @@ directory's `node_modules/`.
 | `provider-rotation.ts` | Subscription credential rotation across Anthropic / OpenAI-Codex: does its own OAuth login/refresh, rotates on rate-limits, falls back across the model ladder. Registers `/provider-sub <provider> <list\|add\|select\|rm>`. |
 | `crtr-commands/` | Auto-generates a slash command per `crtr` CLI node. The tree is derived in-process from crtr's own `buildRoot()` (no subprocesses, no cache on disk); `filters.json` controls which nodes are exposed. |
 | `sysprompt-window.ts` | Registers `/sysprompt`, which runs `crtr sys sysprompt --window` without injecting the prompt into context. |
-| `frontmatter-rules/` | Injects `.pi/rules/*.md` whose `when:` frontmatter matches a read markdown file. `.claude/rules` are migrated into substrate docs with `applies-to` via `crtr sys sync project-guidance`. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
+| `frontmatter-rules/` | Injects `.pi/rules/*.md` whose `when:` frontmatter matches a read markdown file. `.claude/rules` are migrated into substrate docs with read-glob `surfaces` entries via `crtr sys sync project-guidance`. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
 | `statusline.ts` | Custom status line. |
 | `strip-skills-docs.ts` | Trims skill docs from context. |
 

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/index.ts

@@ -5,9 +5,9 @@
  * whose YAML frontmatter satisfies a rule's `when:` condition. This is the
  * inverse of a PATH-glob rule (matched on the document's location, not its
  * content): here the *content* of the read document (its frontmatter) decides
- * which rules apply, not the document's path. Path-glob rules now live as
- * substrate docs with `applies-to` (see `crtr sys sync project-guidance`'s
- * `.claude/rules` migration), not as a sibling pi-extension.
+ * which rules apply, not the document's path. Path-glob rules live as
+ * substrate docs with read-glob `surfaces` entries (see `crtr sys sync
+ * project-guidance`'s `.claude/rules` migration), not as a sibling pi-extension.
  *
  * Rule files live in `.pi/rules/*.md` (walked up the read file's ancestor
  * chain, so a project-root rules dir governs everything beneath it) plus a

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -29,7 +29,6 @@ interface MemoryListItem {
   name: string;
   path: string;
   short_form: string;
-  is_dir: boolean;
   slash: boolean;
 }
 
@@ -55,7 +54,6 @@ async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
     name: doc.name,
     path: doc.path,
     short_form: doc.shortForm,
-    is_dir: doc.isDir,
     slash: doc.slash,
   }));
 
@@ -64,7 +62,7 @@ async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
   // precedence). Resolve all eligible names against one source snapshot.
   const seen = new Set<string>();
   const names = items.flatMap((item) => {
-    if (item.is_dir || seen.has(item.name)) return [];
+    if (seen.has(item.name)) return [];
     seen.add(item.name);
     return item.slash === true ? [item.name] : [];
   });
@@ -98,7 +96,6 @@ export async function discoverSlashDocs(): Promise<SlashDoc[]> {
   const seen = new Set<string>();
   const out: SlashDoc[] = [];
   for (const item of items) {
-    if (item.is_dir) continue;
     if (seen.has(item.name)) continue;
     seen.add(item.name);
     if (item.slash) {