@crouton-kit/crouter 0.3.48 → 0.3.50

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

@@ -10,9 +10,12 @@ 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. */
-const THINKING_START = [68, 120, 228]; // blue
-const THINKING_END = [228, 152, 68]; // orange
+ *  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. */
+const THINKING_START = [46, 92, 190]; // deep blue
+const THINKING_END = [166, 98, 24]; // deep amber
 function interpolateRgb(start, end, t) {
     return [
         Math.round(start[0] + (end[0] - start[0]) * t),

package/dist/commands/human/prompts.js

@@ -36,7 +36,7 @@ export const humanAsk = defineLeaf({
     help: {
         name: 'human ask',
         summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. This is the default, expected channel for posing ANY question or decision to the user — reach for it instead of writing the question as prose in your reply.',
-        guide: 'Use exactly one of these forms: `crtr human ask "<question>"` for a simple open-text prompt (the CLI builds a one-item humanloop deck internally), or `crtr human ask --context-file deck.json` for a fully structured deck. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        guide: 'Use exactly one of these forms: `crtr human ask "<question>"` for a simple open-text prompt (the CLI builds a one-item humanloop deck internally), or `crtr human ask --context-file deck.json` for a fully structured deck. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. Author a GOOD deck: ask only what materially changes your next step (each question spends the human\'s attention), offer genuine alternatives as `options` (not one real pick plus filler), and layer content by progressive disclosure — `title` a short topic, `subtitle` the one-sentence TL;DR, `body` the plain-language detail with denser material under a `## Details` heading the reader can skip.',
         params: [
             { kind: 'positional', name: 'question', type: 'string', required: false, constraint: 'Bare-question shorthand for a simple open-text ask. Mutually exclusive with `--context-file`.' },
             { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict complex-ask deck JSON. Use this when you need multiple interactions, options, or other deck structure. Mutually exclusive with the question shorthand.', shape: DECK_SCHEMA_HINT },

package/dist/commands/human/shared.js

@@ -5,9 +5,13 @@ import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
 import { countPanesInWindow, spawnAndDetach, shellQuote, attachedClientPane, paneAlive, } from '../../core/spawn.js';
 import { graphSurfaceTarget } from '../../core/runtime/placement.js';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
-    'source?:{sessionName?,askedBy?,blockedSince?}, ' +
-    'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
-    'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
+    'source?:{sessionName?,askedBy?,blockedSince?}, interactions:[{id, ' +
+    'title (short ≤~4-word topic — the thing being decided, not the decision), ' +
+    'subtitle? (ONE plain-English sentence — the TL;DR/stakes, not a paragraph), ' +
+    '(body?|bodyPath?) (the full explanation and the ONLY place for long or rich ' +
+    'prose — directive-flavored markdown rendered by termrender; never put the ' +
+    'wall of detail in subtitle), options:[{id,label,description?}], multiSelect?, ' +
+    'allowFreetext?, freetextLabel?, ' +
     "kind?:'notify'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;

package/dist/commands/memory/write.js

@@ -12,7 +12,9 @@ export const writeLeaf = defineLeaf({
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
         guide: 'The body is the easy part; the craft is routing — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
+            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, 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. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\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

@@ -22,6 +22,7 @@ import { nodeContextLeaf } from './node-context.js';
 import { nodeArtifactsLeaf } from './node-inspect-artifacts.js';
 import { nodeWorktreeBranch } from './node-worktree.js';
 import { nodeReviveLeaf } from './node-lifecycle-revive.js';
+import { isPidAlive } from '../core/canvas/pid.js';
 import { recycleNode } from '../core/runtime/recycle.js';
 import { readFaultAsync } from '../core/runtime/fault.js';
 import { activeFaultForDisplay } from '../core/canvas/render.js';
@@ -34,7 +35,7 @@ import { appendInbox } from '../core/feed/inbox.js';
 import { readMergedLaunchConfig } from '../core/config.js';
 import { listProfiles } from '../core/profiles/manifest.js';
 import { stateBlock } from '../core/help.js';
-import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, view, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
+import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, contextDir, reportsDir, nodeArtifacts, readContextTokens, view, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
 // off yielding than holding its fat window open for the child's result: the
 // child's finish revives it fresh against its roadmap, so a clean window absorbs
@@ -436,26 +437,42 @@ const nodeList = defineLeaf({
 // ---------------------------------------------------------------------------
 // node inspect show — a node + its place in the spine
 // ---------------------------------------------------------------------------
+// Enrich a bare subscription edge with the neighbor's name/kind/status so a
+// debugger reads who a report/manager IS without a second `show` per id.
+function enrichNeighbor(ref) {
+    const n = getNode(ref.node_id);
+    return {
+        node_id: ref.node_id,
+        name: n ? fullName(n) : '(missing)',
+        kind: n?.kind ?? '?',
+        status: n ? (n.intent ? `${n.status}/${n.intent}` : n.status) : '?',
+        active: ref.active,
+    };
+}
 const nodeShow = defineLeaf({
     name: 'show',
-    description: 'show a node + its spine neighbors',
-    whenToUse: 'you want one node in depth: its meta plus its spine neighbors — who it reports to (subscriptions) and who manages it (subscribers). Use `node inspect list` instead for the flat roster of every node, or `canvas dashboard` to see the whole-tree shape',
+    description: 'show a node + its spine neighbors, artifacts, and drill-in pointers',
+    whenToUse: 'you want one node in depth — the debugging entrypoint: a glanceable meta slice (status/intent, liveness, cwd, session file), its named spine neighbors (reports down, managers up), how many artifacts/triggers it has, and the exact next commands + on-disk paths to read its context/reports dirs and children. Use `node inspect list` instead for the flat roster of every node, or `canvas dashboard` to see the whole-tree shape',
     help: {
         name: 'node inspect show',
-        summary: 'show a node\'s meta plus its subscriptions (reports) and subscribers (managers)',
+        summary: 'show a node in depth — meta slice, named neighbors (reports/managers), artifact/trigger counts, and drill-in pointers (context dir, session file, children). The debugging entrypoint for one node.',
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id.' },
         ],
         output: [
-            { name: 'node', type: 'object', required: true, constraint: 'The node meta.' },
-            { name: 'reports', type: 'object[]', required: true, constraint: 'Who this node subscribes to (its reports/down).' },
-            { name: 'managers', type: 'object[]', required: true, constraint: 'Who subscribes to this node (its managers/up).' },
+            { name: 'node', type: 'object', required: true, constraint: 'The full node meta (system prompt + every telemetry field). The render surfaces a glanceable slice; `--json` carries the complete dump.' },
+            { name: 'reports', type: 'object[]', required: true, constraint: 'Who this node subscribes to (its reports/down), each enriched with {node_id, name, kind, status, active} — these are typically its spawned children.' },
+            { name: 'managers', type: 'object[]', required: true, constraint: 'Who subscribes to this node (its managers/up), same enriched shape.' },
+            { name: 'artifacts', type: 'object', required: true, constraint: 'Counts of what the node left on disk by corpus: {report, doc, roadmap}. Enumerate them with `node inspect artifacts <id>`.' },
+            { name: 'pending_triggers', type: 'number', required: true, constraint: 'How many clock/predicate triggers this node has armed. Inspect with `node triggers list --node <id>`.' },
+            { name: 'paths', type: 'object', required: true, constraint: 'Resolved on-disk locations: {context_dir, reports_dir, session_file} — read these directly to debug.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The concrete next commands to drill deeper.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: reads the node meta + canvas.db edges.'],
+        effects: ['Read-only: reads the node meta, canvas.db edges, on-disk artifacts, and armed triggers.'],
         // The node meta object inlines the full system prompt + every telemetry
-        // field — a machine-readable dump with no useful human-glance slice to
-        // synthesize (unlike dashboard/list's tabular rows), same rationale as
+        // field — a machine-readable dump we suppress from the viewer preview; the
+        // render below surfaces only a glanceable slice. Same preview rationale as
         // canvas snapshot / node inspect snapshot.
         preview: { suppressOutput: true },
     },
@@ -465,7 +482,75 @@ const nodeShow = defineLeaf({
         if (node === null) {
             throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
         }
-        return { node, reports: subscriptionsOf(id), managers: subscribersOf(id) };
+        const reports = subscriptionsOf(id).map(enrichNeighbor);
+        const managers = subscribersOf(id).map(enrichNeighbor);
+        const arts = nodeArtifacts(id, ['report', 'doc', 'roadmap']);
+        const artifacts = {
+            report: arts.filter((a) => a.source === 'report').length,
+            doc: arts.filter((a) => a.source === 'doc').length,
+            roadmap: arts.filter((a) => a.source === 'roadmap').length,
+        };
+        const pending_triggers = listTriggers({ node: id }).length;
+        const paths = {
+            context_dir: contextDir(id),
+            reports_dir: reportsDir(id),
+            session_file: node.pi_session_file ?? null,
+        };
+        // Auto-gathered drill-in pointers: the exact commands a debugger reaches for
+        // next, populated only when there is actually something behind them.
+        const hints = [];
+        const artTotal = artifacts.report + artifacts.doc + artifacts.roadmap;
+        if (artTotal > 0)
+            hints.push(`Read its ${artTotal} artifact(s): \`crtr node inspect artifacts ${id}\` → each ref feeds \`crtr canvas history read <ref>\`.`);
+        hints.push(`Browse its context + reports dirs (and its subscriptions') in nvim: \`crtr node inspect context ${id}\`.`);
+        if (paths.session_file)
+            hints.push(`Read the raw conversation transcript: ${paths.session_file}`);
+        hints.push(`On-disk context dir (ls/read directly): ${paths.context_dir}`);
+        if (pending_triggers > 0)
+            hints.push(`It has ${pending_triggers} armed trigger(s): \`crtr node triggers list --node ${id}\`.`);
+        if (reports.length > 0)
+            hints.push(`Drill into a child/report: \`crtr node inspect show <node_id>\` (${reports.map((r) => r['node_id']).join(', ')}).`);
+        hints.push(`Full machine dump (system prompt + all telemetry): \`crtr --json node inspect show ${id}\`.`);
+        return { node, reports, managers, artifacts, pending_triggers, paths, follow_up: hints.join('\n') };
+    },
+    render: (r) => {
+        const node = r['node'];
+        const id = String(node['node_id']);
+        const pid = node['pi_pid'];
+        const alive = isPidAlive(pid) ? 'alive' : 'dead';
+        const intent = node['intent'] ? `/${String(node['intent'])}` : '';
+        const parts = [];
+        // 1) Glanceable meta slice — the debug-critical fields, not the full dump.
+        parts.push(`# ${fullName(node)}  (${id})`);
+        const meta = [
+            `- kind/mode/lifecycle: ${node['kind']} / ${node['mode']} / ${node['lifecycle']}`,
+            `- status: ${node['status']}${intent}`,
+            `- broker pid: ${pid ?? '(none)'} — ${alive}`,
+            `- cwd: ${node['cwd']}`,
+            `- host: ${node['host_kind']}` + (node['profile_id'] ? ` · profile ${node['profile_id']}` : ''),
+            `- cycles: ${node['cycles']} · created ${node['created']}`,
+        ];
+        if (node['parent'])
+            meta.push(`- parent: ${node['parent']}`);
+        parts.push(meta.join('\n'));
+        // 2) Neighbor tables (reports down, managers up), pre-enriched with names.
+        const table = (label, rows) => {
+            if (rows.length === 0)
+                return `${label}: none`;
+            const cols = ['node_id', 'name', 'kind', 'status', 'active'];
+            const head = `| ${cols.join(' | ')} |`;
+            const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+            const body = rows.map((row) => `| ${cols.map((c) => String(row[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`).join('\n');
+            return `${rows.length} ${label}:\n\n${head}\n${sep}\n${body}`;
+        };
+        parts.push(table('reports (down — subscriptions, usually children)', r['reports']));
+        parts.push(table('managers (up — subscribers)', r['managers']));
+        // 3) On-disk footprint at a glance.
+        const a = r['artifacts'];
+        parts.push(`artifacts: ${a['report']} report(s), ${a['doc']} doc(s), ${a['roadmap']} roadmap · ${r['pending_triggers']} pending trigger(s)`);
+        // 4) Auto-gathered drill-in pointers.
+        parts.push(`Drill deeper:\n${String(r['follow_up'])}`);
+        return parts.join('\n\n');
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/profile/default.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const defaultBranch: BranchDef;

package/dist/commands/profile/default.js

@@ -0,0 +1,143 @@
+// `crtr profile default` — the per-cwd default-profile pin. A pin says "when a
+// node boots in THIS directory, use THIS profile" and stops the startup
+// chooser from asking. It is directory-scoped, not manifest state: independent
+// of a profile's project purview (`crtr profile project`). The startup menu's
+// `d` action writes the same pin; these verbs are the explicit surface for it.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { profileCoversCwd } from '../../core/profiles/select.js';
+import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, resolveBindingCwd, } from '../../core/profiles/default-binding.js';
+const setLeaf = defineLeaf({
+    name: 'set',
+    description: 'pin a profile as the default for the current directory',
+    whenToUse: 'you want crtr to stop asking which profile to use here and always default to a chosen one — the command form of the startup menu\u2019s `d` action. The profile must already cover this directory (add it with `crtr profile project add` first if not).',
+    help: {
+        name: 'profile default set',
+        summary: "pin a profile as the current directory's default, so the startup chooser stops asking",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name. Must already cover the current directory (be at/above/below it in its project purview).',
+            },
+        ],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: "The resolved directory the pin was set for." },
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The pinned profile id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The pinned profile name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes `default-profile.json` in the per-cwd workspace root. The next launch here auto-picks this profile with no prompt (override once with `crtr --pick-profile`).'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const entry = loadProfileManifest(_input['profile']);
+        if (!profileCoversCwd(entry, resolved)) {
+            throw new InputError({
+                error: 'not_covered',
+                message: `profile "${entry.manifest.name}" does not cover ${resolved}, so a default pinned here would be ignored.`,
+                next: `Widen its purview first: \`crtr profile project add ${entry.profileId} --dir ${resolved}\`, then re-run this.`,
+            });
+        }
+        setDefaultProfileId(cwd, entry.profileId);
+        return {
+            dir: resolved,
+            profile_id: entry.profileId,
+            name: entry.manifest.name,
+            follow_up: `Launches here now auto-pick "${entry.manifest.name}". Clear with \`crtr profile default clear\`, or reopen the chooser once with \`crtr --pick-profile\`.`,
+        };
+    },
+});
+const clearLeaf = defineLeaf({
+    name: 'clear',
+    description: "remove the current directory's default-profile pin",
+    whenToUse: 'you no longer want a fixed default here — go back to the normal startup chooser (MRU / covering menu). No-op if nothing was pinned.',
+    help: {
+        name: 'profile default clear',
+        summary: "remove the current directory's default-profile pin",
+        params: [],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: 'The resolved directory the pin was cleared for.' },
+            { name: 'cleared', type: 'boolean', required: true, constraint: 'True when a pin existed and was removed; false when nothing was pinned.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes `default-profile.json` from the per-cwd workspace root, if present.'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const had = getDefaultProfileId(cwd) !== null;
+        clearDefaultProfile(cwd);
+        return {
+            dir: resolved,
+            cleared: had,
+            follow_up: had
+                ? 'The startup chooser will ask again here. Re-pin with `crtr profile default set <profile>`.'
+                : 'Nothing was pinned here.',
+        };
+    },
+});
+const showLeaf = defineLeaf({
+    name: 'show',
+    description: "show the current directory's default-profile pin",
+    whenToUse: "you want to know which profile (if any) is pinned as this directory's default.",
+    help: {
+        name: 'profile default show',
+        summary: "report the current directory's pinned default profile, or none",
+        params: [],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: 'The resolved directory queried.' },
+            { name: 'pinned', type: 'boolean', required: true, constraint: 'True when a default is pinned here.' },
+            { name: 'profile_id', type: 'string', required: false, constraint: 'The pinned profile id, when pinned.' },
+            { name: 'name', type: 'string', required: false, constraint: 'The pinned profile name, when it still resolves.' },
+            { name: 'stale', type: 'boolean', required: false, constraint: 'True when a pin exists but its profile no longer resolves (deleted); the selector will self-heal it on next launch.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const id = getDefaultProfileId(cwd);
+        if (id === null) {
+            return {
+                dir: resolved,
+                pinned: false,
+                follow_up: 'Pin one with `crtr profile default set <profile>`.',
+            };
+        }
+        let name;
+        try {
+            name = loadProfileManifest(id).manifest.name;
+        }
+        catch {
+            name = undefined;
+        }
+        return {
+            dir: resolved,
+            pinned: true,
+            profile_id: id,
+            ...(name !== undefined ? { name } : { stale: true }),
+            follow_up: name !== undefined
+                ? 'Change it with `crtr profile default set <profile>`, or clear it with `crtr profile default clear`.'
+                : 'This profile no longer exists; clear the stale pin with `crtr profile default clear`.',
+        };
+    },
+});
+export const defaultBranch = defineBranch({
+    name: 'default',
+    description: "manage this directory's default-profile pin",
+    whenToUse: "setting, clearing, or inspecting which profile a directory defaults to at startup — so crtr stops asking. Directory-scoped, independent of a profile's project purview.",
+    help: {
+        name: 'profile default',
+        summary: "the per-directory default profile — pin one so the startup chooser stops asking",
+        model: "A pin binds the CURRENT directory to a profile: launches here auto-pick it with no prompt (`crtr --pick-profile` reopens the chooser once). `set` pins a profile (which must already cover this dir), `clear` removes the pin, `show` reports it. This is directory-scoped selection, NOT manifest state — independent of `crtr profile project` (a profile's purview). The startup menu's `d` action writes the same pin.",
+    },
+    children: [setLeaf, clearLeaf, showLeaf],
+});

package/dist/commands/profile/new.js

@@ -3,7 +3,7 @@ import { createProfile, profileRoot } from '../../core/profiles/manifest.js';
 export const newLeaf = defineLeaf({
     name: 'new',
     description: 'create a new profile',
-    whenToUse: 'you are establishing a new agent identity — a stable id, a display name, and its own memory store. Pass at most one initial project directory here (the parser has no repeatable-flag support); use `profile add-project` afterward for every additional one.',
+    whenToUse: 'you are establishing a new agent identity — a stable id, a display name, and its own memory store. Pass at most one initial project directory here (the parser has no repeatable-flag support); use `profile project add` afterward for every additional one.',
     help: {
         name: 'profile new',
         summary: 'create a profile: `<profiles-root>/<slug>-<id>/` with a manifest + its own `memory/` store',
@@ -20,7 +20,7 @@ export const newLeaf = defineLeaf({
                 name: 'project',
                 type: 'path',
                 required: false,
-                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile add-project` after creation.',
+                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile project add` after creation.',
             },
         ],
         output: [
@@ -44,7 +44,7 @@ export const newLeaf = defineLeaf({
             path: profileRoot(profileId),
             projects: manifest.projects,
             created_at: manifest.created_at,
-            follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile add-project ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
+            follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile project add ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
         };
     },
 });

package/dist/commands/profile/project.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const projectBranch: BranchDef;

package/dist/commands/profile/project.js

@@ -0,0 +1,97 @@
+// `crtr profile project` — the project-purview sub-noun of `profile`. A
+// profile's `projects` list is what it can SEE (memory + config resolution).
+// These two verbs widen or narrow that list after creation; `crtr profile
+// show` reads it back.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { addProfileProject, removeProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
+const addLeaf = defineLeaf({
+    name: 'add',
+    description: "add a project directory to a profile's purview",
+    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile.",
+    help: {
+        name: 'profile project add',
+        summary: "append a project directory to a profile's manifest, deduped by real path",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Appends to the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = addProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});
+const removeLeaf = defineLeaf({
+    name: 'remove',
+    description: "remove a project directory from a profile's purview",
+    whenToUse: "a profile no longer needs purview over one of its listed project directories — narrow it back. Works even if the directory itself was since deleted.",
+    help: {
+        name: 'profile project remove',
+        summary: "remove a project directory from a profile's manifest",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Removes an entry from the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = removeProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});
+export const projectBranch = defineBranch({
+    name: 'project',
+    description: "widen or narrow a profile's project purview",
+    whenToUse: "changing which project directories a profile can see (its memory + config resolution) after creation — add or remove one.",
+    help: {
+        name: 'profile project',
+        summary: "manage a profile's project purview — the directories it resolves memory and config from",
+        model: "A profile's `projects` list is the set of directories it inherits memory and config from. `add` widens that purview by one directory (deduped by real path); `remove` narrows it. Read the current list with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
+    },
+    children: [addLeaf, removeLeaf],
+});

package/dist/commands/profile/show.js

@@ -44,7 +44,7 @@ export const showLeaf = defineLeaf({
             path: profileRoot(profileId),
             config_path: configPath,
             config_exists: existsSync(configPath),
-            follow_up: `Add a project with \`crtr profile add-project ${profileId} --dir <path>\`, or rename with \`crtr profile rename ${profileId} --name <name>\`.`,
+            follow_up: `Add a project with \`crtr profile project add ${profileId} --dir <path>\`, or rename with \`crtr profile rename ${profileId} --name <name>\`.`,
         };
     },
 });

package/dist/commands/profile.js

@@ -1,33 +1,32 @@
 // `crtr profile` subtree — the profile store (spec §2.1/§2.5): agent
 // identities defined at the user root, each owning a manifest naming project
-// directories plus its own memory store. Flat leaves; no sub-branches — 7
-// verbs fits the 5-7 hard cap.
+// directories plus its own memory store.
 //
-// Every verb but `new`/`list` takes <profile> as an exact id OR a unique
-// manifest name (never two positionals: `add-project`/`remove-project` pair
-// <profile> with `--dir`, `rename` pairs it with `--name`, matching the
-// one-positional-per-leaf argv contract used across the whole tree).
+// Five flat manifest verbs (new/list/show/rename/delete) plus two sub-nouns:
+// `project` (the profile's project purview) and `default` (the per-cwd default
+// pin). Seven children — at the breadth cap. Every manifest verb but
+// `new`/`list` takes <profile> as an exact id OR a unique manifest name.
 import { defineBranch } from '../core/command.js';
 import { newLeaf } from './profile/new.js';
 import { listLeaf } from './profile/list.js';
 import { showLeaf } from './profile/show.js';
-import { addProjectLeaf } from './profile/add-project.js';
-import { removeProjectLeaf } from './profile/remove-project.js';
 import { renameLeaf } from './profile/rename.js';
 import { deleteLeaf } from './profile/delete.js';
+import { projectBranch } from './profile/project.js';
+import { defaultBranch } from './profile/default.js';
 export function registerProfile() {
     return defineBranch({
         name: 'profile',
         rootEntry: {
             concept: 'an agent identity defined at the user root — a manifest naming project directories plus its own memory store',
             desc: 'create, inspect, and manage profiles',
-            useWhen: 'creating a new agent identity, inspecting or listing existing ones, or changing a profile\u2019s project purview or display name. Selecting a profile for a running node (`--profile`, startup selection) lives elsewhere; this family only manages the manifest.',
+            useWhen: 'creating a new agent identity, inspecting or listing existing ones, changing a profile\u2019s project purview, or pinning which profile a directory defaults to at startup. Selecting a profile for a one-off run (`--profile`) lives elsewhere.',
         },
         help: {
             name: 'profile',
             summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
-            model: '`new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one manifest in full. `add-project` / `remove-project` mutate the ordered project list after creation, including mid-session on an already-running profile. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. Every verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
+            model: '`new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
         },
-        children: [newLeaf, listLeaf, showLeaf, addProjectLeaf, removeProjectLeaf, renameLeaf, deleteLeaf],
+        children: [newLeaf, listLeaf, showLeaf, renameLeaf, deleteLeaf, projectBranch, defaultBranch],
     });
 }