@north-light/crouter 0.3.231 → 0.3.233

package/dist/commands/human/request.js

@@ -55,9 +55,9 @@ function requestId(input) {
 }
 /** The one projection of a request record onto leaf output. Absent fields stay
  *  absent: a dismissal or a withdrawal has no responses to report. */
-function requestResult(dto) {
+function requestResult(dto, includeRequestId = true) {
     return {
-        request_id: dto.request_id,
+        ...(includeRequestId ? { request_id: dto.request_id } : {}),
         state: dto.state,
         title: dto.title,
         ...(dto.subtitle === undefined ? {} : { subtitle: dto.subtitle }),
@@ -71,8 +71,7 @@ function requestResult(dto) {
         ...(dto.delivery === undefined ? {} : { delivery: dto.delivery }),
     };
 }
-const RECORD_OUTPUT = [
-    { name: 'request_id', type: 'string', required: true, constraint: 'The request — the same 64-hex id the human inbox lists it under.' },
+const REQUEST_RESULT_OUTPUT = [
     { name: 'state', type: 'pending | answered | dismissed | canceled', required: true, constraint: 'answered: the person (or an authorized responder) submitted the typed responses. dismissed: the recipient surface closed it unanswered. canceled: the requester withdrew it.' },
     { name: 'title', type: 'string', required: true, constraint: 'Page title as currently published.' },
     { name: 'subtitle', type: 'string', required: false, constraint: 'Page subtitle when the page carries one.' },
@@ -85,6 +84,10 @@ const RECORD_OUTPUT = [
     { name: 'action', type: 'object', required: false, constraint: '{name, payload} frozen at creation; an omitted payload is frozen as null. Absent when no action is bound.' },
     { name: 'delivery', type: 'object', required: false, constraint: 'Completion-delivery state for the bound action: {state: none | pending | running | accepted | permanent_failed, attempt, next_attempt_at?, accepted_at?, permanent_failed_at?, last_failure?}. Absent when no action is bound.' },
 ];
+const RECORD_OUTPUT = [
+    { name: 'request_id', type: 'string', required: true, constraint: 'The request — the same 64-hex id the human inbox lists it under.' },
+    ...REQUEST_RESULT_OUTPUT,
+];
 // ---------------------------------------------------------------------------
 // create
 // ---------------------------------------------------------------------------
@@ -106,9 +109,7 @@ const createLeaf = defineLeaf({
         ],
         output: [
             { name: 'request_id', type: 'string', required: true, constraint: 'The created request — pass it to get/replace/respond/cancel. Stable, and the deduplication key every completion destination keys on.' },
-            { name: 'state', type: 'string', required: true, constraint: 'Always "pending": creation never settles.' },
             { name: 'action', type: 'object', required: false, constraint: '{name} of the frozen action binding. Absent when the request carries no action.' },
-            { name: 'delivery_state', type: 'string', required: true, constraint: 'Always "none" at creation: delivery is enqueued at settlement, not before.' },
         ],
         outputKind: 'object',
         effects: [
@@ -126,9 +127,7 @@ const createLeaf = defineLeaf({
             const created = await cliClient().createHumanRequest(body);
             return {
                 request_id: created.request_id,
-                state: created.state,
                 ...(created.action === undefined ? {} : { action: created.action }),
-                delivery_state: created.delivery_state,
             };
         }
         catch (error) {
@@ -174,7 +173,7 @@ const replaceLeaf = defineLeaf({
             { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
             { kind: 'flag', name: 'page', type: 'path', required: true, constraint: 'The revised page: a .tsx module or a complete .html/.htm document. Read here and sent inline.' },
         ],
-        output: [...RECORD_OUTPUT],
+        output: [...REQUEST_RESULT_OUTPUT],
         outputKind: 'object',
         effects: [
             'Rewrites the page and its typed response contract in place; open surfaces reload it without a second request.',
@@ -186,7 +185,7 @@ const replaceLeaf = defineLeaf({
         const id = requestId(input);
         const body = { page: readPageFile(input['page']) };
         try {
-            return requestResult(await cliClient().replaceHumanRequest(id, body));
+            return requestResult(await cliClient().replaceHumanRequest(id, body), false);
         }
         catch (error) {
             rethrowAsCliError(error);
@@ -213,7 +212,7 @@ const respondLeaf = defineLeaf({
                 constraint: 'JSON file holding the respond object: {"responses":{"<component_id>":{...}}, "actor"?:"<who answered>"}. One typed response per response-bearing component; the daemon validates the complete map against the currently published page.',
             },
         ],
-        output: [...RECORD_OUTPUT],
+        output: [...REQUEST_RESULT_OUTPUT],
         outputKind: 'object',
         effects: [
             'Settles the request as answered and drops it from the human inbox.',
@@ -225,7 +224,7 @@ const respondLeaf = defineLeaf({
         const id = requestId(input);
         const body = readJsonFile(input['responseFile'], 'response-file', 'the respond object');
         try {
-            return requestResult(await cliClient().respondHumanRequest(id, body));
+            return requestResult(await cliClient().respondHumanRequest(id, body), false);
         }
         catch (error) {
             rethrowAsCliError(error);
@@ -246,7 +245,7 @@ const cancelLeaf = defineLeaf({
             { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
             { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short note recorded on the terminal result and carried in the completion document.' },
         ],
-        output: [...RECORD_OUTPUT],
+        output: [...REQUEST_RESULT_OUTPUT],
         outputKind: 'object',
         effects: [
             'Settles the request as canceled and drops it from the human inbox — the person is no longer asked.',
@@ -258,7 +257,7 @@ const cancelLeaf = defineLeaf({
         const id = requestId(input);
         const reason = typeof input['reason'] === 'string' && input['reason'] !== '' ? input['reason'] : undefined;
         try {
-            return requestResult(await cliClient().cancelHumanRequest(id, reason === undefined ? {} : { reason }));
+            return requestResult(await cliClient().cancelHumanRequest(id, reason === undefined ? {} : { reason }), false);
         }
         catch (error) {
             rethrowAsCliError(error);

package/dist/commands/human/review.js

@@ -46,13 +46,13 @@ function explicitDeliver(input, context) {
     const deliver = input['deliver'];
     return deliver === 'wake' || deliver === 'quiet' ? deliver : undefined;
 }
-function mutationOutput(result) {
+function mutationOutput(result, includeAnchor = true) {
     const { comment } = result;
     return {
         comment_id: comment.comment_id,
         status: comment.status,
         revision: comment.revision,
-        anchor: comment.anchor,
+        ...(includeAnchor ? { anchor: comment.anchor } : {}),
         author: comment.author,
         text: comment.text,
         changed: result.changed,
@@ -143,7 +143,6 @@ const humanReviewCommentCreate = defineLeaf({
             { name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id.' },
             { name: 'status', type: 'string', required: true, constraint: 'Current comment status: open, resolved, or deleted.' },
             { name: 'revision', type: 'integer', required: true, constraint: 'Current per-comment revision.' },
-            { name: 'anchor', type: 'object', required: true, constraint: 'Current whole-line anchor.' },
             { name: 'author', type: 'object', required: true, constraint: 'Daemon-derived human or node attribution.' },
             { name: 'text', type: 'string', required: true, constraint: 'Stored full comment text.' },
             { name: 'changed', type: 'boolean', required: true, constraint: 'Whether this invocation changed the comment.' },
@@ -162,7 +161,7 @@ const humanReviewCommentCreate = defineLeaf({
             actor_node_id: nodeActor(),
             ...(explicitDeliver(input, context) === undefined ? {} : { deliver: explicitDeliver(input, context) }),
         });
-        return mutationOutput(result);
+        return mutationOutput(result, false);
     },
 });
 const humanReviewCommentList = defineLeaf({

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

@@ -4,6 +4,12 @@ export interface PageHelpText {
     componentSelection: readonly string[];
     pageHint: string;
     rootUseWhen: string;
+    /** `human send` surfaces. HTML is named only where an HTML page can be read. */
+    sendSummary: string;
+    sendWhenToUse: string;
+    pageFlagConstraint: string;
+    stdinConstraint: string;
+    dirConstraint: string;
 }
 /** The one page authoring model for `human -h`. */
 export declare function pageHelpText(pageSurface?: boolean): PageHelpText;

package/dist/commands/human/shared.js

@@ -3,16 +3,41 @@ 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. 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 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 what is being settled, not the topic it sits under. Subtitle is the single line shown beside the title in the inbox list before anything is opened, so it earns the open — your recommendation and what is at stake — rather than summarising the page. Content carries only what is needed to decide. Ask only what changes your next step, and offer only options you would actually take; mark the one you would take `recommended` (at most one per question), because a page whose single question is that picker can be answered straight from the inbox list without ever being opened, which is the cheapest answer you can ask for. 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.';
+// Both hosts render pages and both want them reached for by default; only the
+// reason differs, so neither surface is left sounding like pages are exotic.
+const ENCOURAGEMENT_PAGE_SURFACE = 'Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion.';
+const ENCOURAGEMENT_TERMINAL = 'Use inline pages as the default way to put a question or a decision in front of the user; the viewer draws them in the transcript and in the inbox, so a page is not a special occasion.';
+// The default is about form, not frequency: the page is the cheap part and the
+// reader's attention is the expensive one, so say both in the same breath.
+const INTERRUPTION_COST = 'What costs the reader is being asked, not the page it arrives on: send one when their answer changes what you do next, carry everything else in your next report, and put several decisions in one page as separate steps rather than sending several pages.';
+const AUTHORING_MODULE = '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.';
+// Only a page surface can show an HTML document; a terminal host renders its
+// title and nothing else, so naming the dialect there would hand the agent a
+// page its reader could not read.
+const AUTHORING_HTML = 'Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response.';
+const AUTHORING_RULES = '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.';
+// Where context belongs is a property of the surface, not of taste: a page
+// surface shows a question with the whole page around it, a terminal shows one
+// question alone on the screen.
+const CONTEXT_PAGE_SURFACE = 'Context can sit anywhere on the page — prose and display components around a question are rendered beside it — so a question\'s `body` carries what that question needs and the page carries the shared background.';
+const CONTEXT_TERMINAL = 'Put the context a question needs in that question\'s own `body`: the reader is shown one question at a time, so page-level prose is not in front of them while they answer, and a question that leans on it cannot be answered.';
+const FLATTENING_TERMINAL = 'This host draws the page from the components you declared rather than running your module, so layout, Tailwind classes, state, and click handlers never reach the reader — what survives is each component\'s `label`, its markdown `body`, and its options, rows, or cards. A chart renders as one line naming it, and a product-registered component cannot be answered here at all.';
 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`. */
 export function pageHelpText(pageSurface = false) {
+    const authoring = [
+        pageSurface ? ENCOURAGEMENT_PAGE_SURFACE : ENCOURAGEMENT_TERMINAL,
+        INTERRUPTION_COST,
+        AUTHORING_MODULE,
+        ...(pageSurface ? [AUTHORING_HTML] : []),
+        AUTHORING_RULES,
+        pageSurface ? CONTEXT_PAGE_SURFACE : CONTEXT_TERMINAL,
+        ...(pageSurface ? [] : [FLATTENING_TERMINAL]),
+    ].join(' ');
     return {
         brief: PAGE_BRIEF,
-        authoring: pageSurface
-            ? `Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion. ${PAGE_AUTHORING}`
-            : PAGE_AUTHORING,
+        authoring,
         componentSelection: [...CORE_COMPONENT_SELECTION_LINES, DISPLAY_SET_LINE],
         pageHint: 'Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.',
         // The page-surface wording names no document review and no live display:
@@ -22,6 +47,19 @@ export function pageHelpText(pageSurface = false) {
         rootUseWhen: pageSurface
             ? 'a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.'
             : 'a person must decide, review a document with you, or receive a live display.',
+        sendSummary: pageSurface ? 'send a durable TSX or HTML page' : 'send a durable TSX page',
+        sendWhenToUse: pageSurface
+            ? 'you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.'
+            : 'you need to put structured TSX content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.',
+        pageFlagConstraint: pageSurface
+            ? 'A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.'
+            : 'Provide exactly one of --page or stdin.',
+        stdinConstraint: pageSurface
+            ? 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.'
+            : 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH.',
+        dirConstraint: pageSurface
+            ? 'Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.'
+            : 'Interaction directory holding page.tsx, optional page.js, page.json, and response lifecycle files when delivery needs them.',
     };
 }
 export function resolveMaxPanes() {

package/dist/commands/human.js

@@ -46,7 +46,7 @@ export function registerHuman() {
         },
         children: [
             humanComponents,
-            humanSend,
+            humanSend(pageSurface),
             ...(pageSurface ? [] : [humanReviewBranch]),
             humanFeedbackBranch,
             ...(pageSurface ? [] : [humanShow]),

package/dist/commands/memory/delete.js

@@ -37,12 +37,10 @@ export const deleteLeaf = defineLeaf({
             selectorParam('dir', {}, 'Deletes from that one store, including a non-winning duplicate no target view resolves to.'),
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Canonical name of the deleted document.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
-            { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success — the file was removed. A missing document fails with not_found instead.' },
             { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s revision log, which OUTLIVES the document — the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read the life of the removed doc, or browse what remains.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Present only when a same-store canonical collision was recovered by selecting the first physical path in lexical order.' },
         ],
         outputKind: 'object',
         effects: [
@@ -89,12 +87,12 @@ export const deleteLeaf = defineLeaf({
         // this same log — one log per physical path over its whole life.
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'delete', before, after: '' }));
         return {
-            name: doc.name,
             scope: doc.scope,
             path: doc.path,
-            deleted: true,
             log_path: logPath,
-            follow_up: `Removed${selected.collisionPaths.length > 0 ? ` the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` : '.'} Its revision history survives — read it with \`crtr memory history ${doc.name}\`, or browse what remains with \`crtr memory list\`.`,
+            ...(selected.collisionPaths.length > 0
+                ? { follow_up: `Removed the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` }
+                : {}),
         };
     },
 });

package/dist/commands/memory/edit.js

@@ -55,8 +55,6 @@ export const editLeaf = defineLeaf({
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the revised document.' },
             { name: 'revision', type: 'number', required: true, constraint: 'This document\u2019s record count after the append \u2014 the revision number to pass to `crtr memory history --revision`.' },
             { name: 'changed', type: 'string[]', required: true, constraint: '`body` when the body text changed, plus the frontmatter field names whose values changed. `last-updated` is excluded \u2014 it is stamped on every edit, so naming it says nothing.' },
-            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document\u2019s append-only revision log (JSONL, one self-contained record per line).' },
-            { 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'),
@@ -197,8 +195,6 @@ export const editLeaf = defineLeaf({
             path: doc.path,
             revision: readHistoryRecords(logPath).length,
             changed,
-            log_path: logPath,
-            follow_up: `Recorded. Review the revisions with \`crtr memory history ${doc.name} --diff\`, or read the doc back with \`crtr memory read ${doc.name}\`.`,
         };
     },
 });

package/dist/commands/memory/move.js

@@ -57,14 +57,13 @@ export const moveLeaf = defineLeaf({
             selectorParam('dir', {}, 'Source, destination, and inbound-link rewriting all stay inside that one store, so moving a non-winning duplicate leaves every other store untouched — and rewrites no link at all, because the name still resolves to the candidate that outranks it here.'),
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'The document’s new canonical name.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The document’s new canonical name — `--to` after canonicalization, so it can differ from what you passed.' },
             { name: 'previous_name', type: 'string', required: true, constraint: 'The canonical name it answered to before the move.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope of the store the document moved within: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the document at its new location — `<local name>/INDEX.md` when that canonical directory already has members in the store, else `<local name>.md`.' },
-            { name: 'moved', type: 'boolean', required: true, constraint: 'Always true on success — the file and its revision log now live at the new name.' },
             { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the revision log at its new location, ending in a `move` record that names the previous canonical name.' },
             { name: 'refs_rewritten', type: 'object[]', required: true, constraint: 'Documents whose bodies were rewritten from `[[<previous_name>]]` to `[[<name>]]`. Each: {name, scope, path, refs}. Empty when nothing linked to the document — or when the moved file is not what that name resolves to here (another store’s candidate wins the address), in which case inbound refs keep resolving to that winner and are left alone.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back at the new name, verify the corpus with lint.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Outcome-dependent collision recovery and inbound-reference rewriting signal.' },
         ],
         outputKind: 'object',
         effects: [
@@ -216,10 +215,9 @@ export const moveLeaf = defineLeaf({
             previous_name: doc.name,
             scope: doc.scope,
             path: placement.path,
-            moved: true,
             log_path: newLog,
             refs_rewritten: refsRewritten,
-            follow_up: `Moved${selected.collisionPaths.length > 0 ? ` the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` : '.'}${refsNote} Read it back with \`crtr memory read ${newName}\`, and run \`crtr memory lint\` to verify no link dangles.`,
+            follow_up: `Moved${selected.collisionPaths.length > 0 ? ` the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` : '.'}${refsNote}`,
         };
     },
 });

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

@@ -194,7 +194,7 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare 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 declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 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\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s routing anchor \u2014 its own canonical name when it is its directory\u2019s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. 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 \u2014 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 declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 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\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s routing anchor \u2014 its own canonical name when it is its directory\u2019s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line \u2014 split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped \u2014 where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m \"\u2026\"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute \u2014 the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. 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 \u2014 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 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 = "Document gates, surface-entry gates, 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, namespace included for a project document. A bare directory name is a valid link too: following it returns that directory\u2019s own document when it has one, plus the directory listing. 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, label, or old-name form \u2014 a renamed target needs its links rewritten.";

package/dist/commands/memory/shared.js

@@ -14,7 +14,7 @@ import { usage } from '../../core/errors.js';
 import { memoryExtensionValidationCatalog, } from '../../core/memory/extensions.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { NEUTRAL_PROJECT_MEMORY, scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
-import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { loadProfileManifest, resolveProfileOperand, 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';
 import { exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
@@ -113,7 +113,7 @@ export function resolveReadSelector(input) {
         // Naming a profile selects THAT profile's store exactly; the ambient
         // selection would otherwise answer for whichever profile this process runs
         // under, silently ignoring the flag.
-        const { profileId } = loadProfileManifest(input.profile);
+        const { profileId } = resolveProfileOperand(input.profile);
         return { scope: 'profile', store: nativeStoreDescriptor('profile', profileMemoryDir(profileId)) };
     }
     return { ...(scope === undefined ? {} : { scope }), store: null };
@@ -159,11 +159,15 @@ export function resolveWriteSelector(input) {
         return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
     }
     if (scope === 'profile') {
-        const profileIdOrName = input.profile && input.profile !== '' ? input.profile : process.env['CRTR_PROFILE_ID'] || '';
+        // A typed `--profile` gets fuzzy tolerance; the ambient `CRTR_PROFILE_ID`
+        // is a durable id this process was launched under, so it resolves strictly
+        // — a stale one must fail rather than write into a neighbouring store.
+        const typed = input.profile !== undefined && input.profile !== '';
+        const profileIdOrName = typed ? input.profile : process.env['CRTR_PROFILE_ID'] || '';
         if (profileIdOrName === '') {
             throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
         }
-        const { profileId } = loadProfileManifest(profileIdOrName);
+        const { profileId } = typed ? resolveProfileOperand(profileIdOrName) : loadProfileManifest(profileIdOrName);
         const memoryDir = profileMemoryDir(profileId);
         return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
     }
@@ -432,7 +436,7 @@ export function coerceSurface(raw) {
             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) {
+    if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') && match === undefined && matchFrontmatter === undefined) {
         throw usage(`--surface: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`);
     }
     const gate = rec['gate'];
@@ -764,7 +768,7 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     '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`.' },
     '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?, gate?}`; 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. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
+    '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?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command|pre-command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command/pre-command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     '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.' },
     '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.' },
 };
@@ -782,7 +786,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_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 routing anchor — its own canonical name when it is its directory’s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. 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_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 routing anchor — its own canonical name when it is its directory’s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line — split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped — where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m "…"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute — the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. 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 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 const GUIDE_PREDICATE_VOCABULARY = 'Document gates, surface-entry gates, 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, namespace included for a project document. A bare directory name is a valid link too: following it returns that directory\u2019s own document when it has one, plus the directory listing. 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, label, or old-name form \u2014 a renamed target needs its links rewritten.';

package/dist/commands/memory/write.js

@@ -1,6 +1,12 @@
 import { join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
+import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
+import { lintMemoryDocument, resolvableCanonicalNames } from '../../core/memory/lint.js';
+import { descendantStoreRoots } from '../../core/nested-stores.js';
+import { projectScopeRoots } from '../../core/scope.js';
+import { loadMemoryTargetView } from '../../core/memory-resolver.js';
+import { parsedSubstrateSurfaces } from '../../core/substrate/frontmatter-validation.js';
 import { ensureDir, realpathOrSelf, walkFiles, writeText } from '../../core/fs-utils.js';
 import { associateRepository } from '../../core/memory/repository-association.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
@@ -41,7 +47,8 @@ export const writeLeaf = defineLeaf({
             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. 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. State each fact once. Keep facts that affect action or judgment, including constraints, exceptions, numbers, and exact names. Remove known context, inferable conclusions, filler transitions, and examples that resolve no ambiguity. `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' +
+            '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.\n\n' +
+            'This leaf validates the document it just wrote and reports any finding; a silent result means it is clean, so there is nothing to run afterwards. The check is scoped to this one document — `crtr memory lint` remains the corpus-wide sweep, and only it catches store-level faults such as a canonical collision or a missing workspace front door.\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`.',
         params: [
@@ -61,14 +68,10 @@ export const writeLeaf = defineLeaf({
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin only — this leaf already claims the one positional for NAME, so a second bare argv token is rejected, not silently accepted as the body.' },
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'The full canonical document name written.' },
-            { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The full canonical document name written — the resolved identity, which composes a namespace onto the name you passed when the store declares one.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node. The selector rules decide this, so it is the one placement fact the invocation does not already state.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
-            { name: 'created', type: 'boolean', required: true, constraint: 'Always true on success — this leaf only creates. A name already taken at the resolved scope fails with a usage error naming `crtr memory edit`.' },
-            { name: 'frontmatter', type: 'object[]', required: true, constraint: 'The frontmatter options selected by this invocation, in document field order. Each: {key, value}.' },
-            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s append-only revision log, opened here with a `create` record.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back, revise it, or list the inventory.' },
+            { name: 'findings', type: 'object[]', required: false, constraint: 'Authoring problems in the document just written, each {severity, rule, message}. ABSENT when the document is clean, which is the normal case — a silent result means it validated. Covers every rule that reads one document: yaml, schema, extension, length, short-preview, local-name, namespace-placement, root-name, nested-store-boot, broad-memory-read, and a workspace front door on a non-root doc. Reference rules (dangling-link, memory-read-route) run only when the document actually carries a `[[link]]` or a memory-read route. The document is written either way: a finding reports what to revise with `crtr memory edit`, it does not mean the write failed.' },
         ],
         outputKind: 'object',
         dynamicState: () => memoryExtensionFieldCatalogHelp('write'),
@@ -166,31 +169,59 @@ export const writeLeaf = defineLeaf({
         writeText(path, after);
         const logPath = historyLogPathFor(memoryDir, path);
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'create', before: '', after }));
-        // Confirm exactly the frontmatter choices made by this invocation — the
-        // runtime-stamped fields do not masquerade as selected options in the
-        // result or its collapsed viewer preview.
-        const selectedKeys = [
-            'kind',
-            ...(initializing ? ['namespace'] : []),
-            ...(input['whenAndWhyToRead'] !== undefined ? ['when-and-why-to-read'] : []),
-            ...(input['shortForm'] !== undefined ? ['short-form'] : []),
-            ...(input['unlisted'] === true ? ['unlisted'] : []),
-            ...(input['surface'] !== undefined ? ['surfaces'] : []),
-            ...(input['gate'] !== undefined ? ['gate'] : []),
-            ...(input['slash'] === true ? ['slash'] : []),
-            ...(input['rationale'] !== undefined ? ['rationale'] : []),
-            ...(extensionChanges.sets.length > 0 ? ['extensions'] : []),
-        ];
-        const selectedFrontmatter = selectedKeys.map((key) => ({ key, value: frontmatter[key] }));
+        // Validate what was just authored, here, rather than returning a follow_up
+        // asking the author to go run lint — an obligation every write carries is
+        // the command's job, not a decision to hand back. Scoped to this one
+        // document: a corpus-wide sweep would surface unrelated findings from other
+        // docs on every write, which teaches an author to ignore the output.
+        //
+        // Each rule that needs an index beyond this file is paid for ONLY when the
+        // document can actually trip it. Reference resolution needs every canonical
+        // name in the view — seconds on a large corpus — so it is bought only when
+        // the doc carries a reference; nested-store detection walks the project
+        // roots, so it is bought only when the doc carries a boot entry.
+        const surfaceEntries = parsedSubstrateSurfaces(frontmatter);
+        const carriesReference = docLinkNames(body).length > 0 || surfaceEntries.some((entry) => entry.on === 'memory-read');
+        const carriesBootEntry = surfaceEntries.some((entry) => entry.on === 'boot');
+        const lint = lintMemoryDocument(store, path, {
+            ...(carriesReference
+                ? {
+                    resolvable: resolvableCanonicalNames(loadMemoryTargetView({
+                        cwd: store.ownerDir ?? process.cwd(),
+                        profileId: process.env['CRTR_PROFILE_ID'] || null,
+                        nodeId: process.env['CRTR_NODE_ID'] || null,
+                    }, { quiet: true, includeDescendants: true }).docs),
+                }
+                : {}),
+            ...(carriesBootEntry
+                ? {
+                    nestedStore: descendantStoreRoots(projectScopeRoots(process.cwd(), process.env['CRTR_PROFILE_ID'] || null))
+                        .map((root) => realpathOrSelf(join(root, 'memory')))
+                        .includes(realpathOrSelf(memoryDir)),
+                }
+                : {}),
+        });
+        // Findings ride the RESULT only. `memory lint` also streams them to stderr
+        // because it walks hundreds of files and the stream is progress; one
+        // document has no progress to report, and an agent that captures 2>&1
+        // would pay for every finding twice.
+        // The result confirms only what the caller could not already know: the
+        // resolved identity, where the selector rules put it, and anything wrong
+        // with what they just wrote. Echoing back the frontmatter flags just spent
+        // charges the author a second time for text they typed one call ago.
         return {
             name: canonicalName,
-            kind,
             scope,
             path,
-            created: true,
-            frontmatter: selectedFrontmatter,
-            log_path: logPath,
-            follow_up: `Read it back with \`crtr memory read ${canonicalName}\`, revise it later with \`crtr memory edit ${canonicalName} --rationale "<why>"\`, or browse the inventory with \`crtr memory list\`.`,
+            ...(lint.findings.length === 0
+                ? {}
+                : {
+                    findings: lint.findings.map((finding) => ({
+                        severity: finding.severity,
+                        rule: finding.rule,
+                        message: finding.message,
+                    })),
+                }),
         };
     },
 });

package/dist/commands/memory.js

@@ -18,7 +18,7 @@ export function registerMemory() {
         rootEntry: {
             concept: 'a memory document you read on demand — knowledge or a preference',
             desc: 'list, read, search, and write memory documents',
-            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Every document has one canonical name, a crtr identifier rather than a file path — read docs through the command surface, never cat or find the markdown off disk.',
+            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Every document has one canonical name, a crtr identifier rather than a file path — read docs through the command surface, never cat or find the markdown off disk. Slash commands are authored here too — one is a document flagged invocable.',
         },
         help: {
             name: 'memory',