@north-light/crouter 0.3.222 → 0.3.224

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

@@ -9,11 +9,11 @@ surfaces:
 
 # How memory loads
 
-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.
+Every memory doc declares its own delivery in frontmatter `surfaces` entries; the runtime never guesses. Delivery is five events, one rung per entry, document and entry gates, 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.
 
 ## Surfaces entries
 
-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:
+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?, gate?, at: <rung>}`. An entry's event constraints and optional node-config `gate` must both match; participating entries OR across and fold to their highest rung (`content` > `preview` > `name`), with no cross-entry deny precedence. Multiple entries per event are legal. The events:
 
 - **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.
@@ -35,7 +35,7 @@ Silence is the absence of an entry; there is no `none` rung. `short-form` is **n
 
 ## 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.
+A document-level `gate` is the hard eligibility predicate over the node's own config — kind, mode, orchestration depth, scope, cwd — using the standard matcher vocabulary (`crtr memory write -h`). When it fails, no automatic surface delivers the document. An optional `gate` on an individual surface entry applies the same predicate language only to that entry, so one document can choose a different rung by node kind. 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.
 
 ## Listings and dedup
 
@@ -49,7 +49,7 @@ At boot/first-message assembly the runtime mounts: builtin docs, the user store
 
 Each project the selected profile has a relationship with carries a `memory` value — `none`, `name`, `preview`, or `content` — and that value is the maximum rung anything in that project's stores delivers at boot and workspace-open, whatever directory the node is working in. It only lowers: an entry authored below the maximum delivers at its authored rung. `none` contributes nothing to either automatic event, so a `none` project cannot shadow a same-named doc from a wider scope — that wider doc becomes the winner. A project store the selected profile has no relationship with delivers exactly what it authored.
 
-The maximum reaches those two events and nothing else. Read, memory-read, and command entries fire at their authored rungs; directory listings, `crtr memory read`, `crtr memory find`, config resolution, and plugin discovery all see the full corpus. An explicit `crtr memory read` is itself a content delivery, so reading a capped doc returns its whole body and records content — the upgrade path for a doc the automatic events disclosed only by name or preview.
+The maximum reaches those two events and nothing else. Read, memory-read, and command entries fire at their authored rungs; directory listings, `crtr memory read`, `crtr memory find`, config resolution, and plugin discovery all see the full corpus. An explicit `crtr memory read` is itself a content delivery, so reading a capped or document-gated doc returns its whole body and records content — the upgrade path for a doc the automatic events disclosed only by name or preview. Entry gates apply to companion docs routed by the `memory-read` event, not to the deliberate read or its listings.
 
 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.