@north-light/crouter 0.3.207 → 0.3.209

package/dist/commands/memory/shared.js

@@ -3,21 +3,19 @@
 // scope modules and build their documented output objects on top of the small
 // helpers here. Nothing in this file forks on kind or re-implements the
 // schema/gate/resolver — it only composes them.
-import { existsSync, realpathSync, statSync } from 'node:fs';
-import { join, resolve as resolvePath } from 'node:path';
+import { existsSync, readdirSync, realpathSync, rmdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
+import { SURFACE_EVENTS, SURFACE_RUNGS } from '../../core/substrate/schema.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
 // `--kind` enum choices everywhere.
 export const MEMORY_KINDS = ['knowledge', 'preference'];
-// Visibility rungs — how much of a document surfaces (none → name → preview →
-// content). Shared by --system-prompt-visibility and --file-read-visibility.
-export const VISIBILITY_RUNGS = ['none', 'name', 'preview', 'content'];
 // Scope choices for filtering / targeting (builtin is read-only, not writable).
 // `node` is the this-node store, writable only inside a running node.
 export const MEMORY_SCOPES = ['user', 'project', 'profile', 'node'];
@@ -115,6 +113,22 @@ export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
         throw usage(`no ${scope} scope available for writing memory documents`);
     return { scope, memoryDir };
 }
+/** Remove a just-removed file's now-empty parent directories up to (never
+ *  including) its tree root, so removing the last entry under an `area/`
+ *  prefix does not orphan an empty directory. The root is derived by walking
+ *  up one dirname per name segment: a doc named `a/b` sits at `<root>/a/b.md`,
+ *  so its root is two dirnames above — the same arithmetic holds for a
+ *  `.history/<name>.jsonl` sidecar. Stops at the first non-empty ancestor. */
+export function pruneEmptyParents(filePath, nameSegments) {
+    let treeRoot = filePath;
+    for (let i = 0; i < nameSegments; i += 1)
+        treeRoot = dirname(treeRoot);
+    let dir = dirname(filePath);
+    while (dir !== treeRoot && dir.startsWith(treeRoot) && existsSync(dir) && readdirSync(dir).length === 0) {
+        rmdirSync(dir);
+        dir = dirname(dir);
+    }
+}
 /** Map a path-derived name (`topic` or `area/topic`) to its file path under a
  *  memory dir, guarding against traversal/absolute escapes. */
 export function memoryFilePath(memoryDir, name) {
@@ -147,29 +161,72 @@ export function coerceGate(raw) {
     }
     return result;
 }
-/** Coerce a `--read-when` string into a predicate tree. Like `--gate`, the
- *  read-when field MUST be a YAML/JSON object (the field→matcher map the schema
- *  expects, evaluated against a read file's own frontmatter). A scalar/array
- *  read-when is inert (never matches), so passing one is always a mistake and is
- *  caught at authoring time rather than stored. */
-export function coerceReadWhen(raw) {
-    const result = parseYamlObject(raw);
-    if (typeof result === 'string') {
-        throw usage(`--read-when must be a YAML/JSON object (field→matcher map over a read file's frontmatter): ${result}. ` +
-            `Example: --read-when '{tags: {contains: security}}'`);
+// The frontmatter keys one `surfaces` entry may carry.
+const SURFACE_ENTRY_KEYS = new Set(['on', 'match', 'match-frontmatter', 'at']);
+/** Coerce one `--surface` value into a validated surfaces entry. Strict where
+ *  the runtime parser is tolerant: a flag that would be silently dropped or
+ *  trimmed at render time is an authoring mistake and fails HERE. The entry is
+ *  returned in canonical key order with a single glob kept as a bare string,
+ *  so the stored YAML stays as compact as the flag that authored it. */
+export function coerceSurface(raw) {
+    const parsed = yamlParse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw usage(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?}, got ${JSON.stringify(parsed)}. ` +
+            `Example: --surface '{on: read, match: "src/**", at: content}'`);
     }
-    return result;
-}
-/** Coerce repeatable `--applies-to` values (already an array from the argv
- *  parser) to the schema's glob form: one value stays a bare string, several
- *  become an array. Each value is trimmed; empty entries are rejected loudly
- *  (a silently-dropped glob is a routing bug waiting to happen). */
-export function coerceAppliesTo(values) {
-    const cleaned = values.map((v) => v.trim());
-    if (cleaned.some((v) => v.length === 0)) {
-        throw usage('--applies-to values must not be empty');
+    const rec = parsed;
+    for (const key of Object.keys(rec)) {
+        if (!SURFACE_ENTRY_KEYS.has(key)) {
+            throw usage(`--surface: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, at)`);
+        }
+    }
+    const on = rec['on'];
+    if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on)) {
+        throw usage(`--surface: invalid \`on\`: ${JSON.stringify(on)} (expected ${SURFACE_EVENTS.join('|')})`);
+    }
+    const at = rec['at'];
+    if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at)) {
+        throw usage(`--surface: invalid \`at\`: ${JSON.stringify(at)} (expected ${SURFACE_RUNGS.join('|')})`);
     }
-    return cleaned.length === 1 ? cleaned[0] : cleaned;
+    let match;
+    if (rec['match'] !== undefined) {
+        if (on === 'boot' || on === 'workspace-open') {
+            throw usage(`--surface: \`match\` is meaningless on \`${on}\` — the entry's presence is the match; drop it`);
+        }
+        if (typeof rec['match'] === 'string') {
+            const t = rec['match'].trim();
+            if (t === '')
+                throw usage('--surface: `match` must be a non-empty glob or a non-empty glob list');
+            match = t;
+        }
+        else if (Array.isArray(rec['match'])) {
+            const globs = rec['match'].map((g) => (typeof g === 'string' ? g.trim() : ''));
+            if (globs.length === 0 || globs.some((g) => g === '')) {
+                throw usage('--surface: `match` must be a non-empty glob or a non-empty glob list');
+            }
+            match = globs.length === 1 ? globs[0] : globs;
+        }
+        else {
+            throw usage(`--surface: invalid \`match\`: ${JSON.stringify(rec['match'])} (expected a glob string or list)`);
+        }
+    }
+    const matchFrontmatter = rec['match-frontmatter'];
+    if (matchFrontmatter !== undefined) {
+        if (on !== 'read')
+            throw usage('--surface: `match-frontmatter` is a `read`-event predicate only');
+        if (matchFrontmatter === null || typeof matchFrontmatter !== 'object' || Array.isArray(matchFrontmatter)) {
+            throw usage(`--surface: invalid \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`);
+        }
+    }
+    if ((on === 'read' || on === 'memory-read' || on === 'command') && match === undefined && matchFrontmatter === undefined) {
+        throw usage(`--surface: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`);
+    }
+    return {
+        on,
+        ...(match !== undefined ? { match } : {}),
+        ...(matchFrontmatter !== undefined ? { 'match-frontmatter': matchFrontmatter } : {}),
+        at,
+    };
 }
 // Canonical frontmatter field order for a substrate document. Known fields come
 // first in this order; any preserved-on-update extras append after. `origin` is
@@ -179,11 +236,10 @@ const FRONTMATTER_ORDER = [
     'kind',
     'when-and-why-to-read',
     'short-form',
-    'system-prompt-visibility',
-    'file-read-visibility',
+    'unlisted',
+    'surfaces',
     'gate',
-    'applies-to',
-    'read-when',
+    'slash',
     'rationale',
     'last-updated',
     'origin',
@@ -208,8 +264,8 @@ export function buildOrigin() {
 }
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
- *  package — the same one the parser uses — so nested gate maps and applies-to
- *  arrays round-trip), in canonical field order with preserved extras last. */
+ *  package — the same one the parser uses — so nested gate maps and surfaces
+ *  entry lists round-trip), in canonical field order with preserved extras last. */
 export function serializeMemoryDoc(frontmatter, body) {
     const ordered = {};
     for (const key of FRONTMATTER_ORDER) {
@@ -267,11 +323,9 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     'kind': { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Document kind.' },
     'when-and-why-to-read': { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader\u2019s payoff \u2014 the consequence they secure for their task by reading \u2014 NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview.' },
     'short-form': { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form \u2014 a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
-    'system-prompt-visibility': { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
-    'file-read-visibility': { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Every value except none also requires at least one applies-to route in the resulting document.' },
+    'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
+    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to the doc’s own name directory. Constraints within one entry AND together; entries OR together.' },
     'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
-    'applies-to': { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence; the flag set replaces the document\u2019s whole route list. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly AND on any file read beneath the store\u2019s owning dir. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. There is no positional fallback from where the memory file lives. Required whenever file-read-visibility is not none.' },
-    'read-when': { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when \u2014 YAML/JSON object predicate over a read file\u2019s own frontmatter using the same field/matcher vocabulary described in the guide.' },
     'slash': { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
 };
 /** One overlay flag, with leaf-specific prose appended to the shared
@@ -288,7 +342,7 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export const DOC_RATIONALE_CONSTRAINT = 'Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.';
-export const GUIDE_VISIBILITY_RUNGS = 'The visibility rungs `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc fits in a single sentence \u2014 a one-line preference or a one-sentence knowledge fact \u2014 skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
+export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (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` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
 export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
-export const GUIDE_PREDICATE_VOCABULARY = 'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
-export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.';
+export const GUIDE_PREDICATE_VOCABULARY = 'Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
+export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.';

package/dist/commands/memory/write.js

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { writeText, pathExists } from '../../core/fs-utils.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_VISIBILITY_RUNGS, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceAppliesTo, coerceReadWhen, overlayParam, serializeMemoryDoc, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceSurface, overlayParam, serializeMemoryDoc, } from './shared.js';
 // A topic's memory set stays usable only when authors treat cohesion as a creation
 // gate; otherwise small corrections accumulate as overlapping leaves whose routing
 // lines cannot tell a future reader which one owns the topic.
@@ -16,15 +16,15 @@ export const writeLeaf = defineLeaf({
         guide: 'Every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
-            GUIDE_VISIBILITY_RUNGS + '\n\n' +
+            GUIDE_SURFACES + '\n\n' +
             'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
-            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". Its envelope name comes from the owning project directory unless the document already carries an explicit name. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
-            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog; file-read visibility fires on the applies-to routes. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
+            'A workspace front door is an ordinary doc carrying the entry pair {on: workspace-open, at: content} plus {on: read, match: "./**", at: content}: it enters first-message context when cwd/profile mounts its project store and fires on any file read beneath the store’s owning dir. Target the exact project with --dir. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` enforces exactly one such doc per project store managed by the selected profile.\n\n' +
+            'Choose the hook — boot vs read. A boot entry rides the boot catalog every agent sees; a read entry fires only when a matching file is actually read. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it off boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so skip read entries and route it through boot instead.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything. ' + GUIDE_ROUTING_LINE + '\n\n' +
             GUIDE_PREDICATE_VOCABULARY + '\n\n' +
             GUIDE_DOC_LINKS + '\n\n' +
-            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
-            'A directory INDEX earns existence only where the aggregate view beats the sum of per-file rungs. Aggregated child routing is automatic: `crtr memory read` of a directory INDEX appends every member’s routing line (`[[name]]: <when-and-why-to-read>`), so never author that list in the body. Two shapes pass: synthesis — an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single child can carry — and a pure gate — one preview line covering a cluster with one shared routing condition, the body adding nothing the automatic list does not. Otherwise skip the INDEX and let each doc’s own rung route it: frontmatter routing lines are self-maintaining, while an INDEX body describing its children is a hand-maintained copy that drifts. Never write an INDEX body that restates child names, paraphrases their routing lines, fronts a small directory of sharply named docs, or summarizes children a reader should open.\n\n' +
+            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Give reference leaves no surfaces at all — the directory listing and the link from the main doc are how they are found, so any routing entry just double-charges every boot or read for depth the graph already routes. Keep every doc as short as its job allows; `crtr memory lint` caps body length by delivery rung and its findings carry the split guidance.\n\n' +
+            'A directory needs no index doc: reading a directory name returns its listing — each member’s routing line — so never author a doc that merely lists, fronts, or paraphrases its siblings. Write a directory-level doc only for synthesis: an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single member can carry. Guided entrance into a topic is an ordinary member doc, found through the listing like any other.\n\n' +
             'Find before write. Prefer slightly expanding an existing document with `crtr memory edit`, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is stamped here and preserved by every later revision. Run `crtr memory lint` after authoring.\n\n' +
             '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.\n\n' +
             'Revise an existing doc with `crtr memory edit`.',
@@ -33,11 +33,9 @@ export const writeLeaf = defineLeaf({
             overlayParam('kind', { required: true }),
             overlayParam('when-and-why-to-read', { required: true }),
             overlayParam('short-form'),
-            overlayParam('system-prompt-visibility', { required: true }, 'There is no kind default; pick a rung explicitly.'),
-            overlayParam('file-read-visibility', { required: true }, 'There is no kind default; pick a rung explicitly.'),
+            overlayParam('unlisted'),
+            overlayParam('surface'),
             overlayParam('gate'),
-            overlayParam('applies-to'),
-            overlayParam('read-when'),
             overlayParam('slash'),
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
@@ -89,32 +87,26 @@ export const writeLeaf = defineLeaf({
         };
         setIf('when-and-why-to-read', input['whenAndWhyToRead']);
         setIf('short-form', input['shortForm']);
-        setIf('system-prompt-visibility', input['systemPromptVisibility']);
-        setIf('file-read-visibility', input['fileReadVisibility']);
+        if (input['unlisted'] === true)
+            frontmatter['unlisted'] = true;
+        if (input['surface'] !== undefined) {
+            frontmatter['surfaces'] = input['surface'].map(coerceSurface);
+        }
         if (input['gate'] !== undefined)
             frontmatter['gate'] = coerceGate(input['gate']);
-        if (input['appliesTo'] !== undefined) {
-            frontmatter['applies-to'] = coerceAppliesTo(input['appliesTo']);
-        }
-        if (input['readWhen'] !== undefined) {
-            frontmatter['read-when'] = coerceReadWhen(input['readWhen']);
-        }
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['rationale']);
         // One field consumers read for recency, live from the first byte.
         frontmatter['last-updated'] = origin['created'];
-        const applies = frontmatter['applies-to'];
-        const routes = typeof applies === 'string'
-            ? [applies]
-            : Array.isArray(applies) && applies.every((value) => typeof value === 'string')
-                ? applies
-                : [];
-        if (frontmatter['file-read-visibility'] !== 'none' && routes.length === 0) {
-            throw usage(`file-read-visibility ${String(frontmatter['file-read-visibility'])} requires --applies-to: use "." for project workspace/profile-open context, a real file glob for matching reads, or choose file-read-visibility none`);
-        }
-        if (scope !== 'project' && routes.some((route) => route.trim() === '.')) {
-            throw usage('applies-to "." is a project-store workspace mount route; use a real file glob or choose file-read-visibility none for user, profile, and node memory');
+        // A workspace-open entry fires only when cwd/profile mounts the doc's
+        // project store, so outside project scope it is a dead route — reject it
+        // at authoring time.
+        const surfacesVal = frontmatter['surfaces'];
+        if (scope !== 'project' &&
+            Array.isArray(surfacesVal) &&
+            surfacesVal.some((e) => e !== null && typeof e === 'object' && e['on'] === 'workspace-open')) {
+            throw usage('a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one — drop the entry or write to a project store');
         }
         const after = serializeMemoryDoc(frontmatter, body);
         writeText(path, after);
@@ -127,11 +119,9 @@ export const writeLeaf = defineLeaf({
             'kind',
             ...(input['whenAndWhyToRead'] !== undefined ? ['when-and-why-to-read'] : []),
             ...(input['shortForm'] !== undefined ? ['short-form'] : []),
-            ...(input['systemPromptVisibility'] !== undefined ? ['system-prompt-visibility'] : []),
-            ...(input['fileReadVisibility'] !== undefined ? ['file-read-visibility'] : []),
+            ...(input['unlisted'] === true ? ['unlisted'] : []),
+            ...(input['surface'] !== undefined ? ['surfaces'] : []),
             ...(input['gate'] !== undefined ? ['gate'] : []),
-            ...(input['appliesTo'] !== undefined ? ['applies-to'] : []),
-            ...(input['readWhen'] !== undefined ? ['read-when'] : []),
             ...(input['slash'] === true ? ['slash'] : []),
             ...(input['rationale'] !== undefined ? ['rationale'] : []),
         ];

package/dist/commands/memory.js

@@ -1,12 +1,13 @@
 // `crtr memory` subtree — the document substrate (knowledge and preferences)
-// accessed via the CLI. Flat leaves: list, read, find, write, edit, history,
-// delete, origin, lint.
+// accessed via the CLI. Flat leaves: list, read, find, write, edit, move,
+// history, delete, origin, lint.
 import { defineBranch } from '../core/command.js';
 import { listLeaf } from './memory/list.js';
 import { readLeaf } from './memory/read.js';
 import { findLeaf } from './memory/find.js';
 import { writeLeaf } from './memory/write.js';
 import { editLeaf } from './memory/edit.js';
+import { moveLeaf } from './memory/move.js';
 import { historyLeaf } from './memory/history.js';
 import { deleteLeaf } from './memory/delete.js';
 import { originLeaf } from './memory/origin.js';
@@ -22,8 +23,8 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `delete` removes, and `history` reads how a document reached its current state. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content).',
         },
-        children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
     });
 }

package/dist/commands/pkg/browse/catalog.js

@@ -360,12 +360,10 @@ function docDetails(plugin) {
                 ...(parsed.whenAndWhyToRead !== "" ? { routingLine: parsed.whenAndWhyToRead } : {}),
                 path: parsed.path,
                 ...(sizeBytes !== undefined ? { sizeBytes } : {}),
-                systemPromptVisibility: parsed.systemPromptVisibility,
-                fileReadVisibility: parsed.fileReadVisibility,
+                surfaces: parsed.surfaces,
+                unlisted: parsed.unlisted,
                 slash: parsed.slash,
-                ...(parsed.appliesTo !== undefined ? { appliesTo: parsed.appliesTo } : {}),
                 ...(parsed.gate !== undefined ? { gate: parsed.gate } : {}),
-                ...(parsed.readWhen !== undefined ? { readWhenPredicate: parsed.readWhen } : {}),
                 ...(parsed.rationale !== undefined ? { rationale: parsed.rationale } : {}),
                 body: parsed.body,
             }];

package/dist/commands/pkg/browse/doc-view.js

@@ -19,21 +19,27 @@ export function renderDocView(doc, width) {
     }
     out.push("", theme.fg("dim", "READ WHEN"));
     out.push(...paragraph(doc.routingLine || "Not declared.", viewWidth));
-    // The two rungs always answer "will an agent ever see this?", so they are
-    // always shown. The qualifiers below them are shown only when the doc sets
-    // one — a column of `none` says nothing, and a `read when  none` row sitting
-    // under a filled READ WHEN section reads as a contradiction.
-    out.push("", theme.fg("dim", "VISIBILITY"));
-    out.push(...field("system prompt", doc.systemPromptVisibility, viewWidth));
-    out.push(...field("file read", doc.fileReadVisibility, viewWidth));
+    // One row per surfaces entry answers "will an agent ever see this?"; a doc
+    // with none is reachable through listings and explicit reads only, and the
+    // qualifiers below are shown only when the doc sets one.
+    out.push("", theme.fg("dim", "ROUTING"));
+    if (doc.surfaces.length === 0) {
+        out.push(...paragraph("No surfaces — reachable through directory listings and explicit reads only.", viewWidth));
+    }
+    for (const entry of doc.surfaces) {
+        const parts = [`at ${entry.at}`];
+        if (entry.match?.length)
+            parts.push(entry.match.join(", "));
+        if (entry.matchFrontmatter !== undefined)
+            parts.push(JSON.stringify(entry.matchFrontmatter));
+        out.push(...field(entry.on, parts.join("  "), viewWidth));
+    }
+    if (doc.unlisted)
+        out.push(...field("unlisted", "suppressed from directory listings", viewWidth));
     if (doc.slash)
         out.push(...field("slash", `/${doc.name.replaceAll("/", ":")}`, viewWidth));
-    if (doc.appliesTo?.length)
-        out.push(...field("applies to", doc.appliesTo.join(", "), viewWidth));
     if (doc.gate !== undefined)
         out.push(...field("gate", JSON.stringify(doc.gate), viewWidth));
-    if (doc.readWhenPredicate !== undefined)
-        out.push(...field("read-when predicate", JSON.stringify(doc.readWhenPredicate), viewWidth));
     if (doc.rationale) {
         out.push("", theme.fg("dim", "RATIONALE"));
         out.push(...paragraph(doc.rationale, viewWidth));

package/dist/commands/pkg/browse/model.d.ts

@@ -1,5 +1,5 @@
 import type { Field, InputParam } from "../../../core/help.js";
-import type { Rung } from "../../../core/substrate/schema.js";
+import type { SurfaceEntry } from "../../../core/substrate/schema.js";
 import type { OwnerRef, Scope } from "../../../types.js";
 /** The scopes that can hold a marketplace, and that a plugin can be installed
  *  into. Narrower than `Scope`: `builtin` names plugins that ship with crtr, and
@@ -87,18 +87,16 @@ export interface DocDetail {
     /** Absolute path to the `.md` on disk. */
     path: string;
     sizeBytes?: number;
-    /** How much of the doc surfaces at boot, and on a related file read. */
-    systemPromptVisibility: Rung;
-    fileReadVisibility: Rung;
+    /** Frontmatter `surfaces`: explicit event-routing entries — when the doc
+     *  delivers, and how much. Empty = reachable through listings and explicit
+     *  reads only. */
+    surfaces: SurfaceEntry[];
+    /** Frontmatter `unlisted`: suppressed from directory listings. */
+    unlisted: boolean;
     /** Invocable as a pi slash command (`slash: true`). */
     slash: boolean;
-    /** Frontmatter `applies-to`: explicit file-context routes. */
-    appliesTo?: string[];
     /** Frontmatter `gate`: eligibility predicate over the node's config. */
     gate?: Record<string, unknown>;
-    /** Frontmatter `read-when`: predicate over a READ FILE's own frontmatter.
-     *  Unrelated to `routingLine` despite the neighbouring names. */
-    readWhenPredicate?: Record<string, unknown>;
     /** Frontmatter `rationale`: the observed failure the doc exists to close.
      *  Maintainer-facing — never delivered to a reading agent. */
     rationale?: string;

package/dist/commands/sys/migrate.d.ts

@@ -0,0 +1 @@
+export declare const sysMigrateLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/migrate.js

@@ -0,0 +1,106 @@
+// `crtr sys migrate` — the convergent-lane state-migration runner: converge
+// every writable memory store's documents to the current document format.
+// (Journaled canvas-db migrations run in the db's own ordered chain when the
+// daemon opens it; this leaf owns only the on-disk document stores.)
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
+import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
+import { descendantStoreRoots } from '../../core/nested-stores.js';
+import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
+import { runConvergentMigrations } from '../../migrations/convergent.js';
+/** Every writable memory store — the lint corpus minus builtin (package-owned,
+ *  regenerated on every install, so migrating it would fight the package). */
+function migratableStoreDirs() {
+    const dirs = new Set();
+    const add = (dir) => {
+        // realpath so one store reached through two spellings (e.g. a symlinked
+        // ancestor) migrates once.
+        if (dir !== null && dir !== '' && pathExists(dir))
+            dirs.add(realpathOrSelf(dir));
+    };
+    const projectRoots = projectScopeRoots();
+    for (const root of projectRoots) {
+        add(join(root, 'memory'));
+        for (const plugin of listInstalledPluginsInRoot('project', root)) {
+            if (plugin.enabled)
+                add(pluginMemoryDir(plugin));
+        }
+    }
+    for (const root of descendantStoreRoots(projectRoots))
+        add(join(root, 'memory'));
+    add(scopeMemoryDir('user'));
+    for (const plugin of listInstalledPlugins('user')) {
+        if (plugin.enabled)
+            add(pluginMemoryDir(plugin));
+    }
+    const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
+    if (profileIdOrName) {
+        try {
+            const { profileId } = loadProfileManifest(profileIdOrName);
+            add(profileMemoryDir(profileId));
+        }
+        catch {
+            // Unresolvable profile: no profile store to migrate.
+        }
+    }
+    const nodeId = process.env['CRTR_NODE_ID'] ?? '';
+    if (nodeId !== '')
+        add(nodeMemoryDir(nodeId));
+    return [...dirs];
+}
+export const sysMigrateLeaf = defineLeaf({
+    name: 'migrate',
+    description: 'converge every writable memory store to the current document format',
+    whenToUse: 'after a crtr update whose release notes name a document-format migration, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over a current corpus changes nothing, so use --dry-run first only when you want to review the rewrite.',
+    help: {
+        name: 'sys migrate',
+        summary: 'run the registered document-format migrations over every writable memory store',
+        params: [
+            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Plan and report every rewrite without writing any file.' },
+        ],
+        output: [
+            { name: 'stores', type: 'number', required: true, constraint: 'Memory stores scanned.' },
+            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be).' },
+            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files in a store: {store, migration, files}. Empty when the corpus is already current.' },
+            { name: 'skipped', type: 'object[]', required: true, constraint: 'Docs left untouched because their frontmatter is not valid YAML: {store, relPath, error}. Fix the doc, then re-run.' },
+            { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was written (preview only).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: project (plus nested descendant stores and installed plugin stores), user, profile, and this node\'s store. Builtin docs are package-owned and never touched.',
+            'Under --dry-run: read-only, writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const dryRun = input.dryRun === true;
+        const applied = [];
+        const skipped = [];
+        const stores = migratableStoreDirs();
+        for (const store of stores) {
+            const result = runConvergentMigrations(store, { dryRun });
+            for (const row of result.applied)
+                applied.push({ store, migration: row.migration, files: row.files });
+            for (const s of result.skipped)
+                skipped.push({ store, relPath: s.relPath, error: s.error });
+        }
+        const changed = applied.reduce((n, row) => n + row.files.length, 0);
+        return {
+            stores: stores.length,
+            changed,
+            applied,
+            skipped,
+            dryRun,
+            follow_up: skipped.length > 0
+                ? 'Some docs have invalid YAML frontmatter and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
+                : changed === 0
+                    ? 'Corpus already current — nothing to rewrite.'
+                    : dryRun
+                        ? 'Preview only — re-run without --dry-run to write these changes.'
+                        : undefined,
+        };
+    },
+});

package/dist/commands/sys/sync-deps.js

@@ -186,10 +186,8 @@ const CONTROLLED_FIELDS = [
     'kind',
     'when-and-why-to-read',
     'short-form',
-    'system-prompt-visibility',
-    'file-read-visibility',
-    'applies-to',
-    'read-when',
+    'unlisted',
+    'surfaces',
     'gate',
     'rationale',
 ];
@@ -367,8 +365,7 @@ export function runDepsSync(opts) {
                 'short-form': entry.description !== ''
                     ? condenseDescription(entry.description)
                     : `Vendored agent doc shipped by ${entry.pkg}.`,
-                'system-prompt-visibility': 'name',
-                'file-read-visibility': 'none',
+                surfaces: [{ on: 'boot', at: 'name' }],
                 'source-package': `${entry.pkg}@${entry.version}`,
                 ...passthroughFm(entry.fm),
             };
@@ -391,8 +388,7 @@ export function runDepsSync(opts) {
                 kind: 'knowledge',
                 'when-and-why-to-read': `When ${parentName} links to this file, this knowledge should be read because it carries the linked supporting reference.`,
                 'short-form': firstHeading(body) ?? `Supporting reference vendored from ${entry.pkg}.`,
-                'system-prompt-visibility': 'name',
-                'file-read-visibility': 'none',
+                surfaces: [{ on: 'boot', at: 'name' }],
                 'source-package': `${entry.pkg}@${entry.version}`,
                 ...passthroughFm(sourceFm),
             };
@@ -428,8 +424,7 @@ export function runDepsSync(opts) {
         'short-form': emptyCatalog
             ? 'No dependency-shipped agent docs are currently vendored.'
             : "Generated catalog of the agent docs shipped inside this project's npm dependencies.",
-        'system-prompt-visibility': 'preview',
-        'file-read-visibility': 'none',
+        surfaces: [{ on: 'boot', at: 'preview' }],
         'generated-by': DEPS_GENERATED_MARKER,
     };
     const indexBody = emptyCatalog