@crouton-kit/crouter 0.3.17 → 0.3.18

package/dist/core/__tests__/persona-subkind.test.js

@@ -1,15 +1,18 @@
 // Run: node --import tsx/esm --test src/core/__tests__/persona-subkind.test.ts
 //
-// Scoped persona sub-kinds: a kind owns specialist reviewer personas at
-// `<kind>/reviewers/<name>/base.md`, enumerated by `subKindsFor(kind)` and
+// Scoped persona sub-personas: a kind has specialist reviewer personas at
+// `<kind>/reviewers/<name>/PERSONA.md`, enumerated by `subPersonasFor(kind)` and
 // rendered into that kind's composed prompt (and nowhere else) by `resolve`.
-// Visibility = membership: only `plan` sees the `plan/reviewers/*` menu; the
-// sub-kinds never pollute the global `availableKinds()` list; and a sub-kind
-// itself boots as a real composed persona with the terminal finish contract.
+// Visibility = membership (the sub-persona's `availableTo`, default = its
+// top-level ancestor kind): only `plan` sees the `plan/reviewers/*` menu; the
+// `reviewers/` grouping dir is transparent so the kind string keeps it; the
+// sub-personas never pollute the global `availableKinds()` list; and a
+// sub-persona itself boots as a real composed persona with the terminal finish
+// contract.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { resolve } from '../personas/resolve.js';
-import { subKindsFor, availableKinds } from '../personas/loader.js';
+import { subPersonasFor, availableKinds } from '../personas/loader.js';
 const PLAN_REVIEWER_KINDS = [
     'plan/reviewers/architecture-fit',
     'plan/reviewers/code-smells',
@@ -17,19 +20,19 @@ const PLAN_REVIEWER_KINDS = [
     'plan/reviewers/requirements-coverage',
     'plan/reviewers/security',
 ];
-const MENU_HEADER = 'Reviewer sub-kinds you may spawn';
-test('subKindsFor("plan") returns the five reviewers sorted, each with a non-empty summary', () => {
-    const subs = subKindsFor('plan');
-    assert.deepEqual(subs.map((s) => s.kind), PLAN_REVIEWER_KINDS, 'the five plan reviewer kind strings in sorted order');
+const MENU_HEADER = 'Sub-personas you may spawn';
+test('subPersonasFor("plan") returns the five reviewers sorted, each with a non-empty whenToUse', () => {
+    const subs = subPersonasFor('plan');
+    assert.deepEqual(subs.map((s) => s.kind), PLAN_REVIEWER_KINDS, 'the five plan reviewer kind strings in sorted order — the transparent reviewers/ dir keeps the full kind path');
     for (const s of subs) {
-        assert.ok(s.summary.length > 0, `${s.kind} carries a non-empty summary`);
+        assert.ok(s.whenToUse.length > 0, `${s.kind} carries a non-empty whenToUse`);
     }
 });
-test('sub-kinds do not recurse and absent rosters yield []', () => {
-    assert.deepEqual(subKindsFor('explore'), [], 'explore owns no reviewers/');
-    assert.deepEqual(subKindsFor('plan/reviewers/security'), [], 'a sub-kind owns no nested reviewers/ — no recursion');
+test('availability is membership: a kind with no available sub-personas yields []', () => {
+    assert.deepEqual(subPersonasFor('explore'), [], 'no sub-persona is availableTo explore');
+    assert.deepEqual(subPersonasFor('plan/reviewers/security'), [], 'the five reviewers default availableTo:[plan] — none are available to a reviewer kind');
 });
-test('availableKinds() contains no plan/reviewers/* — sub-kinds never pollute the global list', () => {
+test('availableKinds() contains no plan/reviewers/* — sub-personas never pollute the global list', () => {
     const kinds = availableKinds();
     for (const k of PLAN_REVIEWER_KINDS) {
         assert.ok(!kinds.includes(k), `${k} must not appear in availableKinds()`);

package/dist/core/canvas/paths.d.ts

@@ -1,4 +1,7 @@
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export declare function crtrHome(): string;
 export declare function canvasDbPath(): string;
 export declare function nodesRoot(): string;

package/dist/core/canvas/paths.js

@@ -1,6 +1,6 @@
-// The `~/.crtr/` layout. One global, cwd-agnostic home for the whole canvas.
+// The `~/.crouter/canvas/` layout. One global, cwd-agnostic home for the whole canvas.
 //
-//   ~/.crtr/
+//   ~/.crouter/canvas/
 //     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
 //     nodes/<node_id>/
 //       meta.json               source of truth for the node's row
@@ -15,10 +15,16 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { mkdirSync } from 'node:fs';
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+import { CRTR_DIR_NAME } from '../../types.js';
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export function crtrHome() {
     const override = process.env['CRTR_HOME'];
-    return override !== undefined && override !== '' ? override : join(homedir(), '.crtr');
+    return override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
 }
 export function canvasDbPath() {
     return join(crtrHome(), 'canvas.db');

package/dist/core/canvas/types.js

@@ -1,7 +1,7 @@
 // The canvas vocabulary — the node + edge model the whole runtime hangs on.
 //
-// One global canvas (`~/.crtr/canvas.db`) holds the topology (nodes + edges);
-// each node's flesh lives on disk under `~/.crtr/nodes/<id>/`. A node's
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the topology (nodes +
+// edges); each node's flesh lives on disk under `~/.crouter/canvas/nodes/<id>/`. A node's
 // `meta.json` is the source of truth for its own row; the db is a queryable
 // index over those metas, plus the authoritative store for the mutable
 // `subscribes_to` edges (which no single meta owns).

package/dist/core/help.d.ts

@@ -162,6 +162,12 @@ export interface LeafHelp {
     /** Every persistent change the command makes to the world. For read-only
      *  leaves use exactly: ["None. Read-only."] */
     effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
 }
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any

package/dist/core/help.js

@@ -238,5 +238,12 @@ export function renderLeafArgv(h) {
     for (const e of h.effects) {
         lines.push(`  ${e}`);
     }
+    // Optional bounded runtime-state block (e.g. the live <kinds> list), appended
+    // after the schema. Soft-fails to omission on null/throw, mirroring renderBranch.
+    const state = evalDynamic(h.dynamicState);
+    if (state !== null) {
+        lines.push('');
+        lines.push(state);
+    }
     return lines.join('\n');
 }

package/dist/core/personas/index.d.ts

@@ -2,11 +2,12 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
-export type { LoadedPersona } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export type { LoadedPersona, SubPersona } from './loader.js';
 export { resolve } from './resolve.js';
 export type { ResolvedPersona } from './resolve.js';

package/dist/core/personas/index.js

@@ -2,9 +2,10 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
 export { resolve } from './resolve.js';

package/dist/core/personas/loader.d.ts

@@ -5,9 +5,10 @@
  * Resolution order (highest → lowest precedence): project > user > builtin.
  *
  * Layout on disk:
- *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/PERSONA.md
  *   <root>/personas/<kind>/orchestrator.md
  *   <root>/personas/orchestration-kernel.md
+ *   <root>/personas/<kind>/<...>/PERSONA.md   (nested sub-personas)
  *
  * The builtin root is src/builtin-personas (or dist/builtin-personas in the
  * compiled build), resolved relative to this module — mirrors the pattern used
@@ -55,29 +56,46 @@ export declare function loadLifecycleFragment(lifecycle: 'terminal' | 'resident'
  */
 export declare function loadSpineFragment(hasManager: boolean): string;
 /**
- * Enumerate the kinds with at least one persona file (base.md or
+ * Enumerate the kinds with at least one persona file (PERSONA.md or
  * orchestrator.md) across all scope roots (project/user/builtin). Used to
- * validate a requested `--kind` and to list the valid choices.
+ * validate a requested `--kind` and to list the valid choices. Only the
+ * IMMEDIATE children of each root count — nested sub-personas never pollute
+ * the global kind list (see subPersonasFor).
  */
 export declare function availableKinds(): string[];
-export interface SubKind {
+/**
+ * The one-line "when to use this node type" gloss for `kind`, read from its
+ * `<kind>/PERSONA.md` `whenToUse` frontmatter (resolved project > user >
+ * builtin). Returns '' when the kind has no PERSONA.md or no `whenToUse`.
+ * Drives the dynamic kind list in `node new -h` / `node promote -h`.
+ */
+export declare function kindWhenToUse(kind: string): string;
+export interface SubPersona {
     /** Full kind string to spawn, e.g. 'plan/reviewers/security'. */
     kind: string;
     /** Leaf name, e.g. 'security'. */
     name: string;
-    /** One-line "what it reviews", from the sub-kind base.md `summary` frontmatter (or ''). */
-    summary: string;
+    /** One-line "when to use", from the sub-persona PERSONA.md `whenToUse` frontmatter (or ''). */
+    whenToUse: string;
 }
 /**
- * Enumerate the reviewer sub-kinds owned by `parentKind` — the specialist
- * personas at `<root>/<parentKind>/reviewers/<name>/base.md`, scanned across all
- * scope roots (project > user > builtin; highest precedence wins per name).
+ * Enumerate the sub-personas AVAILABLE TO `kind` — the nested specialist
+ * personas (e.g. `plan/reviewers/security`) a `kind` node may spawn, surfaced
+ * in its composed prompt (resolve.ts) and nowhere else.
+ *
+ * A sub-persona is any descendant dir (ANY depth) under a top-level kind dir
+ * that holds a PERSONA.md, EXCLUDING the top-level PERSONA.md itself. Its
+ * availability is its `availableTo` frontmatter: an explicit list of kind
+ * strings, or the wildcard `"*"`/`"all"` (visible to every kind); absent, it
+ * defaults to its own top-level ancestor kind. So the five `plan/reviewers/*`
+ * (no `availableTo`) are visible only to `plan`, while a sub-persona under
+ * `developer/` can declare `availableTo: [plan]` to surface in plan's menu —
+ * which is why ALL top-level kinds' descendants are scanned, not just `<kind>/`.
  *
- * Sub-kinds are intentionally NOT global kinds: `availableKinds()` scans only the
- * immediate children of each persona root, so `<parentKind>/reviewers/*` never
- * leaks into the global list. A sub-kind is reachable only by its full kind
- * string and is surfaced only in its parent kind's composed prompt (resolve.ts).
- * Kind-parametric: any kind owns a roster simply by adding
- * `<kind>/reviewers/<name>/base.md` — no code change.
+ * Sub-personas are intentionally NOT global kinds: `availableKinds()` scans only
+ * the immediate children of each root, so a nested sub-persona never leaks into
+ * the global list; it is reachable only by its full kind string. Precedence is
+ * project > user > builtin keyed on the FULL kind string — the highest root that
+ * defines a given kind string wins (and owns its `availableTo`).
  */
-export declare function subKindsFor(parentKind: string): SubKind[];
+export declare function subPersonasFor(kind: string): SubPersona[];

package/dist/core/personas/loader.js

@@ -5,9 +5,10 @@
  * Resolution order (highest → lowest precedence): project > user > builtin.
  *
  * Layout on disk:
- *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/PERSONA.md
  *   <root>/personas/<kind>/orchestrator.md
  *   <root>/personas/orchestration-kernel.md
+ *   <root>/personas/<kind>/<...>/PERSONA.md   (nested sub-personas)
  *
  * The builtin root is src/builtin-personas (or dist/builtin-personas in the
  * compiled build), resolved relative to this module — mirrors the pattern used
@@ -59,7 +60,7 @@ function personaSearchRoots() {
 // ---------------------------------------------------------------------------
 /**
  * Find the first existing file across the scope roots.
- * `relativePath` is relative to each root (e.g. 'general/base.md').
+ * `relativePath` is relative to each root (e.g. 'general/PERSONA.md').
  */
 function resolveFile(relativePath) {
     for (const root of personaSearchRoots()) {
@@ -92,6 +93,11 @@ function inlineIncludes(body) {
         return kernelBody.trim();
     });
 }
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** The role-body filename for every kind/sub-persona (replaces legacy base.md). */
+const PERSONA_FILE = 'PERSONA.md';
 /**
  * Load and parse a persona file for the given `kind` and `mode`.
  *
@@ -99,7 +105,8 @@ function inlineIncludes(body) {
  * On success, `@include` directives in the body are resolved and inlined.
  */
 export function loadPersona(kind, mode) {
-    const relativePath = `${kind}/${mode}.md`;
+    // base → PERSONA.md (the role body); orchestrator → its sibling orchestrator.md.
+    const relativePath = mode === 'orchestrator' ? `${kind}/orchestrator.md` : `${kind}/PERSONA.md`;
     const filePath = resolveFile(relativePath);
     if (!filePath)
         return null;
@@ -165,9 +172,11 @@ export function loadSpineFragment(hasManager) {
     return body.trim();
 }
 /**
- * Enumerate the kinds with at least one persona file (base.md or
+ * Enumerate the kinds with at least one persona file (PERSONA.md or
  * orchestrator.md) across all scope roots (project/user/builtin). Used to
- * validate a requested `--kind` and to list the valid choices.
+ * validate a requested `--kind` and to list the valid choices. Only the
+ * IMMEDIATE children of each root count — nested sub-personas never pollute
+ * the global kind list (see subPersonasFor).
  */
 export function availableKinds() {
     const kinds = new Set();
@@ -178,42 +187,106 @@ export function availableKinds() {
             if (!entry.isDirectory())
                 continue;
             const dir = join(root, entry.name);
-            if (existsSync(join(dir, 'base.md')) || existsSync(join(dir, 'orchestrator.md'))) {
+            if (existsSync(join(dir, PERSONA_FILE)) || existsSync(join(dir, 'orchestrator.md'))) {
                 kinds.add(entry.name);
             }
         }
     }
     return [...kinds].sort();
 }
-const REVIEWERS_SUBDIR = 'reviewers';
 /**
- * Enumerate the reviewer sub-kinds owned by `parentKind` — the specialist
- * personas at `<root>/<parentKind>/reviewers/<name>/base.md`, scanned across all
- * scope roots (project > user > builtin; highest precedence wins per name).
+ * The one-line "when to use this node type" gloss for `kind`, read from its
+ * `<kind>/PERSONA.md` `whenToUse` frontmatter (resolved project > user >
+ * builtin). Returns '' when the kind has no PERSONA.md or no `whenToUse`.
+ * Drives the dynamic kind list in `node new -h` / `node promote -h`.
+ */
+export function kindWhenToUse(kind) {
+    const filePath = resolveFile(`${kind}/${PERSONA_FILE}`);
+    if (!filePath)
+        return '';
+    const { data } = parseFrontmatterGeneric(readFileSync(filePath, 'utf8'));
+    return data && typeof data['whenToUse'] === 'string' ? data['whenToUse'] : '';
+}
+/** Recursively yield every dir under `dir` (inclusive) that holds a PERSONA.md,
+ *  with `relKind` = the dir's path relative to the scope root (slash-joined).
+ *  Dirs WITHOUT a PERSONA.md (e.g. a `reviewers/` grouping namespace) are
+ *  transparent — they yield nothing themselves but are still descended into,
+ *  so `plan/reviewers/security` keeps that exact kind string. */
+function* walkPersonaDirs(dir, relParts) {
+    const file = join(dir, PERSONA_FILE);
+    if (existsSync(file))
+        yield { relKind: relParts.join('/'), file };
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            yield* walkPersonaDirs(join(dir, entry.name), [...relParts, entry.name]);
+    }
+}
+/** Parse a sub-persona's `availableTo` frontmatter into its availability set.
+ *  Returns the wildcard sentinel `'*'` for `"*"`/`"all"` (scalar or in an
+ *  array), an explicit list of kind strings when present, else the default
+ *  `[topKind]` (the top-level ancestor kind). */
+function parseAvailableTo(data, topKind) {
+    const isWild = (s) => {
+        const t = s.trim().toLowerCase();
+        return t === '*' || t === 'all';
+    };
+    const v = data ? data['availableTo'] : undefined;
+    if (v === undefined)
+        return [topKind];
+    if (typeof v === 'string')
+        return isWild(v) ? '*' : [v];
+    if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string');
+        if (arr.some(isWild))
+            return '*';
+        return arr.length > 0 ? arr : [topKind];
+    }
+    return [topKind];
+}
+/**
+ * Enumerate the sub-personas AVAILABLE TO `kind` — the nested specialist
+ * personas (e.g. `plan/reviewers/security`) a `kind` node may spawn, surfaced
+ * in its composed prompt (resolve.ts) and nowhere else.
  *
- * Sub-kinds are intentionally NOT global kinds: `availableKinds()` scans only the
- * immediate children of each persona root, so `<parentKind>/reviewers/*` never
- * leaks into the global list. A sub-kind is reachable only by its full kind
- * string and is surfaced only in its parent kind's composed prompt (resolve.ts).
- * Kind-parametric: any kind owns a roster simply by adding
- * `<kind>/reviewers/<name>/base.md` — no code change.
+ * A sub-persona is any descendant dir (ANY depth) under a top-level kind dir
+ * that holds a PERSONA.md, EXCLUDING the top-level PERSONA.md itself. Its
+ * availability is its `availableTo` frontmatter: an explicit list of kind
+ * strings, or the wildcard `"*"`/`"all"` (visible to every kind); absent, it
+ * defaults to its own top-level ancestor kind. So the five `plan/reviewers/*`
+ * (no `availableTo`) are visible only to `plan`, while a sub-persona under
+ * `developer/` can declare `availableTo: [plan]` to surface in plan's menu —
+ * which is why ALL top-level kinds' descendants are scanned, not just `<kind>/`.
+ *
+ * Sub-personas are intentionally NOT global kinds: `availableKinds()` scans only
+ * the immediate children of each root, so a nested sub-persona never leaks into
+ * the global list; it is reachable only by its full kind string. Precedence is
+ * project > user > builtin keyed on the FULL kind string — the highest root that
+ * defines a given kind string wins (and owns its `availableTo`).
  */
-export function subKindsFor(parentKind) {
-    const byName = new Map();
+export function subPersonasFor(kind) {
+    const seen = new Set(); // full kind strings already resolved (higher root won)
+    const out = [];
     for (const root of personaSearchRoots()) {
-        const dir = join(root, parentKind, REVIEWERS_SUBDIR);
-        if (!existsSync(dir))
+        if (!existsSync(root))
             continue;
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || byName.has(entry.name))
-                continue; // higher root already won
-            const baseFile = join(dir, entry.name, 'base.md');
-            if (!existsSync(baseFile))
+        for (const top of readdirSync(root, { withFileTypes: true })) {
+            if (!top.isDirectory())
                 continue;
-            const { data } = parseFrontmatterGeneric(readFileSync(baseFile, 'utf8'));
-            const summary = data && typeof data['summary'] === 'string' ? data['summary'] : '';
-            byName.set(entry.name, { kind: `${parentKind}/${REVIEWERS_SUBDIR}/${entry.name}`, name: entry.name, summary });
+            const topKind = top.name;
+            for (const { relKind, file } of walkPersonaDirs(join(root, topKind), [topKind])) {
+                if (relKind === topKind)
+                    continue; // the top-level PERSONA.md is the kind itself, not a sub-persona
+                if (seen.has(relKind))
+                    continue; // a higher root already resolved this kind string
+                seen.add(relKind);
+                const { data } = parseFrontmatterGeneric(readFileSync(file, 'utf8'));
+                const availableTo = parseAvailableTo(data, topKind);
+                if (availableTo !== '*' && !availableTo.includes(kind))
+                    continue;
+                const whenToUse = data && typeof data['whenToUse'] === 'string' ? data['whenToUse'] : '';
+                out.push({ kind: relKind, name: relKind.split('/').pop(), whenToUse });
+            }
         }
     }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }

package/dist/core/personas/resolve.d.ts

@@ -4,17 +4,17 @@
  *
  * Composition rules:
  *   mode==='base'
- *     → load <kind>/base.md; if missing fall back to general defaults.
+ *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
  *
  *   mode==='orchestrator'
  *     → prefer <kind>/orchestrator.md (which must embed the kernel via
  *       @include orchestration-kernel.md — inlined by the loader).
  *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/base.md body  +  '\n\n'  +  kernel body
- *       If even the base is missing, fall back to general defaults + kernel.
+ *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
+ *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
  * are INPUTS (the caller decides them — root/child, terminal/resident), not
  * derived here; they select the lifecycle/spine protocol fragments spliced
  * ahead of the persona body.

package/dist/core/personas/resolve.js

@@ -4,22 +4,22 @@
  *
  * Composition rules:
  *   mode==='base'
- *     → load <kind>/base.md; if missing fall back to general defaults.
+ *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
  *
  *   mode==='orchestrator'
  *     → prefer <kind>/orchestrator.md (which must embed the kernel via
  *       @include orchestration-kernel.md — inlined by the loader).
  *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/base.md body  +  '\n\n'  +  kernel body
- *       If even the base is missing, fall back to general defaults + kernel.
+ *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
+ *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
  * are INPUTS (the caller decides them — root/child, terminal/resident), not
  * derived here; they select the lifecycle/spine protocol fragments spliced
  * ahead of the persona body.
  */
-import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, subKindsFor } from './loader.js';
+import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, subPersonasFor } from './loader.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -40,24 +40,26 @@ function fallbackBasePrompt(kind) {
  *  fragment (report-up vs. silent, keyed on whether the node has a manager),
  *  then the lifecycle fragment (finish-with-`push final` vs. dormant/wake). The
  *  kind×mode persona body follows after a rule. Empty fragments drop out. */
-/** Render the "sub-kinds you may spawn" menu for a kind that owns a roster.
- *  Returns '' when the kind owns none. Data-driven: one line per sub-kind, its
- *  spawn string + its `summary`. Adding a roster file makes it appear here. */
-function renderSubKindMenu(kind) {
-    const subs = subKindsFor(kind);
+/** Render the "sub-personas you may spawn" menu for a kind that has any
+ *  available to it. Returns '' when none are. Data-driven: one line per
+ *  sub-persona, its spawn string + its `whenToUse`. A sub-persona surfaces here
+ *  for a kind when its `availableTo` includes that kind (default: its own
+ *  top-level ancestor) or is the wildcard. */
+function renderSubPersonaMenu(kind) {
+    const subs = subPersonasFor(kind);
     if (subs.length === 0)
         return '';
-    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.summary}`);
+    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.whenToUse}`);
     return [
-        '## Reviewer sub-kinds you may spawn',
+        '## Sub-personas you may spawn',
         '',
-        `These specialist reviewers exist only in the ${kind} kind's world — no other kind sees them. Spawn one with \`crtr node new --kind <sub-kind> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with \`crtr node new --kind <sub> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
         '',
         ...lines,
     ].join('\n');
 }
 function composeProtocol(personaPrompt, kind, lifecycle, hasManager) {
-    const menu = renderSubKindMenu(kind);
+    const menu = renderSubPersonaMenu(kind);
     const body = menu ? `${personaPrompt}\n\n${menu}` : personaPrompt;
     const protocol = [
         loadRuntimeBase(),

package/dist/core/runtime/placement.d.ts

@@ -15,6 +15,16 @@ export declare function focusByPane(pane: string): FocusRow | null;
 export declare function focusedNodes(): Set<string>;
 /** Every focus row (every live viewport). */
 export declare function listFocuses(): FocusRow[];
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
 /** The cached LOCATION as stored on a node row: the authoritative `pane` handle
  *  plus its derived window/session cache. */
 export interface CachedLocation {

package/dist/core/runtime/placement.js

@@ -25,7 +25,7 @@
 // The robustness contract: a manual `move-pane`/`join-pane`/`break-pane` must
 // NEVER read as a node death. Liveness is pane-existence, not window-existence,
 // and reconcile makes crtr follow a move instead of fighting it.
-import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, view, } from '../canvas/index.js';
 import { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
 import { homeSessionOf, nodeSession, newNodeId } from './nodes.js';
 import { isBusy } from './busy.js';
@@ -71,6 +71,42 @@ export function focusedNodes() {
 export function listFocuses() {
     return listFocusRows();
 }
+// ---------------------------------------------------------------------------
+// Graph → focus routing (for surfacing human-in-the-loop prompts)
+// ---------------------------------------------------------------------------
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). */
+function rootOfSpine(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    for (;;) {
+        if (seen.has(cur))
+            return cur;
+        seen.add(cur);
+        const row = getRow(cur);
+        if (row === null || row.parent == null)
+            return cur;
+        cur = row.parent;
+    }
+}
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export function graphSurfaceTarget(nodeId) {
+    const root = rootOfSpine(nodeId);
+    for (const id of [root, ...view(root)]) {
+        const f = getFocusByNode(id);
+        if (f !== null && f.pane !== null)
+            return f;
+    }
+    return null;
+}
 /** PURE reconciliation decision (§2.4) — unit-testable without a live tmux.
  *  Given the cached row LOCATION and what tmux currently reports, decide the
  *  presence patch. Mirrors the pure-core/impure-shell split (cf. `livenessVerdict`

package/dist/core/spawn.d.ts

@@ -1,7 +1,21 @@
 export declare function isInTmux(): boolean;
 export declare function shellQuote(s: string): string;
-/** Count panes in the current tmux window (0 outside tmux / on error). */
+/** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
+ *  counts the window THAT pane lives in (the placement decision must reflect the
+ *  window the new pane will actually open into, not the caller's backstage one);
+ *  without it, the caller's current window. */
+export declare function countPanesInWindow(targetPane?: string): number;
+/** Back-compat alias: panes in the caller's current window. */
 export declare function countPanesInCurrentWindow(): number;
+/** Does this tmux pane id still exist? `display-message` EXITS 0 with EMPTY
+ *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
+ *  False outside tmux / on error. */
+export declare function paneAlive(pane: string): boolean;
+/** The active pane of the user's attached tmux client — where they are looking
+ *  right now. `list-clients` first attached client, then its current pane. Used
+ *  to surface a human prompt in the user's view when nothing in the asking
+ *  node's graph is focused. null outside tmux / no client / on error. */
+export declare function attachedClientPane(): string | null;
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux,
@@ -23,6 +37,11 @@ export interface DetachOptions {
      *  uses the attached client's currently-focused pane — which drifts if the
      *  user switches windows between kickoff and spawn. */
     targetPane?: string;
+    /** Pass tmux `-d` to new-window so CREATING the window never switches the
+     *  attached client to it (split-window already leaves the client's view put).
+     *  The prompt lands in the target session/window without jumping the user out
+     *  of what they are looking at. No effect on split-h/split-v. */
+    detached?: boolean;
 }
 export interface DetachResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';