@north-light/crouter 0.3.217 → 0.3.218

package/dist/commands/human/shared.js

@@ -3,7 +3,7 @@ import { CORE_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.
 // The reader's missing context is the gap syntax cannot close: an inbox page
 // is opened away from the conversation that produced it, by someone who never
 // followed the work.
-const PAGE_BRIEF = 'Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names the topic; subtitle states the decision, your recommendation, and the stakes. Content carries only what is needed to decide, with the evidence behind it below the ask rather than ahead of it. Ask only what changes your next step, and offer only options you would actually take. A page that asks nothing states what happened and what it changes.';
+const PAGE_BRIEF = 'Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names the topic; subtitle states the decision, your recommendation, and the stakes. Content carries only what is needed to decide, with the evidence behind it below the ask rather than ahead of it. Ask only what changes your next step, and offer only options you would actually take. The reader takes a page one step at a time, so hold each step — and a stepless page — to one question or request for action; several decisions means several `<Step>` children, never one long scroll of stacked context and asks. A page that asks nothing states what happened and what it changes.';
 const PAGE_AUTHORING = 'Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="…" subtitle="…">`; a multi-step page puts its content in `<Step>` children. Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response. Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome — the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.';
 const DISPLAY_SET_LINE = 'The shadcn display set — `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts — is in scope too, for presentation only.';
 /** The one page authoring model for `human -h`. */

package/dist/commands/memory/edit.js

@@ -4,7 +4,7 @@ import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { readText, writeText } from '../../core/fs-utils.js';
 import { resolveMemoryDoc } from '../../core/memory-resolver.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, readHistoryRecords, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, coerceGate, coerceSurface, overlayParam, literalBodySegment, serializeMemoryDocLiteral, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, } from './shared.js';
 /** Frontmatter fields an overlay flag cannot express removing. `kind` and the
  *  routing line are the document's contract (a doc without them is malformed);
  *  `origin` and `last-updated` are runtime provenance. */
@@ -39,6 +39,8 @@ export const editLeaf = defineLeaf({
             overlayParam('gate'),
             overlayParam('slash', {}, 'Presence SETS the field; remove it with `--unset slash`.'),
             { kind: 'flag', name: 'doc-rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
+            { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised.' },
+            { kind: 'flag', name: 'unset-extension', type: 'string', required: false, repeatable: true, constraint: 'Remove one explicitly persisted declared field by its full `extensions.<plugin>.<field>` path. A removed explicit value lets its declaration default apply only in structured output.' },
             { kind: 'flag', name: 'unset', type: 'enum', choices: [...CLEARABLE_FIELDS], required: false, repeatable: true, constraint: 'Remove a frontmatter field an overlay flag cannot express removing. One field per occurrence. `kind`, `when-and-why-to-read`, `origin`, and `last-updated` are never clearable.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before editing. A disambiguation filter only \u2014 never a creation target, and never a way to move a doc between stores.' },
             { kind: 'stdin', name: 'body', required: false, constraint: 'Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made.' },
@@ -54,6 +56,7 @@ export const editLeaf = defineLeaf({
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands \u2014 read the revisions or read the doc back.' },
         ],
         outputKind: 'object',
+        dynamicState: () => memoryExtensionFieldCatalogHelp('edit'),
         effects: [
             'Rewrites memory/<name>.md at the resolved scope and appends one `edit` record to memory/.history/<name>.jsonl.',
         ],
@@ -86,6 +89,7 @@ export const editLeaf = defineLeaf({
         if (doc.scope === 'builtin') {
             throw usage(`${doc.name} is a builtin document shipped with the package (read-only) \u2014 it cannot be edited. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
         }
+        const extensionChanges = parseRequestedExtensionChanges(input['extension'], input['unsetExtension'], memoryExtensionCatalogForDoc(doc));
         const before = readText(doc.path);
         const parsed = parseFrontmatterGeneric(before);
         const previous = { ...(parsed.data ?? {}) };
@@ -107,6 +111,7 @@ export const editLeaf = defineLeaf({
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['docRationale']);
+        applyExtensionChanges(frontmatter, extensionChanges.sets, extensionChanges.unsets);
         for (const field of input['unset'] ?? []) {
             delete frontmatter[field];
         }

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

@@ -1,3 +1,4 @@
+export { lintSubstrateFrontmatter as lintSubstrateSchema } from '../../core/substrate/frontmatter-validation.js';
 /** Warn when a body short enough to inline still pays a routing line. */
 export declare function lintShortPreviewBody(fm: Record<string, unknown>, body: string): string | null;
 /** The length rule. Caps are computed from the parsed entries — an invalid
@@ -6,10 +7,4 @@ export declare function lintShortPreviewBody(fm: Record<string, unknown>, body:
  *  `name`, else the normalized path-derived name) — persona layers under
  *  `kinds/` are recognized by it and never capped. */
 export declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | 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"). 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 declare function lintSubstrateSchema(fm: Record<string, unknown> | null): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -13,15 +13,13 @@ 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, parseSubstrateFrontmatter, resolveDocName, SURFACE_EVENTS, SURFACE_RUNGS, } from '../../core/substrate/schema.js';
+import { normalizeDocName, parseSubstrateFrontmatter, resolveDocName, } from '../../core/substrate/schema.js';
+import { lintSubstrateFrontmatter } from '../../core/substrate/frontmatter-validation.js';
+export { lintSubstrateFrontmatter as lintSubstrateSchema } from '../../core/substrate/frontmatter-validation.js';
+import { memoryExtensionValidationCatalog, validateMemoryExtensionValues } from '../../core/memory/extensions.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { descendantStoreRoots } from '../../core/nested-stores.js';
-/** 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
@@ -49,8 +47,6 @@ 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`. */
-const SUPPRESSIBLE_RULES = ['length'];
 function ignoresRule(fm, rule) {
     const v = fm['lint-ignore'];
     return v === rule || (Array.isArray(v) && v.includes(rule));
@@ -104,120 +100,13 @@ export function lintBodyLength(fm, body, docName) {
     }
     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"). 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`';
-    if (!isDocKind(fm.kind)) {
-        return `invalid kind: ${JSON.stringify(fm.kind)} (expected knowledge|preference)`;
-    }
-    // The retired `when`/`why` pair was merged into one read-routing field. The
-    // hard cut is enforced HERE: an old-shape doc must fail, never be silently
-    // read at runtime.
-    if ('when' in fm || 'why' in fm) {
-        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` 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.';
-    }
-    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 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 slash = fm.slash;
-    if (slash !== undefined && typeof slash !== 'boolean') {
-        return `invalid slash: ${JSON.stringify(slash)} (expected a boolean)`;
-    }
-    // rationale (maintainer-facing gap this doc closes) is optional everywhere —
-    // no nagging when absent, just a type check when present.
-    const rationale = fm.rationale;
-    if (rationale !== undefined && typeof rationale !== 'string') {
-        return `invalid rationale: ${JSON.stringify(rationale)} (expected a string)`;
-    }
-    const lintIgnore = fm['lint-ignore'];
-    if (lintIgnore !== undefined) {
-        const rules = Array.isArray(lintIgnore) ? lintIgnore : [lintIgnore];
-        if (rules.length === 0 || !rules.every((r) => typeof r === 'string' && SUPPRESSIBLE_RULES.includes(r))) {
-            return `invalid lint-ignore: ${JSON.stringify(lintIgnore)} (the only suppressible rule is \`length\`)`;
-        }
-    }
-    return null;
-}
 /** Strict-parse one file; push a finding on a YAML error, then run the
  *  schema check when the file lives in a substrate store, then validate every
  *  `[[canonical/name]]` doc link in the body against the exact resolvable
  *  corpus. A dangling link is an authoring error caught HERE, never silently
  *  carried; leaf-name fallback is deliberately excluded so links stay stable
  *  as the graph grows and another document acquires the same leaf name. */
-function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbackName) {
+function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbackName, scope) {
     let fm;
     let body;
     try {
@@ -230,10 +119,13 @@ function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbac
     }
     if (!substrateStore)
         return;
-    const schemaError = lintSubstrateSchema(fm);
+    const schemaError = lintSubstrateFrontmatter(fm);
     if (schemaError !== null)
         findings.push({ path: file, error: schemaError });
     if (fm !== null) {
+        for (const issue of validateMemoryExtensionValues(fm['extensions'], memoryExtensionValidationCatalog({ scope, path: file }))) {
+            findings.push({ path: file, error: `${issue.path}: ${issue.message}` });
+        }
         const lengthError = lintBodyLength(fm, body, resolveDocName(fm, fallbackName));
         if (lengthError !== null)
             findings.push({ path: file, error: lengthError });
@@ -246,7 +138,7 @@ function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbac
             if (entry.on !== 'memory-read')
                 continue;
             for (const glob of entry.match ?? []) {
-                if (glob === '**' || glob === '*') {
+                if ((glob === '**' || glob === '*') && !ignoresRule(fm, 'broad-memory-read')) {
                     warnings.push(`${file}: memory-read glob \`${glob}\` fires on every memory read — scope it to a name subtree`);
                 }
             }
@@ -329,7 +221,7 @@ export const lintLeaf = defineLeaf({
             for (let i = 1; i < segs.length; i++)
                 corpusNames.add(segs.slice(0, i).join('/'));
         }
-        const lintDir = (dir) => {
+        const lintDir = (dir, scope) => {
             if (!dir || !pathExists(dir))
                 return;
             for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
@@ -338,14 +230,14 @@ export const lintLeaf = defineLeaf({
                     continue;
                 memoryCount += 1;
                 const fallbackName = normalizeDocName(relPath.replace(/\.md$/, ''));
-                lintFile(file, basename(file) !== 'MEMORY.md', findings, warnings, corpusNames, fallbackName);
+                lintFile(file, basename(file) !== 'MEMORY.md', findings, warnings, corpusNames, fallbackName, scope);
             }
         };
         for (const root of projectScopeRoots()) {
-            lintDir(join(root, 'memory'));
+            lintDir(join(root, 'memory'), 'project');
             for (const plugin of listInstalledPluginsInRoot('project', root)) {
                 if (plugin.enabled)
-                    lintDir(pluginMemoryDir(plugin));
+                    lintDir(pluginMemoryDir(plugin), 'project');
             }
         }
         // Nested descendant stores: same schema gate, plus a boot-entry warning —
@@ -353,7 +245,7 @@ export const lintLeaf = defineLeaf({
         // surfaces entry there is inert.
         for (const root of descendantStoreRoots(projectScopeRoots())) {
             const dir = join(root, 'memory');
-            lintDir(dir);
+            lintDir(dir, 'project');
             if (!pathExists(dir))
                 continue;
             for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
@@ -372,10 +264,10 @@ export const lintLeaf = defineLeaf({
             }
         }
         for (const scope of ['user', 'builtin']) {
-            lintDir(scopeMemoryDir(scope));
+            lintDir(scopeMemoryDir(scope), scope);
             for (const plugin of listInstalledPlugins(scope)) {
                 if (plugin.enabled)
-                    lintDir(pluginMemoryDir(plugin));
+                    lintDir(pluginMemoryDir(plugin), scope);
             }
         }
         // Profile coverage: each managed project has exactly ONE workspace front
@@ -390,7 +282,7 @@ export const lintLeaf = defineLeaf({
             try {
                 const { profileId, manifest } = loadProfileManifest(profileIdOrName);
                 profileResolved = true;
-                lintDir(profileMemoryDir(profileId));
+                lintDir(profileMemoryDir(profileId), 'user');
                 for (const dir of manifest.projects) {
                     profileProjects += 1;
                     const doors = frontDoorDocs(join(dir, '.crouter', 'memory'));

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

@@ -9,6 +9,7 @@ export interface ListedMemoryDoc {
     path: string;
     shortForm: string;
     slash: boolean;
+    extensions: Record<string, Record<string, string | boolean | number>>;
 }
 export declare function listMemoryDocs(kindFilter?: string, scopeFilter?: MemoryScope, quiet?: boolean, docs?: readonly MemoryDoc[]): ListedMemoryDoc[];
 export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/list.js

@@ -1,5 +1,7 @@
 import { defineLeaf } from '../../core/command.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
+import { renderResult } from '../../core/render.js';
 import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { paginate } from '../../core/pagination.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
@@ -20,7 +22,15 @@ export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = li
             continue;
         if (kindFilter !== undefined && sub.kind !== kindFilter)
             continue;
-        addItem({ name: sub.name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, slash: sub.slash });
+        addItem({
+            name: sub.name,
+            kind: sub.kind,
+            scope: sub.scope,
+            path: sub.path,
+            shortForm: sub.shortForm,
+            slash: sub.slash,
+            extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(doc)),
+        });
     }
     items.sort((a, b) => {
         const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -48,7 +58,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}. 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: 'items', type: 'object[]', required: true, constraint: 'One row per document: {name, short_form, kind, scope, extensions}. extensions carries effective valid plugin-owned metadata; enabled defaults appear here without becoming frontmatter, while disabled and unresolved namespaces are omitted. 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.' },
@@ -72,6 +82,7 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
+                extensions: d.extensions,
                 ...(includePaths ? { path: d.path } : {}),
             })),
             next_cursor: result.next_cursor,
@@ -79,4 +90,8 @@ export const listLeaf = defineLeaf({
             follow_up: 'Read one in full with `crtr memory read <name>`, or revise one with `crtr memory edit <name> --rationale "<why>"` (body, routing, frontmatter, and visibility all go through that one verb, and it records the change). Narrow with --kind / --scope, page with --cursor, or search a topic with `crtr memory find <query>`.',
         };
     },
+    render: (result) => {
+        const items = result['items'].map(({ extensions: _extensions, ...item }) => item);
+        return renderResult({ ...result, items }, listLeaf.help);
+    },
 });

package/dist/commands/memory/read.js

@@ -2,6 +2,7 @@ import { CrtrClient } from '../../api/index.js';
 import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
+import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
 import { readText, realpathOrSelf } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
@@ -10,6 +11,7 @@ import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../co
 import { deliveredAtOrAbove, loadInjectedDocs, recordDelivery, saveInjectedDocs } from '../../core/substrate/injected-store.js';
 import { ancestorDirsOf, dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
 import { memoryReadDocBlocks } from '../../core/substrate/on-read.js';
+import { renderResult } from '../../core/render.js';
 import { effectiveDocKind, normalizeDocName } from '../../core/substrate/schema.js';
 import { MEMORY_KINDS } from './shared.js';
 export { createMemoryDocSnapshot, resolveMemoryDocs };
@@ -72,8 +74,9 @@ export const readLeaf = defineLeaf({
             { name: 'path', type: 'string', required: false, constraint: 'Absolute path to the document on disk. Revise it with `crtr memory edit`, never by editing this file — an edit records why the change happened and lands in the doc’s revision history. Absent on a directory read.' },
             { name: 'content', type: 'string', required: false, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text. May be preceded by one `<auto-loaded-context>` block carrying the doc\u2019s neighborhood listings and any docs routed to this read. Absent on a directory read.' },
             { name: 'listing', type: 'string[]', required: false, constraint: 'Present only on a directory read: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`.' },
+            { name: 'extensions', type: 'object', required: false, constraint: 'Effective valid plugin-owned metadata, keyed by plugin namespace then field. Includes enabled declaration defaults without writing them to frontmatter; disabled and unresolved namespaces are omitted. Present only on a document read.' },
             { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. A directory link returns that directory\u2019s listing. Omitted when the body carries no resolvable links.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Present on a directory read, or on a document read whose body links to further memory documents.' },
         ],
         outputKind: 'object',
         effects: [
@@ -191,11 +194,17 @@ export const readLeaf = defineLeaf({
             scope: doc.scope,
             path: doc.path,
             content: finalContent,
-            ...(links.length > 0 ? { links } : {}),
-            follow_up: (links.length > 0
-                ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
-                : '') +
-                'Use --frontmatter on this same command to inspect the YAML frontmatter, or revise the doc with `crtr memory edit` (recorded, with a rationale). Browse the inventory with `crtr memory list`.',
+            extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(doc)),
+            ...(links.length > 0
+                ? {
+                    links,
+                    follow_up: 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth.',
+                }
+                : {}),
         };
     },
+    render: (result) => {
+        const { extensions: _extensions, ...withoutExtensions } = result;
+        return renderResult(withoutExtensions, readLeaf.help);
+    },
 });

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

@@ -1,5 +1,7 @@
-import type { FlagParam } from '../../core/help.js';
-import type { MemoryScope } from '../../core/memory-resolver.js';
+import { type FlagParam } from '../../core/help.js';
+import type { MemoryDoc, MemoryScope } from '../../core/memory-resolver.js';
+import { type MemoryExtensionCatalog } from '../../core/memory/extensions.js';
+import type { MemoryExtensionScalar } from '../../types.js';
 export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
 export declare const MEMORY_SCOPES: readonly ["user", "project", "profile", "node"];
 /** Scope sort weight matching resolution precedence (node > project stack >
@@ -64,6 +66,33 @@ export declare function literalBodySegment(source: string): string;
  *  untransformed. Creation uses `serializeMemoryDoc`, which normalizes a first
  *  body into the canonical shape. */
 export declare function serializeMemoryDocLiteral(frontmatter: Record<string, unknown>, bodySegment: string): string;
+export interface RequestedExtensionSet {
+    path: string;
+    namespace: string;
+    field: string;
+    value: MemoryExtensionScalar;
+}
+interface RequestedExtensionPath {
+    path: string;
+    namespace: string;
+    field: string;
+}
+/** Resolve declarations at the same scope and path a document will use. The
+ * catalog intentionally includes disabled plugins: they still authorize typed
+ * edits to values that stay inert until their plugin is enabled again. */
+export declare function memoryExtensionCatalogForDoc(doc: Pick<MemoryDoc, 'scope' | 'path'>): MemoryExtensionCatalog;
+/** A bounded declaration catalog for the two authoring leaves. The manifest is
+ * the source for both the type and operation-specific guidance. */
+export declare function memoryExtensionFieldCatalogHelp(operation: 'write' | 'edit'): string | null;
+/** Parse every requested extension mutation before the caller constructs any
+ * frontmatter. Set values are deliberately declaration-typed rather than YAML. */
+export declare function parseRequestedExtensionChanges(setRaw: readonly string[] | undefined, unsetRaw: readonly string[] | undefined, catalog: MemoryExtensionCatalog): {
+    sets: RequestedExtensionSet[];
+    unsets: RequestedExtensionPath[];
+};
+/** Apply only requested extension paths. Existing unknown namespaces remain
+ * untouched; an unset prunes the empty namespace and empty root mapping. */
+export declare function applyExtensionChanges(frontmatter: Record<string, unknown>, sets: readonly RequestedExtensionSet[], unsets: readonly RequestedExtensionPath[]): void;
 /** The frontmatter-overlay flags, keyed by flag name, carrying the prose true
  *  on BOTH leaves. `write` appends its creation clauses with `withConstraint`;
  *  neither leaf restates the other's rules. */
@@ -80,3 +109,4 @@ export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s
 export declare 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 when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: \"When planning or prioritizing work across this profile.\" Good: \"When the user mentions something from their todos, or asks what is still outstanding across this profile.\" 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 declare 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 declare 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.";
+export {};