@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/clients/attach/slash-commands.js

@@ -37,6 +37,8 @@ export const CANVAS_SLASH_COMMANDS = [
     { name: 'resume-node', description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node' },
     { name: 'view', description: 'Open a view in a popup — bare for the picker, or /view <name> to open that view directly' },
     { name: 'context', description: 'Browse this node + its subscriptions’ context dirs in a read-only nvim popup' },
+    { name: 'rename', description: 'Rename this node everywhere — node row, viewer window, session chip, tmux pane: /rename <name>' },
+    { name: 'color', description: 'Color this node — tmux pane outline + name chip: /color <color> (red, blue, #rrggbb, …) or /color none' },
 ];
 const CANVAS_NAMES = new Set(CANVAS_SLASH_COMMANDS.map((c) => c.name));
 /** Native canvas commands that shell a LOCAL `crtr` mutation or read against
@@ -46,7 +48,15 @@ const CANVAS_NAMES = new Set(CANVAS_SLASH_COMMANDS.map((c) => c.name));
  *  local node, `/context` opens local `crtr node inspect context`. `/graph`
  *  (the in-process GRAPH overlay, already remote-safe — see graph-overlay.ts)
  *  and `/view` (a self-contained popup unrelated to `nodeId`) stay available. */
-const REMOTE_UNSAFE_CANVAS_NAMES = new Set(['promote', 'resume-node', 'context']);
+const REMOTE_UNSAFE_CANVAS_NAMES = new Set(['promote', 'resume-node', 'context', 'rename']);
+/** tmux named colours accepted by `/color` (plus `colourN`/`#rrggbb`, validated
+ *  by pattern). Mirrors tmux's colour-name table so a typo is rejected with the
+ *  options rather than silently ignored by tmux. */
+const TMUX_NAMED_COLORS = new Set([
+    'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white',
+    'brightred', 'brightgreen', 'brightyellow', 'brightblue', 'brightmagenta', 'brightcyan',
+    'orange', 'grey', 'gray', 'default',
+]);
 /** Builtins with no Phase-4 engine method — scoped out (review m2). */
 const SCOPED_OUT = new Set(['trust']);
 /** Valid `/settings thinking` levels — the `SetThinkingLevelFrame['level']`
@@ -62,6 +72,7 @@ const THINKING_LEVELS = new Set(Object.keys({
     medium: true,
     high: true,
     xhigh: true,
+    max: true,
 }));
 const BUILTIN_NAMES = new Set(BUILTIN_SLASH_COMMANDS.map((c) => c.name));
 /** Builtin slash commands safe to run against a REMOTE attach (`--canvas`) —
@@ -152,6 +163,7 @@ export function dispatchSlashCommand(text, ctx) {
             if (!arg)
                 return openOrHint(ctx.openModelPicker, ctx, 'model', '/model <provider/id>');
             ctx.send({ type: 'set_model', model: arg });
+            ctx.onExplicitModelSet?.(arg);
             return true;
         case 'resume':
             if (!arg)
@@ -231,7 +243,7 @@ export function dispatchSlashCommand(text, ctx) {
 }
 /** Append the native canvas commands to a command list, skipping any already
  *  present (so they survive whatever list Unit Q feeds in — builtins, or the
- *  broker's `get_commands` result). The four canvas commands are viewer-owned,
+ *  broker's `get_commands` result). The canvas commands are viewer-owned,
  *  so they are always surfaced in autocomplete regardless of the source list —
  *  EXCEPT `REMOTE_UNSAFE_CANVAS_NAMES` when `remote`, which are structurally
  *  omitted rather than offered-then-blocked, so a remote attach's autocomplete
@@ -255,7 +267,7 @@ export function commandAutocompleteItems(commands = BUILTIN_SLASH_COMMANDS, remo
 // ---------------------------------------------------------------------------
 // Canvas commands — native reimplementations of the canvas chrome extensions.
 // ---------------------------------------------------------------------------
-/** Dispatch one of the four native canvas commands. Always returns `true` (the
+/** Dispatch one of the native canvas commands. Always returns `true` (the
  *  command is viewer-owned — never forwarded to the engine as a prompt). */
 function dispatchCanvasCommand(name, arg, ctx) {
     // Structural omission (withCanvasCommands) keeps these out of remote-mode
@@ -268,10 +280,8 @@ function dispatchCanvasCommand(name, arg, ctx) {
     }
     switch (name) {
         case 'graph':
-            // `/graph` is inherently the in-process GRAPH overlay (canvas-nav.ts
-            // `toggleGraph`), NOT a tmux popup. The overlay is Unit C/Q's surface; this
-            // unit registers the command + autocomplete entry and triggers the overlay
-            // via the `onGraph` hook the integration unit wires in.
+            // `/graph` opens the attach viewer's in-process GRAPH overlay, not a tmux
+            // popup. Dispatch reaches it through the viewer integration's `onGraph` hook.
             if (ctx.onGraph)
                 ctx.onGraph();
             else
@@ -292,6 +302,11 @@ function dispatchCanvasCommand(name, arg, ctx) {
             // A read-only nvim explorer over this node's + its subscriptions' context
             // dirs, as a self-contained popup.
             return openContext(ctx);
+        case 'rename':
+            renameNode(arg, ctx);
+            return true;
+        case 'color':
+            return colorNode(arg, ctx);
         default:
             ctx.notify(`/${name} is not available in attach`);
             return true;
@@ -350,6 +365,112 @@ function promoteNode(arg, ctx) {
         });
     });
 }
+/** `/rename <name>` — rename this node EVERYWHERE the name shows (à la Claude
+ *  Code's rename): (1) the pi session name, which is what the editor's title
+ *  chip ("bubble") paints — sent as a `set_session_name` frame so the chip
+ *  updates on the session_info_changed round-trip; (2) the tmux pane title
+ *  (visible with pane-border-status / terminal titles); (3) the canvas node row
+ *  via `crtr node config --name`, which also renames the live viewer window. */
+function renameNode(arg, ctx) {
+    const nodeId = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').trim();
+    if (nodeId === '') {
+        ctx.notify('/rename: no node to rename (viewer has no node id)');
+        return;
+    }
+    if (arg === '') {
+        ctx.notify('Usage: /rename <name>');
+        return;
+    }
+    // 1. Session name → the editor title chip repaints when the state echoes back.
+    ctx.send({ type: 'set_session_name', name: arg });
+    // 2. tmux pane title (best-effort; no-op outside tmux).
+    const pane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] !== undefined && pane !== undefined && pane !== '') {
+        execFile('tmux', ['select-pane', '-t', pane, '-T', arg], () => {
+            /* best-effort */
+        });
+    }
+    // 3. Canvas node row + live viewer window.
+    execFile('crtr', ['node', 'config', '--node', nodeId, '--name', arg, '--json'], { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        if (err) {
+            // On a non-zero exit crtr still prints the structured error to stdout.
+            let msg = null;
+            try {
+                const payload = JSON.parse(stdout);
+                msg = typeof payload.message === 'string' ? payload.message : null;
+            }
+            catch {
+                msg = null;
+            }
+            ctx.notify(`rename failed: ${msg ?? err.message}`);
+            return;
+        }
+        ctx.notify(`Renamed node → ${arg}`);
+    });
+}
+/** Promisified one-shot tmux call — resolves stdout ('' on error; best-effort). */
+function tmuxCall(args) {
+    return new Promise((resolve) => {
+        execFile('tmux', args, { timeout: 5_000 }, (err, stdout) => resolve(err ? '' : stdout));
+    });
+}
+/** Paint (or clear) THIS pane's border color. `pane-border-style` is a WINDOW
+ *  option — tmux silently hoists a `set-option -p` to window scope, painting
+ *  every pane — so per-pane color rides a per-pane user option instead: the
+ *  color lands in `@crtr_color` on this pane only, and the window's border
+ *  styles are set ONCE to a format tmux expands per pane (`fg=#{@crtr_color}`
+ *  when set, else the style that was in effect before — baked in at install
+ *  time so uncolored panes keep the user's theme). Clearing just unsets
+ *  `@crtr_color`; the format's fallback branch restores the original look. */
+async function paintPaneBorder(pane, value, clear) {
+    if (clear) {
+        await tmuxCall(['set-option', '-p', '-u', '-t', pane, '@crtr_color']);
+        return;
+    }
+    await tmuxCall(['set-option', '-p', '-t', pane, '@crtr_color', value]);
+    for (const opt of ['pane-border-style', 'pane-active-border-style']) {
+        const cur = (await tmuxCall(['show-options', '-wqv', '-t', pane, opt])).trim();
+        if (cur.includes('@crtr_color'))
+            continue; // our format is already installed on this window
+        // Bake the pre-existing effective style into the fallback branch (window
+        // value, else global, else tmux's defaults) — commas escaped so they don't
+        // split the #{?,,} conditional.
+        let base = cur !== '' ? cur : (await tmuxCall(['show-options', '-gqv', opt])).trim();
+        if (base === '')
+            base = opt === 'pane-active-border-style' ? 'fg=green' : 'default';
+        const fmt = `#{?#{!=:#{@crtr_color},},fg=#{@crtr_color},${base.replace(/,/g, '#,')}}`;
+        await tmuxCall(['set-option', '-w', '-t', pane, opt, fmt]);
+    }
+}
+/** `/color <color>` — color this node's two identity surfaces in one stroke:
+ *  the tmux PANE OUTLINE (via `paintPaneBorder` above — per-pane, not the whole
+ *  window) and the editor's NAME CHIP (the bubble `/rename` names), via the
+ *  `onColor` hook attach-cmd wires. Ephemeral by design: the border rides the
+ *  tmux pane and the chip lives in this viewer process. `/color none` clears
+ *  both. Remote-SAFE: both surfaces are local to this viewer. */
+function colorNode(arg, ctx) {
+    const value = arg.trim().toLowerCase();
+    if (value === '') {
+        ctx.notify('Usage: /color <color> — a name (red, blue, orange…), colourN, or #rrggbb; /color none to clear');
+        return true;
+    }
+    const clear = value === 'none' || value === 'clear';
+    const valid = clear || TMUX_NAMED_COLORS.has(value) || /^colour\d{1,3}$/.test(value) || /^#[0-9a-f]{6}$/.test(value);
+    if (!valid) {
+        ctx.notify(`Invalid color "${value}" — use a tmux colour name (${['red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'orange'].join(', ')}, …), colourN, or #rrggbb`);
+        return true;
+    }
+    // Pane outline — per-pane @crtr_color + a per-pane-expanded window format,
+    // so only THIS node's pane recolors (fire-and-forget; best-effort).
+    const pane = process.env['TMUX_PANE'];
+    const inTmux = process.env['TMUX'] !== undefined && pane !== undefined && pane !== '';
+    if (inTmux)
+        void paintPaneBorder(pane, value, clear);
+    // Name chip — the viewer owns the editor, so this rides the onColor hook.
+    ctx.onColor?.(clear ? null : value);
+    ctx.notify(clear ? 'Node color cleared' : `Node colored ${value}${inTmux ? '' : ' (chip only — no tmux pane)'}`);
+    return true;
+}
 /** `/resume-node`. Opens `crtr canvas browse` as a tmux popup,
  *  scoped to this node's cwd; on Enter it focuses the chosen node back into this
  *  pane via `crtr node focus --pane` (which `canvas browse` shells). */

package/dist/clients/attach/titled-editor.d.ts

@@ -1,7 +1,12 @@
 import { CustomEditor } from '@earendil-works/pi-coding-agent';
 import { type EditorOptions, type EditorTheme, type TUI } from '@earendil-works/pi-tui';
 /** Thinking levels pi cycles through (shift+tab), lowest → highest budget. */
-export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** Build a title-chip styler for a `/color` token (a tmux colour name, `#rrggbb`,
+ *  or `colourN`): the colour as the chip BACKGROUND with contrast-picked bold
+ *  text, matching the thinking-chip treatment. `undefined` for an unrenderable
+ *  token (e.g. `default`) — the caller keeps its fallback style. */
+export declare function colorChipStyle(token: string): ((s: string) => string) | undefined;
 /** The default (thinking `off`) title chip: reverse video + a space of padding
  *  each side, so the name reads as a label sitting on the border rule. Used as
  *  the fallback when no thinking color applies. */
@@ -20,6 +25,7 @@ export declare function thinkingTitleStyle(level: string | undefined, fallback:
  *  and truncates when it only partially fits. Exported pure for the overflow
  *  regression test. */
 export declare function composeTopBorder(width: number, title: string, info: string, titleStyle: (s: string) => string, borderColor: (s: string) => string): string;
+export declare function outlineCursorLine(line: string): string | undefined;
 export declare class TitledEditor extends CustomEditor {
     /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
      *  against. We keep a reference so `handleInput` can resolve the newline chord
@@ -51,5 +57,10 @@ export declare class TitledEditor extends CustomEditor {
     titleStyle: (s: string) => string;
     /** Mode badge colorizer, matched to the current mode type. */
     modeStyle: (s: string) => string;
+    /** Whether the hosting tmux pane / terminal window has FOCUS (terminal focus
+     *  reporting, DECSET 1004 — attach-cmd flips this on `\x1b[I` / `\x1b[O`).
+     *  Distinct from TUI component focus: the editor keeps component focus while
+     *  its pane is blurred. False → the fake cursor renders as an outline. */
+    paneFocused: boolean;
     render(width: number): string[];
 }

package/dist/clients/attach/titled-editor.js

@@ -6,16 +6,16 @@
 //      on each state update), mirroring pi's `getThinkingBorderColor`.
 // Both are pure render-layer chrome; nothing here touches the socket or session.
 import { CustomEditor } from '@earendil-works/pi-coding-agent';
-import { truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
-/** The thinking color scale is a deliberate cool→warm ramp between a blue and
- *  its orange complement, evenly spaced across the five active levels so each
- *  step stays readable without jumping through unrelated hues. `off` falls
- *  back to the caller's default border color. The endpoints are deliberately
- *  deep (not bright) hues: the same colors double as the title-chip BACKGROUND
- *  under bold white text, so every step must clear ~4.5:1 white-on-color
- *  contrast — a lighter blue/orange washes the label out. */
+import { CURSOR_MARKER, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+/** The standard thinking levels form a deliberate cool→warm ramp between blue
+ *  and its orange complement. `max` is a distinct, intense cyan endpoint so it
+ *  never falls back to the neutral default border. `off` alone falls back to
+ *  the caller's default border color. The colors double as title-chip
+ *  BACKGROUNDS under bold white text, so each must remain dark enough for the
+ *  label to read clearly. */
 const THINKING_START = [46, 92, 190]; // deep blue
 const THINKING_END = [166, 98, 24]; // deep amber
+const THINKING_MAX = [0, 145, 170]; // intense cyan
 function interpolateRgb(start, end, t) {
     return [
         Math.round(start[0] + (end[0] - start[0]) * t),
@@ -30,7 +30,55 @@ const THINKING_RGB = {
     medium: interpolateRgb(THINKING_START, THINKING_END, 2 / 4),
     high: interpolateRgb(THINKING_START, THINKING_END, 3 / 4),
     xhigh: interpolateRgb(THINKING_START, THINKING_END, 4 / 4),
+    max: THINKING_MAX,
 };
+/** Named colours `/color` accepts, as RGB — mirrors the tmux colour-name table
+ *  (so the chip and the pane border read as the same hue). */
+const NAMED_RGB = {
+    black: [0, 0, 0],
+    red: [205, 49, 49],
+    green: [13, 188, 121],
+    yellow: [229, 229, 16],
+    blue: [36, 114, 200],
+    magenta: [188, 63, 188],
+    cyan: [17, 168, 205],
+    white: [229, 229, 229],
+    orange: [228, 152, 68],
+    grey: [128, 128, 128],
+    gray: [128, 128, 128],
+    brightred: [241, 76, 76],
+    brightgreen: [35, 209, 139],
+    brightyellow: [245, 245, 67],
+    brightblue: [59, 142, 234],
+    brightmagenta: [214, 112, 214],
+    brightcyan: [41, 184, 219],
+};
+/** Build a title-chip styler for a `/color` token (a tmux colour name, `#rrggbb`,
+ *  or `colourN`): the colour as the chip BACKGROUND with contrast-picked bold
+ *  text, matching the thinking-chip treatment. `undefined` for an unrenderable
+ *  token (e.g. `default`) — the caller keeps its fallback style. */
+export function colorChipStyle(token) {
+    const t = token.trim().toLowerCase();
+    const c256 = /^colour(\d{1,3})$/.exec(t);
+    if (c256 !== null)
+        return (s) => `\x1b[48;5;${c256[1]}m\x1b[97m\x1b[1m ${s} \x1b[0m`;
+    let rgb;
+    const hex = /^#([0-9a-f]{6})$/.exec(t);
+    if (hex !== null) {
+        const h = hex[1];
+        rgb = [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+    }
+    else {
+        rgb = NAMED_RGB[t];
+    }
+    if (rgb === undefined)
+        return undefined;
+    const [r, g, b] = rgb;
+    // Pick black-on-light / white-on-dark so the name stays readable on any hue.
+    const luma = 0.299 * r + 0.587 * g + 0.114 * b;
+    const fg = luma > 160 ? '\x1b[30m' : '\x1b[97m';
+    return (s) => `\x1b[48;2;${r};${g};${b}m${fg}\x1b[1m ${s} \x1b[0m`;
+}
 /** The default (thinking `off`) title chip: reverse video + a space of padding
  *  each side, so the name reads as a label sitting on the border rule. Used as
  *  the fallback when no thinking color applies. */
@@ -71,6 +119,39 @@ export function composeTopBorder(width, title, info, titleStyle, borderColor) {
     const fill = Math.max(0, width - chipW - visibleWidth(infoChip));
     return chip + borderColor('─'.repeat(fill)) + infoChip;
 }
+/** The stock pi-tui editor paints its fake cursor as a solid reverse-video
+ *  block (`\x1b[7m…\x1b[0m`) unconditionally — in a wall of attach panes every
+ *  pane shows an identical solid white cursor, and nothing tells you which one
+ *  keys actually go to. When the hosting pane/terminal is UNFOCUSED we rewrite
+ *  that cell into a MUTED cursor, mirroring how real terminals de-emphasize
+ *  the hardware cursor on blur. A pixel-true full-cell outline isn't possible
+ *  in text cells, and hollow-box glyphs (▯/⍘/□) render undersized, so the
+ *  muted form is a full-size block in a dim gray background — same footprint
+ *  as the focused cursor, clearly not the bright active one (ruling: tried the
+ *  glyphs, Silas preferred the dim block). The rewrite anchors on pi-tui's
+ *  zero-width CURSOR_MARKER (emitted right before the fake cursor while the
+ *  editor component has TUI focus) so it can never touch reverse video
+ *  elsewhere in the line. Returns undefined when the line carries no cursor.
+ *  Exported pure for tests. */
+const SOLID_CURSOR_PREFIX = '\x1b[7m';
+const SOLID_CURSOR_RESET = '\x1b[0m';
+/** Dim gray bg, default fg — the char under the cursor stays readable. */
+const MUTED_CURSOR_ON = '\x1b[48;5;240m';
+export function outlineCursorLine(line) {
+    const m = line.indexOf(CURSOR_MARKER);
+    if (m === -1)
+        return undefined;
+    const start = m + CURSOR_MARKER.length;
+    if (!line.startsWith(SOLID_CURSOR_PREFIX, start))
+        return undefined;
+    const gStart = start + SOLID_CURSOR_PREFIX.length;
+    const end = line.indexOf(SOLID_CURSOR_RESET, gStart);
+    if (end === -1)
+        return undefined;
+    const grapheme = line.slice(gStart, end);
+    const replacement = `${MUTED_CURSOR_ON}${grapheme}\x1b[0m`;
+    return line.slice(0, start) + replacement + line.slice(end + SOLID_CURSOR_RESET.length);
+}
 export class TitledEditor extends CustomEditor {
     /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
      *  against. We keep a reference so `handleInput` can resolve the newline chord
@@ -114,8 +195,22 @@ export class TitledEditor extends CustomEditor {
     titleStyle = defaultTitleStyle;
     /** Mode badge colorizer, matched to the current mode type. */
     modeStyle = defaultTitleStyle;
+    /** Whether the hosting tmux pane / terminal window has FOCUS (terminal focus
+     *  reporting, DECSET 1004 — attach-cmd flips this on `\x1b[I` / `\x1b[O`).
+     *  Distinct from TUI component focus: the editor keeps component focus while
+     *  its pane is blurred. False → the fake cursor renders as an outline. */
+    paneFocused = true;
     render(width) {
         const lines = super.render(width);
+        if (!this.paneFocused) {
+            for (let i = 0; i < lines.length; i++) {
+                const hollowed = outlineCursorLine(lines[i]);
+                if (hollowed !== undefined) {
+                    lines[i] = hollowed;
+                    break;
+                }
+            }
+        }
         if ((this.title || this.info) && lines.length > 0) {
             // Replace the stock top border; dashes in the current (thinking-aware)
             // border color.

package/dist/commands/canvas-browse.js

@@ -1,6 +1,6 @@
 // `crtr canvas browse` — the interactive full-screen canvas navigator.
 //
-// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Flagged), an
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Attention/Pinned), an
 // auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
 // `crtr node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
 // Owns the screen, so it returns void and writes nothing to stdout itself.
@@ -14,7 +14,7 @@ import { readState } from '../core/config.js';
 export const browseLeaf = defineLeaf({
     name: 'browse',
     description: 'open the interactive canvas navigator (tabs/tree/search)',
-    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Flagged), an expandable tree (children auto-collapsed; → to expand), and `/` fuzzy search that auto-expands ancestors of matches; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Attention/Pinned), an expandable tree (children auto-collapsed; → to expand), `/` fuzzy search, `f` to pin, `m` to message and `R` to rename a node in place, and `?` for the full keymap; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
     help: {
         name: 'canvas browse',
         summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr node focus`. Outside a TTY it prints the static forest and exits',

package/dist/commands/memory/lint.js

@@ -11,6 +11,8 @@ import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
@@ -101,14 +103,14 @@ function lintFile(file, substrateStore, findings) {
 export const lintLeaf = defineLeaf({
     name: 'lint',
     description: 'validate frontmatter across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation; also flags any dir the selected profile manages that lacks an AGENTS.md operating guide. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
     help: {
         name: 'memory lint',
         summary: 'strict-parse frontmatter across the bounded corpus; non-zero exit on any finding',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for AGENTS.md)}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
         ],
         outputKind: 'object',
@@ -121,10 +123,14 @@ export const lintLeaf = defineLeaf({
         // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
         // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
+        //    Hidden dirs are skipped to mirror doc enumeration (a dot-segment
+        //    path never yields a doc name, so e.g. the maintainer store shipped
+        //    at builtin-memory/.crouter can never register) — lint must not
+        //    flag files the substrate can never load.
         const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
                 return;
-            for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+            for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
                 if (!relative(dir, file).split(sep).join('/'))
                     continue;
                 memoryCount += 1;
@@ -145,6 +151,34 @@ export const lintLeaf = defineLeaf({
                     lintDir(pluginMemoryDir(plugin));
             }
         }
+        // Profile coverage: the selected profile's manifest names the dirs the
+        // operator manages. Lint the profile's own store, and require every
+        // managed project dir to carry an always-loaded operating guide
+        // (.crouter/memory/AGENTS.md) — a managed dir without one boots every
+        // agent there blind, so its absence is an authoring finding like any
+        // schema violation. (The managed dirs' stores themselves already lint
+        // above: projectScopeRoots folds the profile's project pointers in.)
+        let profileProjects = 0;
+        const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
+        if (profileIdOrName) {
+            try {
+                const { profileId, manifest } = loadProfileManifest(profileIdOrName);
+                lintDir(profileMemoryDir(profileId));
+                for (const dir of manifest.projects) {
+                    profileProjects += 1;
+                    if (!pathExists(join(dir, '.crouter', 'memory', 'AGENTS.md'))) {
+                        findings.push({
+                            path: dir,
+                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/AGENTS.md — author its always-loaded operating guide (name the doc AGENTS, target the dir with --dir; run \`crtr memory write -h\` first)`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Unresolvable profile (deleted/corrupt manifest): profile coverage
+                // just doesn't apply — the file corpus above already linted fully.
+            }
+        }
         const checked = memoryCount;
         if (findings.length > 0) {
             // Human/agent path renders only the message — surface every offender as
@@ -154,12 +188,12 @@ export const lintLeaf = defineLeaf({
             throw general(`memory lint: ${findings.length} finding(s) across ${checked} files`, {
                 checked,
                 findings: findings.map((f) => ({ path: f.path, error: f.error })),
-                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate), then re-run `crtr memory lint`.',
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate); for a profile-managed dir missing AGENTS.md, author one — run `crtr memory write -h` — then re-run `crtr memory lint`.',
             });
         }
         return {
             checked,
-            corpora: { memory_stores: memoryCount },
+            corpora: { memory_stores: memoryCount, profile_projects: profileProjects },
             findings: [],
             follow_up: 'Corpus green — zero invalid frontmatter docs.',
         };

package/dist/commands/memory/write.js

@@ -15,6 +15,7 @@ export const writeLeaf = defineLeaf({
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
             'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
             'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'AGENTS.md is the one special doc: a store’s always-loaded operating guide, and every dir a profile manages should carry one (`crtr memory lint` flags the gaps). Name the doc AGENTS, target the exact dir with --dir, and set system-prompt-visibility to `content` so every agent working there boots with it. It is a front door, not a manual — constraints and gotchas, the key commands, a few sentences of architecture orientation, and only the conventions that differ from defaults. Every line is paid by every session in that dir forever: prefer a pointer (“when X, run Y -h / read Z, because W”) over inlined how-to, and cut any line that would not change an agent’s behavior.\n\n' +
             'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +

package/dist/commands/node.js

@@ -137,7 +137,7 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with). Mutually exclusive with --worktree.' },
             { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on local `main`; the child\'s cwd is pinned there, and it lands the work serially onto local main later with `crtr node worktree close`. Mutually exclusive with --root.' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
-            { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Override the model the node runs on: exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (anthropic|openai + ultra|strong|medium|light, e.g. openai/ultra — pin a specific model family, useful for spawning cross-family children), a bare capability TIER (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku). Must resolve to a concrete model OFFLINE — unlike `node config --model`, no live broker exists yet at spawn to free-text substring-search a registry. Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
+            { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Override the model the node runs on: a `provider/tier` (anthropic|openai + ultra|strong|medium|light, e.g. openai/ultra — pin a specific model family, useful for spawning cross-family children), a bare capability TIER (ultra|strong|medium|light), a family alias (opus|sonnet|haiku), or an exact `provider/id` for a concrete model. Must resolve to a concrete model OFFLINE — unlike `node config --model`, no live broker exists yet at spawn to free-text substring-search a registry. Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (which may be none, e.g. a historical null-profile parent). A shell/no-spawner root with no profile coverage instead runs the startup selector and can persist the stable root profile. --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
             { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context — current situation (e.g. which applet/page spawned this), NOT the visible prompt. Appended as a `<situational-context>` sibling block in the injected bearings, never as visible chat. Preserved unchanged into a deferred --at/--every/--when node_birth recipe.' },
             { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. The spawned node gets a `submit` tool shaped by this schema, must call it to finish, and the submitted JSON is written to the final report and context/result.json. Rejected with trigger flags in this version.' },
@@ -188,7 +188,7 @@ const nodeNew = defineLeaf({
                 throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Pass a `provider/id`, a `provider/tier` (e.g. openai/ultra), a tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).' });
             }
             if (!normalizeModel(modelSpec).includes('/')) {
-                throw new InputError({ error: 'unresolvable_model', message: `'${modelSpec}' does not resolve to a concrete model`, field: 'model', next: 'Pass an exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (e.g. openai/ultra), a tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku) — a live-broker substring search (like `node config --model`) is not available at spawn.' });
+                throw new InputError({ error: 'unresolvable_model', message: `'${modelSpec}' does not resolve to a concrete model`, field: 'model', next: 'Pass a `provider/tier` (e.g. openai/ultra), a tier (ultra|strong|medium|light), a family alias (opus|sonnet|haiku), or an exact `provider/id` — a live-broker substring search (like `node config --model`) is not available at spawn.' });
             }
         }
         const model = modelSpec;
@@ -869,7 +869,7 @@ const nodeConfig = defineLeaf({
             else {
                 const normalized = normalizeModel(modelSpec);
                 if (!normalized.includes('/')) {
-                    throw new InputError({ error: 'unresolvable_dormant', message: `'${modelSpec}' does not resolve to a concrete model for a dormant node`, field: 'model', next: 'Pass an exact `provider/id` (e.g. openai-codex/gpt-5.5) or a tier/alias — the live registry search is only available while the node\'s broker is up.' });
+                    throw new InputError({ error: 'unresolvable_dormant', message: `'${modelSpec}' does not resolve to a concrete model for a dormant node`, field: 'model', next: 'Pass a `provider/tier` (e.g. openai/ultra) or a tier/alias — the live registry search is only available while the node\'s broker is up.' });
                 }
                 persistDormantModel(nodeId, normalized);
                 resolved = normalized;
@@ -911,6 +911,10 @@ const nodeConfig = defineLeaf({
                 lifecycle: newLifecycle,
                 hasManager: meta.parent !== null,
                 model: meta.model_override ?? undefined,
+                // The TARGET node's cwd + profile — profile-scope kind defaults must
+                // resolve for the node being reconfigured, not the calling process.
+                cwd: meta.cwd,
+                profileId: meta.profile_id,
             });
             meta = updateNode(nodeId, {
                 ...(kindSpec !== undefined ? { kind: newKind } : {}),
@@ -1655,6 +1659,8 @@ function setLifecycle(id, value, opts) {
         lifecycle: value,
         hasManager: target.parent !== null,
         model: target.model_override ?? undefined,
+        cwd: target.cwd,
+        profileId: target.profile_id,
     });
     const meta = updateNode(id, { lifecycle: value, launch });
     // --detach: stop foregrounding the agent by closing its viewer pane (the
@@ -1723,6 +1729,7 @@ const nodeYield = defineLeaf({
     help: {
         name: 'node yield',
         summary: 'request a context refresh — you will be respawned fresh against your roadmap on your next stop (a base node auto-promotes to orchestrator first); optionally change your kind or model as you refresh',
+        guide: 'A yield discards everything that lives only in this window, so externalize first: checkpoint context/roadmap.md, and if you are holding a question for the human you have not actually posed, post it via `crtr human ask` before yielding — an in-flight ask survives the refresh and its answer wakes your fresh revive — then note the pending ask in your yield message so the fresh window knows what the answer settles.',
         params: [
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh — change your kind to this (developer, review, spec, design, plan, explore, general); a base node also auto-promotes into an orchestrator of this kind. Defaults to your current kind.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
@@ -1976,13 +1983,13 @@ export function registerNode() {
         rootEntry: {
             concept: 'a unit of the agent runtime — an agent on the canvas with its own context dir and pi vehicle. Spawning nodes is how work gets done here, not an optimization you reach for late',
             desc: 'spawn, inspect, and navigate nodes on the canvas',
-            useWhen: 'delegating work, or walking the subscription graph. CRITICAL, and your default reflex — spawning a child is the first move on almost any task, not a fallback. Your own context window is the scarce resource: before you read files into it to understand, implement, debug, or change code you do not already know, hand that to a fresh node and get back just the conclusion, matching the node kind to the work. Keep inline only a fact you already know. Fan out independent units as CONCURRENT children — a wake with idle workers is wasted; serialize only true dependencies, and never let two live children edit the same files. Once you delegate a unit, do not also run it yourself: you auto-subscribe on spawn, so its finish wakes you. Use the help surface for the exact node contract before invoking it.'
+            useWhen: 'delegating a genuinely independent subtask, or walking the subscription graph. Base nodes work hands-on; orchestrators fan out. Give each child a bounded outcome distinct from your whole assignment so delegation moves work toward completion instead of recursively passing it down. Once delegated, do not duplicate the child’s work; its finish wakes you. Use the help surface for the exact node contract before invoking it.'
         },
         help: {
             name: 'node',
             summary: 'spawn and navigate canvas nodes',
             model: 'Every agent is a node in one directed graph (the canvas); `subscribes_to` is the spine — spawn a child and you auto-subscribe (active) to it, so its finish wakes you.\n\n' +
-                'WHEN TO DELEGATE: hand any self-contained unit of work to a child instead of doing it inline — it keeps your own context window (your scarce resource) free for steering. Spawn independent units in PARALLEL; a wake with idle workers is wasted. Serialize only true dependencies, and never let two live children edit the same files.\n\n' +
+                'WHEN TO DELEGATE: base nodes work hands-on and spawn only genuinely independent subtasks; orchestrators decompose and fan out. A child owns a bounded outcome distinct from the caller’s whole assignment. Spawn independent units in PARALLEL, serialize true dependencies, and never let two live children edit the same files.\n\n' +
                 'HOW: the new leaf returns a node id immediately and runs the worker as a detached headless broker; no viewer opens unless a surface asks for one. Match the kind to the work and read the leaf schema before invoking. You are woken when a child finishes — the wake message ALREADY IS the coalesced digest, so dereference the report paths in that digest that matter instead of acting on a one-line label. Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with a final push, which writes the canonical result, marks done, and closes the window; stopping without it is not finishing. For a job too big for one context window, promote to an orchestrator; when context fills, yield to refresh against that roadmap.',
         },