@crouton-kit/crouter 0.3.37 → 0.3.39

package/dist/core/runtime/launch.js

@@ -7,15 +7,13 @@
 // for a refresh-yield.
 // The spec is rewritten on every polymorph (base→orchestrator) so a node
 // always comes back as its *current* self.
-import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readConfig, configPath as userConfigPath } from '../config.js';
-import { resolve as resolvePersona } from '../personas/index.js';
+import { readMergedLaunchConfig, resolveKindConfig } from '../config.js';
 import { nodeEnv } from './nodes.js';
 import { editorLabel } from '../canvas/index.js';
 import { nodeDir } from '../canvas/paths.js';
-import { defaultScopeConfig } from '../../types.js';
 // ---------------------------------------------------------------------------
 // The two canvas pi-extensions every node loads. They self-gate on the live
 // {kind,mode} env, so the worker→orchestrator polymorph flips hook behavior
@@ -71,37 +69,13 @@ export const CANVAS_EXTENSIONS = [
 // xhigh — confirmed via `pi --help`), so the resolved spec is exactly the
 // string buildPiArgv passes to `--model`; no extra launch plumbing.
 // ---------------------------------------------------------------------------
-/** Cached user config for model resolution. The launch path is hot and reads
- *  config synchronously, so cache the merged config and invalidate on mtime/size
- *  changes rather than rereading on every normalizeModel/buildLaunchSpec call. */
-let cachedUserConfig = null;
-function readUserConfigCached() {
-    const path = userConfigPath('user');
-    if (path === null)
-        return defaultScopeConfig();
-    try {
-        const stat = statSync(path);
-        if (cachedUserConfig !== null &&
-            cachedUserConfig.path === path &&
-            cachedUserConfig.mtimeMs === stat.mtimeMs &&
-            cachedUserConfig.size === stat.size) {
-            return cachedUserConfig.config;
-        }
-        const config = readConfig('user');
-        cachedUserConfig = { path, mtimeMs: stat.mtimeMs, size: stat.size, config };
-        return config;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            cachedUserConfig = null;
-            return defaultScopeConfig();
-        }
-        throw error;
-    }
-}
-const DEFAULT_MODEL_LADDERS = defaultScopeConfig().modelLadders;
+/** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
+ *  project-stack > profile > user > builtin precedence `resolveKindConfig`
+ *  already uses for `kinds` — so a project/profile override of `modelLadders`
+ *  is honored identically to a kind override, instead of this file reading
+ *  only user config. */
 function modelLadders() {
-    return readUserConfigCached().modelLadders ?? DEFAULT_MODEL_LADDERS;
+    return readMergedLaunchConfig().modelLadders;
 }
 function ladderFor(provider, ladders = modelLadders()) {
     return ladders[provider];
@@ -112,7 +86,7 @@ function ladderFor(provider, ladders = modelLadders()) {
  *  defaultProvider in config.json wins over this env. */
 export const OPENAI_PROVIDER_ENV = 'CRTR_MODEL_PROVIDER';
 function defaultProvider() {
-    const cfgProvider = readUserConfigCached().modelLadders.defaultProvider;
+    const cfgProvider = readMergedLaunchConfig().modelLadders.defaultProvider;
     if (cfgProvider === 'anthropic' || cfgProvider === 'openai')
         return cfgProvider;
     return (process.env[OPENAI_PROVIDER_ENV] ?? '').toLowerCase() === 'openai' ? 'openai' : 'anthropic';
@@ -198,31 +172,44 @@ export function normalizeModel(model) {
 // ---------------------------------------------------------------------------
 // Build the launch spec from {kind, mode}
 // ---------------------------------------------------------------------------
-/** Compose a node's full pi launch recipe from its persona. The system prompt
- *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
- *  (terminal/resident — the finish contract) and spine position (hasManager —
- *  whether the push-up family is taught at all). Callers pass the authoritative
- *  lifecycle + hasManager (`parent !== null`) so a polymorph/flip rebuilds the
- *  prompt faithfully. The two canvas extensions are always first; persona-
- *  declared extensions follow. */
+/** The minimal static system prompt every node launches with — a thin launcher
+ *  frame keeping the `\n\nGuidelines:` anchor the `before_agent_start` substrate
+ *  hook (canvas-doc-substrate.ts) splices its `<memory kind="preference">` block
+ *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
+ *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
+ *  must never duplicate that prose. Exported so `sys prompt-review` can render
+ *  through the exact same static+spliced pipeline boot uses, so the two can
+ *  never drift. */
+export const LAUNCH_SYSTEM_PROMPT = 'You are a node in the crtr canvas — an agentic runtime.\n\nGuidelines:\n' +
+    '- Use the crtr canvas and memory substrate according to injected context.';
+/** Compose a node's full pi launch recipe from the kind registry. The system
+ *  prompt is now a minimal static scaffold (`LAUNCH_SYSTEM_PROMPT`) — runtime/
+ *  spine/lifecycle/kind prose is spliced per-turn from gated builtin memory docs,
+ *  not baked in here. Launch KNOBS (model/tools/extensions) still come from the
+ *  kind registry (`resolveKindConfig`), keyed on the FULL kind string (top-level
+ *  or sub-kind). Model precedence, strongest to weakest:
+ *   1. Caller-supplied `opts.model` (durable on `meta.model_override`, re-passed
+ *      on every polymorph).
+ *   2. The kind's registered model — mode-aware: orchestrator mode prefers
+ *      `orchestratorModel`, falling back to `model`; base mode always uses
+ *      `model`.
+ *   3. Unset → pi default.
+ *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
+ *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
+ *  as-given — it is no longer persona-frontmatter-derived. The two canvas
+ *  extensions are always first; kind-declared extensions follow. */
 export function buildLaunchSpec(kind, mode, opts) {
-    const p = resolvePersona(kind, mode, { lifecycle: opts.lifecycle, hasManager: opts.hasManager });
-    const cfg = readUserConfigCached();
-    // Precedence, from strongest to weakest:
-    // 1. Caller-supplied override (durable on `meta.model_override`, re-passed on
-    //    every polymorph).
-    // 2. Configured persona strength for this kind.
-    // 3. The persona file's own frontmatter model.
-    // 4. Unset → pi default.
-    const chosenModel = opts.model ?? cfg.personaStrengths[kind] ?? p.model;
+    const kindConfig = resolveKindConfig(kind);
+    const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
+    const chosenModel = opts.model ?? kindModel;
     const launch = {
         model: chosenModel !== undefined ? normalizeModel(chosenModel) : undefined,
-        tools: p.tools,
-        extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
-        systemPrompt: p.systemPrompt,
+        tools: kindConfig?.tools ?? [],
+        extensions: [...CANVAS_EXTENSIONS, ...(kindConfig?.extensions ?? [])],
+        systemPrompt: LAUNCH_SYSTEM_PROMPT,
         env: { ...(opts.extraEnv ?? {}) },
     };
-    return { launch, lifecycle: p.lifecycle };
+    return { launch, lifecycle: opts.lifecycle };
 }
 // ---------------------------------------------------------------------------
 // Build the pi argv to launch / revive a node

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

@@ -47,6 +47,13 @@ export interface SpawnNodeOpts {
      *  persona default. Persisted to `meta.model_override` so polymorphs preserve
      *  it. Omit to use the persona default. */
     modelOverride?: string | null;
+    /** The profile-directory id (`<slug>-<id>`) this node runs under; null for a
+     *  root/no-profile node. Written to `meta.profile_id` and the row, and mirrored
+     *  into the pi process env as `CRTR_PROFILE_ID` by `nodeEnv` — the runtime
+     *  → resolver seam every downstream memory/gate consumer reads. Callers
+     *  resolve/validate the operand (via `loadProfileManifest`) before it reaches
+     *  here; this layer just persists the already-resolved id. */
+    profile_id?: string | null;
     /** Override the generated id (e.g. when a caller pre-allocates one). */
     nodeId?: string;
 }

package/dist/core/runtime/nodes.js

@@ -64,6 +64,11 @@ export function nodeEnv(meta) {
         // resolves into the REPO, not here — agents must address artifacts via this.
         CRTR_CONTEXT_DIR: contextDir(meta.node_id),
         CRTR_CYCLES: (meta.cycles ?? 0).toString(),
+        // The runtime→resolver seam: memory-resolver.ts/scope.ts/config.ts read
+        // this process-wide env var (Phase 5) to pull in the node's profile memory
+        // store and multi-project pointer set. '' (never omitted) for a root/
+        // no-profile node, matching every other CRTR_* scalar here.
+        CRTR_PROFILE_ID: meta.profile_id ?? '',
     };
     if (meta.parent)
         env['CRTR_PARENT_NODE_ID'] = meta.parent;
@@ -105,6 +110,7 @@ export function spawnNode(opts) {
         // Broker is the only host: every node runs on the headless broker; a tmux
         // pane is only an attach viewer.
         host_kind: 'broker',
+        profile_id: opts.profile_id ?? null,
         kind: opts.kind,
         mode,
         lifecycle,

package/dist/core/runtime/persona.js

@@ -20,7 +20,6 @@
 // worker never gets spurious guidance). `personaDrift` compares live meta to it;
 // the caller delivers the guidance, then commits the ack.
 import { getNode, updateNode } from '../canvas/index.js';
-import { loadKernel, loadPersona, loadLifecycleFragment } from '../personas/index.js';
 import { resolveMemoryDoc } from '../memory-resolver.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { orchestratorContextNote } from './bearings.js';
@@ -28,40 +27,30 @@ import { orchestratorContextNote } from './bearings.js';
 // base→orchestrator guidance (the roadmap-shaping dump) — MOVED here from
 // promote.ts so the injector is the one place that builds it.
 // ---------------------------------------------------------------------------
-/** Coerce a frontmatter scalar to its string form. Strings pass through;
- *  number/boolean coerce via String(); null/undefined and non-scalars are
- *  dropped (→ null). This lets numeric/boolean `roadmapKnowledge` knowledge-doc
- *  pointers resolve the same way string pointers do. */
-function scalarToString(v) {
-    if (typeof v === 'string')
-        return v;
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    return null;
-}
-/** Load a knowledge doc's body text by name, or null if it can't be resolved.
- *  Used to inline a kind's roadmap-shaping knowledge doc into the orchestration
- *  guidance. */
-function loadRoadmapKnowledgeBody(name) {
+/** Load a builtin/user/project memory doc's body by its normalized name, or ''
+ *  if it can't be resolved. The single source for the lifecycle/spine/
+ *  orchestration-kernel fragments this injector re-delivers on a transition —
+ *  the SAME docs Phase 2 authored under `src/builtin-memory/`, so static
+ *  (system-prompt splice) and transition prose can never drift. */
+function loadMemoryBody(name) {
     try {
         return resolveMemoryDoc(name).body.trim();
     }
     catch {
-        return null;
+        return '';
     }
 }
 /** The base→orchestrator guidance dump, specialized to the node's kind: the
- *  shared kernel + that kind's roadmap-shaping memory doc + the roadmap scaffold
- *  the node must author + the orchestrator context-dir framing + a short pointer at
- *  the substrate memory flow (promotion re-informs of nothing about the stores,
- *  it only adds the across-cycles relevance). The node is now a delegator whose
- *  scarce resource is its own context window. (Lifecycle is left to its own
- *  section — promotion no longer forces resident, so this never asserts residency.) */
+ *  shared orchestration-kernel doc + the roadmap scaffold the node must author +
+ *  the orchestrator context-dir framing + a short pointer at the substrate
+ *  memory flow (promotion re-informs of nothing about the stores, it only adds
+ *  the across-cycles relevance). The node is now a delegator whose scarce
+ *  resource is its own context window. Roadmap-shaping guidance is just another orchestrator-gated memory
+ *  doc the node already gets via the boot-render splice (kinds/<kind>/orchestrator
+ *  gated `{kind, mode: orchestrator}`). (Lifecycle is left to its own section —
+ *  promotion no longer forces resident, so this never asserts residency.) */
 function orchestrationGuidance(nodeId, kind) {
-    const kernel = loadKernel();
-    const orch = loadPersona(kind, 'orchestrator');
-    const roadmapKnowledge = scalarToString(orch?.frontmatter?.['roadmapKnowledge']) ?? undefined;
-    const roadmapKnowledgeBody = roadmapKnowledge ? loadRoadmapKnowledgeBody(roadmapKnowledge) : null;
+    const kernel = loadMemoryBody('orchestration-kernel');
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
     const rmPath = roadmapPath(nodeId);
     const parts = [
@@ -70,9 +59,6 @@ function orchestrationGuidance(nodeId, kind) {
         '',
         kernel,
     ];
-    if (roadmapKnowledgeBody) {
-        parts.push('', `--- How to shape a ${kind} roadmap (knowledge: ${roadmapKnowledge}) ---`, '', roadmapKnowledgeBody);
-    }
     parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 
     // The orchestrator framing for the context dir — the missing guidance a
     // promoted node never got at spawn (it spawned as a base worker). Same note
@@ -96,11 +82,11 @@ function baseModeGuidance() {
 // only re-delivers that fragment as the node's new-state steer.
 /** terminal → resident: interactable, never forced to submit. */
 function residentLifecycleGuidance() {
-    return loadLifecycleFragment('resident');
+    return loadMemoryBody('lifecycle/resident');
 }
 /** resident → terminal: owes a final, reaps when done. */
 function terminalLifecycleGuidance() {
-    return loadLifecycleFragment('terminal');
+    return loadMemoryBody('lifecycle/terminal');
 }
 /** Build the injected transition prompt for a `from → to` persona change.
  *  Concatenates the relevant section per changed axis (both when both changed).

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

@@ -6,6 +6,11 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
+    /** Explicit `--profile <id-or-name>` on the front-door invocation, validated
+     *  through `loadProfileManifest`. Omit to run the MRU/create-or-root startup
+     *  selector for `cwd` (see `selectProfileForCwd`) — a root has no spawner to
+     *  inherit from, so this is the front door's only source of profile identity. */
+    profile?: string | null;
 }
 /** Create the front-door root: launch its broker engine, then exec `crtr surface attach`
  *  inline so THIS terminal becomes the broker's controller-viewer. Does not
@@ -41,6 +46,14 @@ export interface SpawnChildOpts {
      *  persona's declared default. Persisted to `meta.model_override` so it
      *  survives polymorphs. Omit to use the persona default. */
     model?: string;
+    /** Select the profile this node runs under — an exact profile id or a unique
+     *  manifest name, validated through `loadProfileManifest`. Omit to INHERIT the
+     *  spawner's current `profile_id` (managed child or --root alike — --root only
+     *  means top-level, it does not reset to no profile). Passed through unchanged
+     *  into a deferred trigger recipe so a triggered birth re-resolves the SAME
+     *  choice at fire time (an explicit value re-validates; inheritance re-reads
+     *  the spawner's THEN-current profile). */
+    profile?: string | null;
 }
 /** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
  *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).

package/dist/core/runtime/spawn.js

@@ -14,6 +14,8 @@ import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnNode, currentNodeContext, rootOfSpine } from './nodes.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { selectProfileForCwd } from '../profiles/select.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
@@ -61,6 +63,10 @@ export async function bootRoot(opts) {
     }
     catch { /* daemon is best-effort */ }
     const kind = opts.kind ?? 'general';
+    // The front door's only source of profile identity — a root has no spawner
+    // to inherit from. Runs BEFORE spawnNode: explicit --profile > MRU profile
+    // covering cwd > a synchronous create-or-root prompt (or root, headless).
+    const profileId = await selectProfileForCwd(opts.cwd, opts.profile);
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
@@ -75,6 +81,7 @@ export async function bootRoot(opts) {
         cwd: opts.cwd,
         name: opts.name ?? kind,
         parent: null,
+        profile_id: profileId,
         launch,
     });
     // Persist the spawning prompt as the goal so a fresh revive can re-read its
@@ -216,6 +223,22 @@ export function resolveForkSource(value) {
     // .jsonl (the broker fork won't resolve a uuid).
     return resolveSessionUuid(v);
 }
+/** Resolve the profile a spawned child runs under: an explicit `--profile`
+ *  operand (id or name) validated through `loadProfileManifest`, else INHERIT
+ *  the spawner's current `profile_id` (null when the spawner has none). `--root`
+ *  never resets this to null on its own; only an explicit override does. When
+ *  there is NO spawner at all — `crtr node new --root` run directly from a
+ *  shell, not from inside a node — there is no profile to inherit, so this runs
+ *  the same startup selector the front door uses (MRU covering `cwd`, else the
+ *  synchronous create-or-root prompt / headless root default). */
+async function resolveProfileId(explicit, spawner, cwd) {
+    if (explicit !== undefined && explicit !== null && explicit !== '') {
+        return loadProfileManifest(explicit).profileId;
+    }
+    if (spawner !== null)
+        return getNode(spawner)?.profile_id ?? null;
+    return selectProfileForCwd(cwd);
+}
 /** Resolve who a spawn is attributed to. A managed child needs a spine parent
  *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
  *  does not: it is top-level by definition and the spawner identity is
@@ -256,6 +279,7 @@ export async function spawnChild(opts) {
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn
     // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
+    const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
     const meta = spawnNode({
         kind: opts.kind,
         mode,
@@ -267,6 +291,7 @@ export async function spawnChild(opts) {
         // A child's parent IS its manager.
         parent: root ? null : spawner,
         spawnedBy: root ? (spawner ?? undefined) : undefined,
+        profile_id: profileId,
         // Persist the RAW fork reference (not the resolved path) as provenance, so
         // the boot intro can detect this is a fork and re-assert the node's own
         // identity over the source's copied-in conversation.

package/dist/core/scope.d.ts

@@ -5,14 +5,21 @@ export declare function builtinPiPackagesDir(): string;
 export declare function builtinPiPackageDir(name: string): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
-/** Every project scope root visible from `startDir`, nearest first. Each
- *  ancestor directory with a `.crouter/` contributes memory/preferences to the
- *  current workspace; the nearest root still wins for writes and duplicate doc
- *  names. The user-global `~/.crouter/` is excluded because it is the separate
- *  user scope, not a project ancestor. */
-export declare function findProjectScopeRoots(startDir?: string): string[];
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Results are cached per (resolved startDir, profileId) — `resetScopeCache()`
+ *  invalidates on any profile mutation that can change project dirs or names. */
+export declare function findProjectScopeRoots(startDir?: string, profileId?: string | null): string[];
 export declare function projectScopeRoot(startDir?: string): string | null;
-export declare function projectScopeRoots(startDir?: string): string[];
+export declare function projectScopeRoots(startDir?: string, profileId?: string | null): string[];
 export declare function scopeRoot(scope: Scope): string | null;
 export declare function requireScopeRoot(scope: Scope): string;
 export declare function ensureProjectScopeRoot(startDir?: string): string;

package/dist/core/scope.js

@@ -4,7 +4,19 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
 import { usage } from './errors.js';
-let cachedProjectRoot;
+import { loadProfileManifest } from './profiles/manifest.js';
+// Cache of resolved project-scope-root STACKS, keyed by (resolved cwd, profile
+// id). A profile widens the pointer set beyond the bare cwd (see
+// findProjectScopeRoots below), so the cache key must carry both — the same
+// cwd resolves to a different stack under a different (or no) profile.
+// `resetScopeCache()` (called by every profile mutation in
+// src/core/profiles/manifest.ts) clears the whole cache; there is no
+// per-entry invalidation because a profile edit can change which pointer set
+// any cached cwd belongs to.
+const scopeRootsCache = new Map();
+function scopeRootsCacheKey(resolvedStartDir, profileId) {
+    return `${resolvedStartDir}\u0000${profileId ?? ''}`;
+}
 export function builtinViewsRoot() {
     // Resolved relative to this file: dist/core/scope.js → dist/builtin-views/
     // (src/ at dev time).
@@ -47,20 +59,13 @@ function isProjectScopeDir(candidate, userRoot) {
     }
 }
 export function findProjectScopeRoot(startDir = process.cwd()) {
-    if (cachedProjectRoot !== undefined)
-        return cachedProjectRoot;
-    const roots = findProjectScopeRoots(startDir);
-    cachedProjectRoot = roots[0] ?? null;
-    return cachedProjectRoot;
-}
-/** Every project scope root visible from `startDir`, nearest first. Each
- *  ancestor directory with a `.crouter/` contributes memory/preferences to the
- *  current workspace; the nearest root still wins for writes and duplicate doc
- *  names. The user-global `~/.crouter/` is excluded because it is the separate
- *  user scope, not a project ancestor. */
-export function findProjectScopeRoots(startDir = process.cwd()) {
+    return findProjectScopeRoots(startDir)[0] ?? null;
+}
+/** Walk `startDir` upward to the filesystem root, collecting every ancestor
+ *  `.crouter/` dir (nearest first). The user-global `~/.crouter/` is excluded
+ *  because it is the separate user scope, not a project ancestor. */
+function collectAncestorScopeRoots(startDir, userRoot) {
     const roots = [];
-    const userRoot = userScopeRoot();
     let dir = resolve(startDir);
     while (true) {
         const candidate = join(dir, CRTR_DIR_NAME);
@@ -72,11 +77,55 @@ export function findProjectScopeRoots(startDir = process.cwd()) {
         dir = parent;
     }
 }
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Results are cached per (resolved startDir, profileId) — `resetScopeCache()`
+ *  invalidates on any profile mutation that can change project dirs or names. */
+export function findProjectScopeRoots(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    const resolvedStart = resolve(startDir);
+    const key = scopeRootsCacheKey(resolvedStart, profileId);
+    const cached = scopeRootsCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const userRoot = userScopeRoot();
+    const pointers = [resolvedStart];
+    if (profileId !== null && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            pointers.push(...manifest.projects);
+        }
+        catch {
+            // Missing/deleted/invalid profile: this is a hot path every memory and
+            // launch-config resolve runs through, so fall back to the bare
+            // `[startDir]` pointer rather than throwing.
+        }
+    }
+    const seen = new Set();
+    const roots = [];
+    for (const pointer of pointers) {
+        for (const root of collectAncestorScopeRoots(pointer, userRoot)) {
+            if (seen.has(root))
+                continue;
+            seen.add(root);
+            roots.push(root);
+        }
+    }
+    scopeRootsCache.set(key, roots);
+    return roots;
+}
 export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
-export function projectScopeRoots(startDir) {
-    return findProjectScopeRoots(startDir);
+export function projectScopeRoots(startDir, profileId) {
+    return findProjectScopeRoots(startDir, profileId);
 }
 export function scopeRoot(scope) {
     // The builtin scope has no scope-root dir: its only content is memory
@@ -96,9 +145,16 @@ export function ensureProjectScopeRoot(startDir = process.cwd()) {
     const found = findProjectScopeRoot(startDir);
     if (found)
         return found;
-    // Initialize new project scope at startDir
-    const root = join(resolve(startDir), CRTR_DIR_NAME);
-    cachedProjectRoot = root;
+    // Initialize new project scope at startDir. `found` was falsy, which means
+    // the (resolvedStart, profileId) cache key above resolved to an EMPTY stack
+    // (no pointer had an existing `.crouter/` yet) — seed that same cache entry
+    // with the about-to-exist root so a caller that immediately writes under it
+    // (without an intervening disk rescan) sees it without a stale empty-array
+    // cache hit.
+    const resolvedStart = resolve(startDir);
+    const root = join(resolvedStart, CRTR_DIR_NAME);
+    const profileId = process.env['CRTR_PROFILE_ID'] || null;
+    scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), [root]);
     return root;
 }
 export function pluginsDir(scope) {
@@ -154,5 +210,5 @@ export function listScopes(scopeArg) {
     return [v];
 }
 export function resetScopeCache() {
-    cachedProjectRoot = undefined;
+    scopeRootsCache.clear();
 }

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

@@ -1,9 +1,9 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
-export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
 export type { Surface } from './ceiling.js';
-export { renderPreferencesSection, renderKnowledgeBlock, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, renderPreferencesForSubject, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -11,9 +11,11 @@ RUNGS, rungRank, rungAtLeast,
 // fallback floor
 FALLBACK_RUNG, 
 // parse + render-shared helpers
-parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
-export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
+// display-name normalization
+normalizeNameSegment, normalizeDocName, } from './schema.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject, profileNameFor } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
-export { renderPreferencesSection, renderKnowledgeBlock, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, renderPreferencesForSubject, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/on-read.js

@@ -56,7 +56,7 @@ import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
-import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 // Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
 // file may live under a build/dependency tree; `.crouter` is NOT junk here — it
@@ -113,10 +113,11 @@ function isJunkAncestor(dir) {
  *  (gate eval keys off the NODE subject, render off name/body/rung). */
 function loadPositionalDoc(file, memDir, scope) {
     try {
-        const name = relative(memDir, file)
+        const raw = relative(memDir, file)
             .replace(/\.md$/i, '')
             .split(sep)
             .join('/');
+        const name = normalizeDocName(raw);
         if (name === '')
             return null;
         const { data, body } = parseFrontmatterGeneric(readText(file));

package/dist/core/substrate/render.d.ts

@@ -1,16 +1,21 @@
-/** The system-prompt memory block: the always-present memory-usage guidance,
- *  then (when any are eligible) the `kind: preference` docs in one tree at their
- *  effective rung (the preference default rung is `preview` → the routing line).
- *  ALWAYS returns a non-empty `<memory kind="preference">` block — the guidance
- *  frame is unconditional, so the system-prompt splice is never empty even when
- *  no preference is eligible. */
+import { type NodeConfigSubject, type SubstrateDoc } from './index.js';
 export declare function renderPreferencesSection(nodeId: string): string;
+export declare function renderPreferencesForSubject(subject: NodeConfigSubject): {
+    block: string;
+    contentDocs: SubstrateDoc[];
+    tree: string;
+};
 /** The `<memory kind="knowledge">` block embedded in the session_start bearings
  *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
  *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
- *  doc at its effective rung (most surface only as `[+N more]` counts unless
- *  author-promoted) PLUS the node-local memory docs (any kind), the latter
- *  floored to `name` so a `none`-rung node-local doc still shows its name rather
- *  than collapsing into a count. Procedural guidance and factual references both
- *  live here as `knowledge`. Returns '' when nothing is eligible. */
+ *  doc PLUS the node-local memory docs (any kind) — resolver docs win
+ *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
+ *  like the preference block: content prose first (general→specific,
+ *  node-local last), then the preview/name catalog tree. Node-local docs are
+ *  floored HERE — a rung-none node-local doc's effective rung is bumped to
+ *  `name` before grouping, so it still surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance
+ *  and factual references both live here as `knowledge`. Returns '' when
+ *  nothing is eligible. */
 export declare function renderKnowledgeBlock(nodeId: string): string;