@north-light/crouter 0.3.208 → 0.3.210

package/dist/commands/memory/lint.js

@@ -13,27 +13,29 @@ import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/res
 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 { isDocKind, normalizeDocName, resolveDocName, RUNGS } from '../../core/substrate/schema.js';
-import { displayName } from '../../core/substrate/ceiling.js';
+import { isDocKind, normalizeDocName, parseSubstrateFrontmatter, resolveDocName, SURFACE_EVENTS, SURFACE_RUNGS, } from '../../core/substrate/schema.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { descendantStoreRoots } from '../../core/nested-stores.js';
-const VALID_RUNGS = [...RUNGS];
-const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
+/** The four retired visibility-axis fields. The cut is hard: an old-format doc
+ *  fails loudly and names the migration, never gets a dual-parse fallback. */
+const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
+/** The frontmatter keys one `surfaces` entry may carry. */
+const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'at'];
 /** Rung-scaled body-length caps, measured in WORDS (frontmatter excluded).
  *  Words, not lines: house style writes each paragraph as ONE logical line
  *  and lets the editor soft-wrap, so a line count measures wrapping style
  *  rather than context cost — words track what the reader actually pays.
  *
- *  `content` on the system axis inlines the whole body into every agent's
- *  system prompt at boot; `preview`/`content` on the file-read axis surface
- *  the whole body through a workspace mount or a matching file read — both
- *  cap at 1000 words. `preview` on the system axis routes a deliberate
+ *  A `boot` entry at `content` inlines the whole body into every agent's
+ *  system prompt; a `content` entry on any other event (workspace-open, read,
+ *  memory-read, command) surfaces the whole body whenever the entry fires —
+ *  both cap at 1000 words. A `boot` entry at `preview` routes a deliberate
  *  reader into the whole body, so its cap is the longest doc worth reading
- *  end-to-end (calibrated to the humanizer doc, 2936 words). `name`/`none`
- *  rungs never cap: such a doc is only reached deliberately (browse or a
- *  [[link]]), so its length is the reader's choice. The strictest
- *  applicable cap wins.
+ *  end-to-end (calibrated to the humanizer doc, 2936 words). `name` entries
+ *  and surface-less docs never cap: such a doc is only reached deliberately
+ *  (a listing, browse, or a [[link]]), so its length is the reader's choice.
+ *  The strictest applicable cap wins.
  *
  *  Persona layers — canonical names under `kinds/`, the docs the prompt
  *  render composes into an agent's persona — are structurally exempt: an
@@ -42,9 +44,9 @@ const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
  *  deliberate and per-doc: `lint-ignore: length` in the frontmatter,
  *  surfaced ONLY by the finding itself — never advertised in authoring
  *  help. */
-const SYSTEM_CONTENT_MAX_WORDS = 1000;
-const FILE_READ_MAX_WORDS = 1000;
-const SYSTEM_PREVIEW_MAX_WORDS = 3000;
+const BOOT_CONTENT_MAX_WORDS = 1000;
+const EVENT_CONTENT_MAX_WORDS = 1000;
+const BOOT_PREVIEW_MAX_WORDS = 3000;
 /** A routing line costs more than it saves for a short rule or fact. */
 const PREVIEW_TO_CONTENT_MAX_WORDS = 30;
 /** Rules a doc may suppress via frontmatter `lint-ignore`. */
@@ -57,24 +59,28 @@ function countBodyWords(body) {
     const trimmed = body.trim();
     return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
 }
-/** The length rule. Caps are computed from the RAW rung strings — an invalid
- *  rung already fails the schema check, so it simply matches no cap here.
- *  `docName` is the doc's canonical resolver identity (explicit frontmatter
- *  `name`, else the normalized path-derived name) — persona layers under
- *  `kinds/` are recognized by it and never capped. */
+/** The doc's surfaces entries as the runtime will read them. Used by the cap
+ *  checks AFTER the strict schema check has run — for a doc that passes it,
+ *  the tolerant parse and the strict contract agree. */
+function parsedSurfaces(fm) {
+    return parseSubstrateFrontmatter(fm)?.surfaces ?? [];
+}
+/** Warn when a body short enough to inline still pays a routing line. */
 export function lintShortPreviewBody(fm, body) {
     const words = countBodyWords(body);
     if (words >= PREVIEW_TO_CONTENT_MAX_WORDS)
         return null;
-    const previewAxes = [
-        fm['system-prompt-visibility'] === 'preview' ? 'system-prompt-visibility' : undefined,
-        fm['file-read-visibility'] === 'preview' ? 'file-read-visibility' : undefined,
-    ].filter((axis) => axis !== undefined);
-    if (previewAxes.length === 0)
+    const previewEvents = [...new Set(parsedSurfaces(fm).filter((e) => e.at === 'preview').map((e) => e.on))];
+    if (previewEvents.length === 0)
         return null;
-    const verb = previewAxes.length === 1 ? 'is' : 'are';
-    return `body is ${words} words but ${previewAxes.join(' and ')} ${verb} \`preview\`; use \`content\` on that axis so agents receive the whole rule without a separate memory read`;
+    const noun = previewEvents.length === 1 ? 'entry delivers' : 'entries deliver';
+    return `body is ${words} words but the ${previewEvents.join('/')} ${noun} \`preview\`; use \`at: content\` so agents receive the whole rule without a separate memory read`;
 }
+/** The length rule. Caps are computed from the parsed entries — an invalid
+ *  entry already fails the schema check, so it simply matches no cap here.
+ *  `docName` is the doc's canonical resolver identity (explicit frontmatter
+ *  `name`, else the normalized path-derived name) — persona layers under
+ *  `kinds/` are recognized by it and never capped. */
 export function lintBodyLength(fm, body, docName) {
     if (ignoresRule(fm, 'length'))
         return null;
@@ -83,28 +89,78 @@ export function lintBodyLength(fm, body, docName) {
     // construction — persona length is persona design, never an authoring smell.
     if (docName === 'kinds' || docName.startsWith('kinds/'))
         return null;
-    const sys = fm['system-prompt-visibility'];
-    const file = fm['file-read-visibility'];
+    const entries = parsedSurfaces(fm);
     const words = countBodyWords(body);
-    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs saved at `none` visibility on both axes (the link is how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off “further evidence”, examples, or references — a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
-    if (sys === 'content' && words > SYSTEM_CONTENT_MAX_WORDS) {
-        return `body is ${words} words but system-prompt-visibility: content inlines every word into every agent's system prompt at boot — capped at ${SYSTEM_CONTENT_MAX_WORDS} words (system-prompt preview gets ${SYSTEM_PREVIEW_MAX_WORDS}; name/none are never capped on that axis). ${remedy}`;
+    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs carrying no surfaces at all (the listing and the link are how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off “further evidence”, examples, or references — a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
+    if (entries.some((e) => e.on === 'boot' && e.at === 'content') && words > BOOT_CONTENT_MAX_WORDS) {
+        return `body is ${words} words but a boot entry at \`content\` inlines every word into every agent's system prompt — capped at ${BOOT_CONTENT_MAX_WORDS} words (boot preview gets ${BOOT_PREVIEW_MAX_WORDS}; name entries are never capped). ${remedy}`;
     }
-    if ((file === 'content' || file === 'preview') && words > FILE_READ_MAX_WORDS) {
-        return `body is ${words} words, over the ${FILE_READ_MAX_WORDS}-word cap for file-read routed rungs (file-read-visibility: preview|content surfaces the whole body through a workspace mount or a matching file read; name/none are never capped on that axis). ${remedy}`;
+    const contentEvents = [...new Set(entries.filter((e) => e.on !== 'boot' && e.at === 'content').map((e) => e.on))];
+    if (contentEvents.length > 0 && words > EVENT_CONTENT_MAX_WORDS) {
+        return `body is ${words} words, over the ${EVENT_CONTENT_MAX_WORDS}-word cap for a \`content\` entry on ${contentEvents.join('/')} (the whole body delivers every time the entry fires; name entries are never capped). ${remedy}`;
     }
-    if (sys === 'preview' && words > SYSTEM_PREVIEW_MAX_WORDS) {
-        return `body is ${words} words, over the ${SYSTEM_PREVIEW_MAX_WORDS}-word cap for system-prompt preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; system-prompt content is capped at ${SYSTEM_CONTENT_MAX_WORDS} words; name/none are never capped on that axis). ${remedy}`;
+    if (entries.some((e) => e.on === 'boot' && e.at === 'preview') && words > BOOT_PREVIEW_MAX_WORDS) {
+        return `body is ${words} words, over the ${BOOT_PREVIEW_MAX_WORDS}-word cap for boot preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; boot content is capped at ${BOOT_CONTENT_MAX_WORDS} words; name entries are never capped). ${remedy}`;
+    }
+    return null;
+}
+/** Strict validation of a raw `surfaces` value — the mirror of `coerceSurface`
+ *  in shared.ts: everything the runtime parser would silently drop or trim is
+ *  an error here. Returns the first problem found, or null. */
+function lintSurfacesField(v) {
+    if (v === undefined)
+        return null;
+    if (!Array.isArray(v))
+        return `invalid surfaces: ${JSON.stringify(v)} (expected a list of {on, at, match?, match-frontmatter?} entries)`;
+    for (const raw of v) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return `invalid surfaces entry: ${JSON.stringify(raw)} (expected an {on, at, match?, match-frontmatter?} object)`;
+        }
+        const rec = raw;
+        for (const key of Object.keys(rec)) {
+            if (!SURFACE_ENTRY_KEYS.includes(key)) {
+                return `invalid surfaces entry: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, at)`;
+            }
+        }
+        const on = rec['on'];
+        if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on)) {
+            return `invalid surfaces entry \`on\`: ${JSON.stringify(on)} (expected ${SURFACE_EVENTS.join('|')})`;
+        }
+        const at = rec['at'];
+        if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at)) {
+            return `invalid surfaces entry \`at\`: ${JSON.stringify(at)} (expected ${SURFACE_RUNGS.join('|')})`;
+        }
+        let hasMatch = false;
+        if (rec['match'] !== undefined) {
+            if (on === 'boot' || on === 'workspace-open') {
+                return `invalid surfaces entry: \`match\` is meaningless on \`${on}\` — the entry's presence is the match; drop it`;
+            }
+            const m = rec['match'];
+            const globs = typeof m === 'string' ? [m] : Array.isArray(m) && m.every((g) => typeof g === 'string') ? m : null;
+            if (globs === null || globs.length === 0 || globs.some((g) => g.trim() === '')) {
+                return `invalid surfaces entry \`match\`: ${JSON.stringify(m)} (expected a non-empty glob or non-empty glob list)`;
+            }
+            hasMatch = true;
+        }
+        const mf = rec['match-frontmatter'];
+        if (mf !== undefined) {
+            if (on !== 'read')
+                return 'invalid surfaces entry: `match-frontmatter` is a `read`-event predicate only';
+            if (mf === null || typeof mf !== 'object' || Array.isArray(mf)) {
+                return `invalid surfaces entry \`match-frontmatter\`: ${JSON.stringify(mf)} (expected a field→matcher object)`;
+            }
+        }
+        if ((on === 'read' || on === 'memory-read' || on === 'command') && !hasMatch && mf === undefined) {
+            return `invalid surfaces entry: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`;
+        }
     }
     return null;
 }
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
- *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
- *  REQUIRED — there is no kind default to lean on, so a missing rung is an
- *  authoring error. Rung and gate values are checked RAW — the runtime parser
- *  silently falls back to the neutral floor / inert gates, which is exactly the
- *  silent tolerance this lint exists to catch at authoring time. */
+ *  error here (elsewhere it just means "not a substrate doc"). Fields are
+ *  checked RAW — the runtime parser silently drops invalid entries, which is
+ *  exactly the silent tolerance this lint exists to catch at authoring time. */
 export function lintSubstrateSchema(fm) {
     if (fm === null)
         return 'missing frontmatter: a memory store doc requires `kind: knowledge|preference`';
@@ -120,52 +176,22 @@ export function lintSubstrateSchema(fm) {
     if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
         return 'missing `when-and-why-to-read`: one routing line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
     }
-    for (const field of RUNG_FIELDS) {
-        const v = fm[field];
-        if (v === undefined) {
-            return `missing ${field}: choose a rung explicitly (${RUNGS.join('|')}) — there is no kind default`;
-        }
-        if (typeof v !== 'string' || !VALID_RUNGS.includes(v)) {
-            return `invalid ${field}: ${JSON.stringify(v)} (expected ${RUNGS.join('|')})`;
+    for (const field of RETIRED_FIELDS) {
+        if (field in fm) {
+            return `retired \`${field}\` key: the visibility axes were replaced by \`surfaces\` event routing — run \`crtr sys migrate\` to convert old-format docs, or author \`surfaces\` entries by hand (\`crtr memory write -h\`)`;
         }
     }
+    const unlisted = fm['unlisted'];
+    if (unlisted !== undefined && typeof unlisted !== 'boolean') {
+        return `invalid unlisted: ${JSON.stringify(unlisted)} (expected a boolean)`;
+    }
+    const surfacesError = lintSurfacesField(fm['surfaces']);
+    if (surfacesError !== null)
+        return surfacesError;
     const gate = fm.gate;
     if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
         return `invalid gate: ${JSON.stringify(gate)} (expected a field→matcher object)`;
     }
-    const appliesTo = fm['applies-to'];
-    let appliesToGlobs;
-    if (appliesTo !== undefined) {
-        if (typeof appliesTo === 'string') {
-            appliesToGlobs = [appliesTo];
-        }
-        else if (Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string')) {
-            appliesToGlobs = appliesTo;
-        }
-        else {
-            return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected one non-empty file glob or a non-empty list of file globs)`;
-        }
-        if (appliesToGlobs.length === 0 || appliesToGlobs.some((glob) => glob.trim() === '')) {
-            return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected one non-empty file glob or a non-empty list of file globs)`;
-        }
-    }
-    // read-when (Stream A on-read frontmatter trigger): same well-formed-object
-    // contract as gate — a non-object is inert (never fires), so catch it here.
-    const readWhen = fm['read-when'];
-    if (readWhen !== undefined && (readWhen === null || typeof readWhen !== 'object' || Array.isArray(readWhen))) {
-        return `invalid read-when: ${JSON.stringify(readWhen)} (expected a field→matcher object)`;
-    }
-    // Every authored file-read surface needs an explicit event boundary. Runtime
-    // parsing stays tolerant so one bad doc cannot break an agent's context.
-    if (fm['file-read-visibility'] !== 'none' && appliesToGlobs === undefined) {
-        return `missing applies-to: file-read-visibility is \`${fm['file-read-visibility']}\`, so this memory must declare when it surfaces. Use \`applies-to: "."\` for context loaded when cwd or a selected profile mounts this project store and on any file read beneath the store's owning dir, use a non-empty file glob (or YAML list) for context loaded only after a matching file is read, or set \`file-read-visibility: none\` when this memory has no file-context route. File globs match the read file's absolute path, basename, or path relative to the memory's owning project root. \`read-when\` matches file metadata but does not replace the required workspace/file boundary. Run \`crtr memory write -h\` before changing routing frontmatter.`;
-    }
-    // A dead on-read trigger: an explicit applies-to/read-when with nothing to
-    // surface (file-read-visibility none) can never fire — flag it loudly rather
-    // than store a silent no-op.
-    if (fm['file-read-visibility'] === 'none' && (appliesTo !== undefined || readWhen !== undefined)) {
-        return 'dead on-read trigger: applies-to/read-when is set but file-read-visibility is `none` — raise the rung or drop the trigger';
-    }
     const slash = fm.slash;
     if (slash !== undefined && typeof slash !== 'boolean') {
         return `invalid slash: ${JSON.stringify(slash)} (expected a boolean)`;
@@ -214,27 +240,64 @@ function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbac
         const shortPreviewWarning = lintShortPreviewBody(fm, body);
         if (shortPreviewWarning !== null)
             warnings.push(`${file}: ${shortPreviewWarning}`);
+        // An over-broad memory-read glob fires on EVERY memory read — almost
+        // always an authoring accident, so flag it without failing the corpus.
+        for (const entry of parsedSurfaces(fm)) {
+            if (entry.on !== 'memory-read')
+                continue;
+            for (const glob of entry.match ?? []) {
+                if (glob === '**' || glob === '*') {
+                    warnings.push(`${file}: memory-read glob \`${glob}\` fires on every memory read — scope it to a name subtree`);
+                }
+            }
+        }
     }
     for (const name of docLinkNames(body)) {
         if (!corpusNames.has(name)) {
             findings.push({
                 path: file,
-                error: `dangling doc link [[${name}]]: no memory document has that exact canonical name — retarget the link (\`crtr memory find ${name.split('/').pop()}\`) or drop it`,
+                error: `dangling doc link [[${name}]]: no memory document or directory has that exact canonical name — retarget the link (\`crtr memory find ${name.split('/').pop()}\`) or drop it`,
             });
         }
     }
 }
+/** The files in a project store carrying a workspace front-door entry
+ *  ({on: workspace-open, at: content}). Raw fm scan; a missing store or an
+ *  unparseable doc contributes zero (the YAML failure is its own finding). */
+function frontDoorDocs(storeDir) {
+    const hits = [];
+    if (!pathExists(storeDir))
+        return hits;
+    for (const file of walkFiles(storeDir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
+        if (basename(file) === 'MEMORY.md')
+            continue;
+        let fm;
+        try {
+            fm = parseFrontmatterGeneric(readText(file)).data;
+        }
+        catch {
+            continue;
+        }
+        if (fm === null)
+            continue;
+        const entries = parsedSurfaces(fm);
+        if (entries.some((e) => e.on === 'workspace-open' && e.at === 'content'))
+            hits.push(file);
+    }
+    return hits;
+}
+const FRONT_DOOR_REMEDY = 'author the project\'s operating guide as an ordinary doc with `surfaces: [{on: workspace-open, at: content}, {on: read, match: "./**", at: content}]`; run `crtr memory write -h` first';
 export const lintLeaf = defineLeaf({
     name: 'lint',
     description: 'validate frontmatter and body length across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML, substrate schema violation, body longer than its visibility rung earns, or dangling `[[canonical/name]]` doc link; also validates the root INDEX.md front door of every project managed by the selected profile and warns when an unprofiled working directory has no front door. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML, substrate schema violation (including retired visibility fields and malformed `surfaces` entries), body longer than its delivery entries earn, or dangling `[[canonical/name]]` doc link; also validates that every project managed by the selected profile has exactly one workspace front door and warns when an unprofiled working directory has none. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
     help: {
         name: 'memory lint',
-        summary: 'strict-parse the bounded memory corpus and validate project root INDEX front doors',
+        summary: 'strict-parse the bounded memory corpus and validate project workspace front doors',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for a root INDEX.md front door)}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for a workspace front door)}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
             { name: 'warnings', type: 'string[]', required: true, constraint: 'Non-fatal authoring gaps detected for the directory where lint ran.' },
         ],
@@ -254,13 +317,17 @@ export const lintLeaf = defineLeaf({
         //    path never yields a doc name, so e.g. the maintainer store shipped
         //    at builtin-memory/.crouter can never register) — lint must not
         //    flag files the substrate can never load.
-        // Exact canonical names in the current resolvable corpus. INDEX docs also
-        // expose their folded bare-directory name (`taste`, not `taste/INDEX`).
+        // The resolvable link targets: exact doc names, plus every proper name
+        // prefix — a bare-dir [[ref]] is a legal listing link (`crtr memory read
+        // <dir>` answers with the directory listing).
         const corpusNames = new Set();
         for (const doc of listAllMemoryDocs(undefined, true, true)) {
-            const canonical = displayName(doc.name);
-            if (canonical !== '')
-                corpusNames.add(canonical);
+            if (doc.name === '')
+                continue;
+            corpusNames.add(doc.name);
+            const segs = doc.name.split('/');
+            for (let i = 1; i < segs.length; i++)
+                corpusNames.add(segs.slice(0, i).join('/'));
         }
         const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
@@ -281,9 +348,9 @@ export const lintLeaf = defineLeaf({
                     lintDir(pluginMemoryDir(plugin));
             }
         }
-        // Nested descendant stores: same schema gate, plus a boot-rung warning —
-        // the boot catalog deliberately never includes nested stores, so a
-        // system-prompt-visibility above `none` there is an inert rung.
+        // Nested descendant stores: same schema gate, plus a boot-entry warning —
+        // the boot catalog deliberately never includes nested stores, so a boot
+        // surfaces entry there is inert.
         for (const root of descendantStoreRoots(projectScopeRoots())) {
             const dir = join(root, 'memory');
             lintDir(dir);
@@ -299,9 +366,8 @@ export const lintLeaf = defineLeaf({
                 catch {
                     continue; // invalid YAML is already a finding from lintDir
                 }
-                const sys = fm?.['system-prompt-visibility'];
-                if (sys !== undefined && sys !== 'none') {
-                    warnings.push(`${file}: nested-store docs never ride the boot catalog, so this \`system-prompt-visibility\` rung is inert — set \`none\``);
+                if (fm !== null && parsedSurfaces(fm).some((e) => e.on === 'boot')) {
+                    warnings.push(`${file}: nested-store docs never ride the boot catalog, so its boot surfaces entries are inert — drop them`);
                 }
             }
         }
@@ -312,10 +378,11 @@ export const lintLeaf = defineLeaf({
                     lintDir(pluginMemoryDir(plugin));
             }
         }
-        // Profile coverage: each managed project has one direct root INDEX front
-        // door. It enters first-message context through the workspace-open `.`
-        // route, so its exact contract is knowledge + system none/file content +
-        // applies-to containing `.`.
+        // Profile coverage: each managed project has exactly ONE workspace front
+        // door — a doc carrying {on: workspace-open, at: content}, the guide that
+        // enters first-message context when cwd/profile mounts the store. Zero
+        // means agents open the workspace blind; two means both deliver whole at
+        // every open, and the store needs consolidating.
         let profileProjects = 0;
         let profileResolved = false;
         const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
@@ -326,38 +393,18 @@ export const lintLeaf = defineLeaf({
                 lintDir(profileMemoryDir(profileId));
                 for (const dir of manifest.projects) {
                     profileProjects += 1;
-                    const indexPath = join(dir, '.crouter', 'memory', 'INDEX.md');
-                    if (!pathExists(indexPath)) {
+                    const doors = frontDoorDocs(join(dir, '.crouter', 'memory'));
+                    if (doors.length === 0) {
                         findings.push({
                             path: dir,
-                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/INDEX.md root front door — author INDEX in that exact project with kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to "."; run \`crtr memory write -h\` first`,
+                            error: `profile "${manifest.name}" manages this dir but no doc in its .crouter/memory carries a {on: workspace-open, at: content} surfaces entry — ${FRONT_DOOR_REMEDY}`,
                         });
-                        continue;
-                    }
-                    try {
-                        const fm = parseFrontmatterGeneric(readText(indexPath)).data;
-                        const problems = [];
-                        if (fm?.kind !== 'knowledge')
-                            problems.push('kind must be `knowledge`');
-                        if (fm?.['system-prompt-visibility'] !== 'none')
-                            problems.push('system-prompt-visibility must be `none`');
-                        if (fm?.['file-read-visibility'] !== 'content')
-                            problems.push('file-read-visibility must be `content`');
-                        const applies = fm?.['applies-to'];
-                        const globs = typeof applies === 'string'
-                            ? [applies]
-                            : Array.isArray(applies) && applies.every((value) => typeof value === 'string')
-                                ? applies
-                                : [];
-                        if (!globs.some((glob) => glob.trim() === '.'))
-                            problems.push('applies-to must include `.`');
-                        if (problems.length > 0) {
-                            findings.push({ path: indexPath, error: `invalid project root front door: ${problems.join('; ')}` });
-                        }
                     }
-                    catch (e) {
-                        const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-                        findings.push({ path: indexPath, error: `invalid project root front door YAML: ${msg}` });
+                    else if (doors.length > 1) {
+                        findings.push({
+                            path: dir,
+                            error: `multiple workspace front doors (${doors.length}): ${doors.join(', ')} — exactly one doc per project store may carry {on: workspace-open, at: content}; consolidate the others into it or lower their entries`,
+                        });
                     }
                 }
             }
@@ -369,9 +416,8 @@ export const lintLeaf = defineLeaf({
         // Without a selected, resolvable profile there is no managed-project
         // finding to carry this signal, so keep a non-fatal cwd adoption warning.
         if (!profileResolved) {
-            const workingDirectoryIndex = join(workingDirectory, '.crouter', 'memory', 'INDEX.md');
-            if (!pathExists(workingDirectoryIndex)) {
-                warnings.push(`${workingDirectory}: no .crouter/memory/INDEX.md root front door — author INDEX for this project with kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to "."; run \`crtr memory write -h\` first`);
+            if (frontDoorDocs(join(workingDirectory, '.crouter', 'memory')).length === 0) {
+                warnings.push(`${workingDirectory}: no workspace front door — ${FRONT_DOOR_REMEDY}`);
             }
         }
         const checked = memoryCount;
@@ -388,7 +434,7 @@ export const lintLeaf = defineLeaf({
                 checked,
                 findings: findings.map((f) => ({ path: f.path, error: f.error })),
                 warnings,
-                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate; route every non-`none` file-read rung with `applies-to: "."` for workspace-open context plus reads beneath the store\'s owning dir, or a non-empty file glob for matching reads; otherwise use file-read-visibility `none`; retarget or drop dangling [[links]]; split an over-length body into [[linked]] `none`-visibility reference docs); make every profile-managed project root INDEX match the front-door contract; then re-run `crtr memory lint`.',
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind; run `crtr sys migrate` for retired visibility fields; give each surfaces entry a valid on/at and the match its event requires; retarget or drop dangling [[links]]; split an over-length body into [[linked]] surface-less reference docs); give every profile-managed project exactly one workspace front door; then re-run `crtr memory lint`.',
             });
         }
         return {

package/dist/commands/memory/list.d.ts

@@ -8,7 +8,6 @@ export interface ListedMemoryDoc {
     scope: MemoryScope;
     path: string;
     shortForm: string;
-    isDir: boolean;
     slash: boolean;
 }
 export declare function listMemoryDocs(kindFilter?: string, scopeFilter?: MemoryScope, quiet?: boolean, docs?: readonly MemoryDoc[]): ListedMemoryDoc[];

package/dist/commands/memory/list.js

@@ -1,7 +1,6 @@
 import { defineLeaf } from '../../core/command.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/schema.js';
-import { isIndexName, indexDirOf } from '../../core/substrate/ceiling.js';
 import { paginate } from '../../core/pagination.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
 export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = listAllMemoryDocs(scopeFilter, quiet, true)) {
@@ -21,15 +20,7 @@ export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = li
             continue;
         if (kindFilter !== undefined && sub.kind !== kindFilter)
             continue;
-        // A directory INDEX surfaces as a dir entry: its dir path with a trailing
-        // slash, flagged is_dir, so the inventory distinguishes it from a doc. A
-        // store-root INDEX has no dir path, so it keeps its canonical `INDEX`
-        // name — every name in this column must be one `crtr memory read` and a
-        // `[[link]]` accept, and a bare `/` is neither.
-        const isDir = isIndexName(sub.name);
-        const dirPath = isDir ? indexDirOf(sub.name) : '';
-        const name = dirPath === '' ? sub.name : dirPath + '/';
-        addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir, slash: sub.slash });
+        addItem({ name: sub.name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, slash: sub.slash });
     }
     items.sort((a, b) => {
         const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -57,7 +48,7 @@ export const listLeaf = defineLeaf({
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document: {name, short_form, kind, scope, is_dir}. path is included only with --paths. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash, or `INDEX` for a store-root INDEX that has no directory path); is_dir is false for an ordinary doc. Every name is readable as-is with `crtr memory read`. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document: {name, short_form, kind, scope}. path is included only with --paths. Every name is readable as-is with `crtr memory read` (a directory segment of a name is readable too — it answers with the directory listing). short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Opaque token for the next page; null means no more items.' },
             { name: 'total', type: 'integer | null', required: true, constraint: 'Exact total across all pages when cheap to compute (always cheap here); never null in practice for this leaf.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
@@ -81,7 +72,6 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
-                is_dir: d.isDir,
                 ...(includePaths ? { path: d.path } : {}),
             })),
             next_cursor: result.next_cursor,

package/dist/commands/memory/move.d.ts

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