@crouton-kit/crouter 0.3.37 → 0.3.38

package/dist/core/config.js

@@ -1,7 +1,8 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig, defaultKindsConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
-import { scopeRoot, requireScopeRoot } from './scope.js';
+import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
+import { profileRoot } from './profiles/manifest.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -150,14 +151,15 @@ function mergeCanvasNav(raw) {
         graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds, normalizeGraphBind),
     };
 }
-function mergeModelLadders(raw) {
-    const defaults = defaultModelLaddersConfig();
+function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
+    const defaults = base;
     if (raw === null || typeof raw !== 'object')
         return defaults;
     const r = raw;
     const out = {
         anthropic: { ...defaults.anthropic },
         openai: { ...defaults.openai },
+        ...(defaults.defaultProvider !== undefined ? { defaultProvider: defaults.defaultProvider } : {}),
     };
     if (r.defaultProvider === 'anthropic' || r.defaultProvider === 'openai') {
         out.defaultProvider = r.defaultProvider;
@@ -174,13 +176,42 @@ function mergeModelLadders(raw) {
     }
     return out;
 }
-function mergePersonaStrengths(raw) {
-    const out = {};
+/** Validate one raw `kinds.<name>` entry into a `KindConfig`, or drop it
+ *  (return null) rather than throwing — an invalid kind entry in config.json
+ *  must not break config parsing for every other kind. `whenToUse` is the
+ *  only required field. */
+function normalizeKindEntry(raw) {
     if (raw === null || typeof raw !== 'object')
-        return out;
-    for (const [persona, value] of Object.entries(raw)) {
-        if (value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light') {
-            out[persona] = value;
+        return null;
+    const r = raw;
+    if (typeof r.whenToUse !== 'string' || r.whenToUse.trim() === '')
+        return null;
+    const out = { whenToUse: r.whenToUse };
+    if (typeof r.model === 'string' && r.model.trim() !== '')
+        out.model = r.model;
+    if (typeof r.orchestratorModel === 'string' && r.orchestratorModel.trim() !== '')
+        out.orchestratorModel = r.orchestratorModel;
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    if (isStringArray(r.tools))
+        out.tools = r.tools;
+    if (isStringArray(r.extensions))
+        out.extensions = r.extensions;
+    if (isStringArray(r.availableTo))
+        out.availableTo = r.availableTo;
+    return out;
+}
+/** Merge a raw `kinds` block over `base` (defaulting to the builtin registry):
+ *  each valid entry adds or shadows a kind by name; invalid entries are
+ *  dropped, never thrown. Mirrors `mergeModelLadders`'s layer-over-defaults
+ *  shape so a user/project config.json can add or override a single kind
+ *  without restating the whole registry. */
+function mergeKinds(raw, base = defaultKindsConfig()) {
+    const out = { ...base };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [kind, value] of Object.entries(raw)) {
+            const normalized = normalizeKindEntry(value);
+            if (normalized !== null)
+                out[kind] = normalized;
         }
     }
     return out;
@@ -215,8 +246,120 @@ function mergeConfig(partial) {
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
     const modelLadders = mergeModelLadders(partial.modelLadders);
-    const personaStrengths = mergePersonaStrengths(partial.personaStrengths);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, personaStrengths };
+    const kinds = mergeKinds(partial.kinds);
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, kinds };
+}
+/** Raw (un-defaulted) partial config for one scope, or null if the scope has
+ *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+function readRawScopeConfig(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return null;
+    return readJsonIfExists(configPathFor(root));
+}
+/** Raw partial config at `<profileRoot(profileId)>/config.json`, or null when
+ *  no profile is selected, the profile id no longer resolves (deleted/
+ *  invalid), or it has no config.json. `profileRoot` centralizes the id-shape
+ *  + containment checks (never a raw path join), and any resolution failure
+ *  is swallowed here — launch config resolution is a hot path that must never
+ *  throw on a stale `CRTR_PROFILE_ID`. */
+function readRawProfileConfig(profileId) {
+    if (profileId === null || profileId === '')
+        return null;
+    try {
+        return readJsonIfExists(configPathFor(profileRoot(profileId)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Raw partial configs for the whole project-scope STACK (`findProjectScopeRoots`
+ *  — every ancestor `.crouter/`, widened by a selected profile's `projects`),
+ *  ordered FARTHEST-first so `readMergedLaunchConfig` can layer them on last
+ *  and have the NEAREST root win — mirroring the resolver's nearest-project-
+ *  strongest replacement precedence. */
+function readRawProjectScopeConfigs() {
+    const nearestFirst = findProjectScopeRoots();
+    const farthestFirst = [...nearestFirst].reverse();
+    const out = [];
+    for (const root of farthestFirst) {
+        const raw = readJsonIfExists(configPathFor(root));
+        if (raw !== null)
+            out.push(raw);
+    }
+    return out;
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. A kind or ladder cell declared at a
+ *  more-specific scope shadows the same key from a less-specific scope; the
+ *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
+ *  widened by a selected profile's `projects`) layers nearest-root-strongest;
+ *  a key no scope declares falls through to the builtin default registry
+ *  (`defaultScopeConfig().kinds` / `.modelLadders`).
+ *
+ *  Layers RAW (un-defaulted) partial config per scope, not `readConfig(scope)`
+ *  — `readConfig` already fills in every default kind for a scope that
+ *  customizes even one, so naively overlaying two already-defaulted
+ *  `ScopeConfig.kinds` objects would let an untouched project-scope kind
+ *  (silently defaulted) clobber a real user-scope customization of that same
+ *  kind. Layering the raw partials avoids that.
+ *
+ *  Callers (launch, kind registry) go through this function rather than
+ *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
+ *  extensions/`availableTo` all honor the same profile + multi-project
+ *  precedence. */
+export function readMergedLaunchConfig() {
+    const defaults = defaultScopeConfig();
+    const userRaw = readRawScopeConfig('user');
+    const profileRaw = readRawProfileConfig(process.env['CRTR_PROFILE_ID'] || null);
+    const projectRawsFarthestFirst = readRawProjectScopeConfigs();
+    let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
+    let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    if (profileRaw !== null) {
+        kinds = mergeKinds(profileRaw.kinds, kinds);
+        modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+    }
+    for (const raw of projectRawsFarthestFirst) {
+        kinds = mergeKinds(raw.kinds, kinds);
+        modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+    }
+    return { kinds, modelLadders };
+}
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
+ *  project > user > builtin precedence. Returns `undefined` for a kind no
+ *  scope registers — existence is deliberately NOT validated here (kind
+ *  existence/launch-menu enumeration is a Phase 3 caller concern); this only
+ *  resolves the config for a kind the caller already knows about. */
+export function resolveKindConfig(kind) {
+    return readMergedLaunchConfig().kinds[kind];
+}
+/** The sub-kinds available to spawn FROM a given top-level kind — every
+ *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
+ *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to
+ *  `['plan']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/render.ts`) read, so the two can never
+ *  drift apart. Sorted by full kind name for stable rendering. */
+export function subKindsAvailableTo(kind) {
+    const registry = readMergedLaunchConfig().kinds;
+    const out = [];
+    for (const [full, cfg] of Object.entries(registry)) {
+        const slash = full.indexOf('/');
+        if (slash === -1)
+            continue;
+        const topAncestor = full.slice(0, slash);
+        const availableTo = cfg.availableTo ?? [topAncestor];
+        if (!(availableTo.includes('*') || availableTo.includes(kind)))
+            continue;
+        out.push({ kind: full, whenToUse: cfg.whenToUse });
+    }
+    return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/memory-resolver.d.ts

@@ -2,18 +2,20 @@ import type { InstalledPlugin, Scope } from '../types.js';
 /**
  * Thin memory-document resolver for the document substrate. Resolution is scope
  * + leaf/path only: qualifier parse → scope precedence → direct path lookup →
- * leaf-name fallback. The three memory scopes resolve in precedence order
- * project > user > builtin. It returns the raw parsed
- * frontmatter + body; it does NOT interpret the schema, kind, gate, or rungs —
- * that is the schema/gate layer's job (callers filter by `frontmatter.kind`).
- * Project resolution is a nearest-first stack of every ancestor `.crouter/`,
- * while user and builtin remain singleton scopes.
+ * leaf-name fallback. The memory scopes resolve in precedence order project
+ * stack > profile > user > builtin. It returns the raw parsed frontmatter +
+ * body; it does NOT interpret the schema, kind, gate, or rungs — that is the
+ * schema/gate layer's job (callers filter by `frontmatter.kind`). Project
+ * resolution is a nearest-first stack of every ancestor `.crouter/` (widened by
+ * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
+ * in scope.ts), profile is the selected profile's own singleton `memory/` store
+ * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
  */
 export interface MemoryDoc {
     /** Path-derived identity: the doc's path under the scope's memory/ root, no
      *  extension, slash-separated — e.g. memory/taste/foo.md → "taste/foo". */
     name: string;
-    scope: Scope;
+    scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
     path: string;
     /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
@@ -21,26 +23,35 @@ export interface MemoryDoc {
     /** Document body, with the frontmatter block stripped. */
     body: string;
 }
+/** The memory-only scope union: the global `Scope` (`user|project|builtin`)
+ *  plus `profile`. Confined to the memory resolver/list/read/write/render
+ *  paths — deliberately NOT folded into the global `Scope` union, because that
+ *  would leak `profile` into config, plugin, marketplace, view, and doctor/
+ *  sys-config surfaces the spec does not extend. */
+export type MemoryScope = Scope | 'profile';
 export interface MemoryResolutionOpts {
     /** Restrict resolution to a single scope. Conflicts with a scope prefix on
      *  the identifier (e.g. `user/foo` with scope=project) throw. */
-    scope?: Scope;
+    scope?: MemoryScope;
 }
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
 /** All native memory docs for a scope. Project scope is a nearest-first stack of
- *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
-export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
+ *  every ancestor `.crouter/memory/` (widened by a selected profile's project
+ *  stack); profile is the selected profile's own singleton store, resolved
+ *  through `loadProfileManifest`; user and builtin are singleton stores. */
+export declare function listMemoryDocs(scope: MemoryScope, quiet?: boolean): MemoryDoc[];
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
-export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Scope): MemoryDoc[];
+export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean): MemoryDoc[];
 /** All memory docs across the resolved sources, in precedence order: each
- *  ancestor project `.crouter/` from nearest to farthest, then user, then
- *  builtin. Within each source, native docs are emitted before enabled-plugin
- *  docs, so native wins on the caller's first-wins dedup. */
-export declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
+ *  ancestor project `.crouter/` from nearest to farthest, then the selected
+ *  profile's memory (if any), then user, then builtin. Within each source,
+ *  native docs are emitted before enabled-plugin docs, so native wins on the
+ *  caller's first-wins dedup. */
+export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean): MemoryDoc[];
 /**
  * Resolve a path-derived name to a single memory document.
  *

package/dist/core/memory-resolver.js

@@ -6,26 +6,41 @@ import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier }
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
 import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
+import { normalizeDocName, normalizeNameSegment } from './substrate/schema.js';
+import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
 }
-/** The memory scopes in resolution precedence: project > user > builtin.
- *  Project is included only when a project scope exists for the cwd. A single
- *  `scope` narrows to just that scope. */
+/** The selected profile id from the process env, or '' when none. The single
+ *  seam every profile-aware memory/config path reads through — see the plan's
+ *  synthesis decision on why this is process env, not a threaded parameter. */
+function selectedProfileId() {
+    return process.env['CRTR_PROFILE_ID'] || '';
+}
+/** The memory scopes in resolution precedence: project stack > profile > user >
+ *  builtin. Project is included only when a project scope exists for the cwd
+ *  (or the selected profile's project stack); profile is included only when a
+ *  profile is selected. A single `scope` narrows to just that scope. */
 function scopesInPrecedence(scope) {
     if (scope)
         return [scope];
     const out = [];
     if (projectScopeRoot())
         out.push('project');
+    if (selectedProfileId() !== '')
+        out.push('profile');
     out.push('user');
     out.push('builtin');
     return out;
 }
 /** Memory loads project scopes as a stack, not a single nearest root: every
- *  ancestor `.crouter/` from cwd upward contributes, nearest first. User and
- *  builtin remain singleton scopes after that stack. */
+ *  ancestor `.crouter/` from cwd upward (widened by a selected profile's
+ *  `projects`) contributes, nearest first. Profile is a singleton store
+ *  resolved through the centralized `loadProfileManifest` — never a raw path
+ *  join — and drops out silently (never throws the resolver) when the
+ *  selected profile id no longer resolves to a manifest. User and builtin
+ *  remain singleton scopes after that. */
 function memorySourcesInPrecedence(scope) {
     const out = [];
     for (const s of scopesInPrecedence(scope)) {
@@ -38,6 +53,18 @@ function memorySourcesInPrecedence(scope) {
                 });
             }
         }
+        else if (s === 'profile') {
+            const profileId = selectedProfileId();
+            if (profileId !== '') {
+                try {
+                    const { profileId: resolvedId } = loadProfileManifest(profileId);
+                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [] });
+                }
+                catch {
+                    // Missing/deleted/invalid selected profile: no profile memory source.
+                }
+            }
+        }
         else {
             out.push({
                 scope: s,
@@ -56,7 +83,7 @@ function loadMemoryDoc(name, scope, path) {
  *  subdirs supported), sorted by path-derived name. SKILL.md bundles are legacy
  *  Agent Skills and are ignored; crouter memory docs are plain .md files under
  *  memory/. */
-function listMemoryDocsInDir(scope, dir) {
+function listMemoryDocsInDir(scope, dir, quiet = false) {
     if (!dir || !pathExists(dir))
         return [];
     const docs = [];
@@ -76,7 +103,8 @@ function listMemoryDocsInDir(scope, dir) {
                 stack.push(join(d, e.name));
             else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'SKILL.md') {
                 const file = join(d, e.name);
-                const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                const name = normalizeDocName(raw);
                 if (name)
                     found.push({ path: file, name });
             }
@@ -86,35 +114,52 @@ function listMemoryDocsInDir(scope, dir) {
         // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
         // Isolate one malformed doc with a clear scoped notice + skip, so a single
         // bad file can't brick `memory list`/`find` or the substrate boot render.
+        // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
+        // where another doc's health is irrelevant noise before the result.
         try {
             docs.push(loadMemoryDoc(name, scope, path));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            warn(`invalid frontmatter in ${path}: ${msg}`);
+            if (!quiet)
+                warn(`invalid frontmatter in ${path}: ${msg}`);
         }
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
 /** All native memory docs for a scope. Project scope is a nearest-first stack of
- *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
-export function listMemoryDocs(scope) {
+ *  every ancestor `.crouter/memory/` (widened by a selected profile's project
+ *  stack); profile is the selected profile's own singleton store, resolved
+ *  through `loadProfileManifest`; user and builtin are singleton stores. */
+export function listMemoryDocs(scope, quiet = false) {
     if (scope === 'project') {
-        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory')));
+        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory'), quiet));
     }
-    return listMemoryDocsInDir(scope, scopeMemoryDir(scope));
+    if (scope === 'profile') {
+        const profileId = selectedProfileId();
+        if (profileId === '')
+            return [];
+        try {
+            const { profileId: resolvedId } = loadProfileManifest(profileId);
+            return listMemoryDocsInDir('profile', profileMemoryDir(resolvedId), quiet);
+        }
+        catch {
+            return [];
+        }
+    }
+    return listMemoryDocsInDir(scope, scopeMemoryDir(scope), quiet);
 }
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
-export function listPluginMemoryDocs(plugin, scope) {
+export function listPluginMemoryDocs(plugin, scope, quiet = false) {
     const dir = pluginMemoryDir(plugin);
     if (!pathExists(dir))
         return [];
     const docs = [];
     for (const file of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md')) {
-        const derived = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        const derived = normalizeDocName(relative(dir, file).replace(/\.md$/i, '').split(sep).join('/'));
         if (!derived)
             continue;
         const name = `${plugin.name}/${derived}`;
@@ -123,21 +168,84 @@ export function listPluginMemoryDocs(plugin, scope) {
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            warn(`invalid frontmatter in ${file}: ${msg}`);
+            if (!quiet)
+                warn(`invalid frontmatter in ${file}: ${msg}`);
         }
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
 /** All memory docs across the resolved sources, in precedence order: each
- *  ancestor project `.crouter/` from nearest to farthest, then user, then
- *  builtin. Within each source, native docs are emitted before enabled-plugin
- *  docs, so native wins on the caller's first-wins dedup. */
-export function listAllMemoryDocs(scope) {
+ *  ancestor project `.crouter/` from nearest to farthest, then the selected
+ *  profile's memory (if any), then user, then builtin. Within each source,
+ *  native docs are emitted before enabled-plugin docs, so native wins on the
+ *  caller's first-wins dedup. */
+export function listAllMemoryDocs(scope, quiet = false) {
     return memorySourcesInPrecedence(scope).flatMap((source) => [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope)),
+        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
     ]);
 }
+/** Find the direct child of `dir` — a `.md` file (matched on name minus
+ *  extension) or a directory — whose NORMALIZED display name equals
+ *  `segment`. An exact literal match (no prefix to strip) wins over a
+ *  normalized match, so a `spine` dir sitting beside a `01-spine` dir (a
+ *  malformed corpus) never masks the literal one; a well-formed corpus has at
+ *  most one candidate either way. Returns the absolute child path, or null. */
+function matchNormalizedChild(dir, segment, want) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    let normalizedHit = null;
+    for (const e of entries) {
+        if (want === 'dir') {
+            if (!e.isDirectory())
+                continue;
+            if (e.name === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(e.name) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+        else {
+            if (!(e.isFile() && e.name.endsWith('.md')))
+                continue;
+            const base = e.name.slice(0, -3);
+            if (base === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(base) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+    }
+    return normalizedHit;
+}
+/** Resolve a NORMALIZED (numeric-prefix-stripped) segment path against a
+ *  physical memory dir: walk intermediate segments matching each as a
+ *  directory by normalized name, then resolve the final segment as either a
+ *  `.md` file or a directory (the bare-dir -> INDEX.md fallback needs the dir
+ *  match even when a same-named file also exists). Either half is null when
+ *  the segment path does not resolve that way. This is what makes
+ *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
+ *  findable as `spine/has-manager` — the physical path keeps its pins, only
+ *  lookup is prefix-blind. */
+function resolveNormalizedPath(baseDir, segments) {
+    let curDir = baseDir;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = matchNormalizedChild(curDir, segments[i], 'dir');
+        if (!next)
+            return { filePath: null, dirPath: null };
+        curDir = next;
+    }
+    const last = segments[segments.length - 1];
+    return {
+        filePath: matchNormalizedChild(curDir, last, 'file'),
+        dirPath: matchNormalizedChild(curDir, last, 'dir'),
+    };
+}
 /** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
  *  Returns every scope's hit in precedence order; the resolver takes the first
  *  (highest-precedence) one — a fully-specified name is never ambiguous.
@@ -145,7 +253,12 @@ export function listAllMemoryDocs(scope) {
  *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
  *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
  *  INDEX doc — carrying the dir name as its identity. (`taste/INDEX` still
- *  resolves directly as the file path.) */
+ *  resolves directly as the file path.)
+ *
+ *  `name`'s segments are already normalized (a caller-supplied identifier is
+ *  never authored with a numeric prefix); resolution against the physical tree
+ *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
+ *  `NN-`-pinned physical file/dir. */
 function findMemoryMatches(name, scope) {
     const matches = [];
     const segments = name.split('/');
@@ -156,15 +269,17 @@ function findMemoryMatches(name, scope) {
         // ancestor `.crouter/`, then user, then builtin.
         const dir = source.memoryDir;
         if (dir) {
-            const path = join(dir, ...segments) + '.md';
-            if (!isLegacySkillDoc && pathExists(path)) {
-                matches.push(loadMemoryDoc(name, source.scope, path));
+            const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+            if (!isLegacySkillDoc && filePath !== null) {
+                matches.push(loadMemoryDoc(name, source.scope, filePath));
                 continue;
             }
-            const indexPath = join(dir, ...segments, 'INDEX.md');
-            if (pathExists(indexPath)) {
-                matches.push(loadMemoryDoc(name, source.scope, indexPath));
-                continue;
+            if (dirPath !== null) {
+                const indexPath = join(dirPath, 'INDEX.md');
+                if (pathExists(indexPath)) {
+                    matches.push(loadMemoryDoc(name, source.scope, indexPath));
+                    continue;
+                }
             }
         }
         // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
@@ -179,21 +294,22 @@ function findMemoryMatches(name, scope) {
             if (p.name !== pluginName)
                 continue;
             const pdir = pluginMemoryDir(p);
+            const restSegments = rest ? rest.split('/') : [];
             if (rest) {
-                const restSegments = rest.split('/');
-                const ppath = join(pdir, ...restSegments) + '.md';
-                if (restSegments.at(-1) !== 'SKILL' && pathExists(ppath)) {
-                    matches.push(loadMemoryDoc(name, source.scope, ppath));
+                const { filePath } = resolveNormalizedPath(pdir, restSegments);
+                if (restSegments.at(-1) !== 'SKILL' && filePath !== null) {
+                    matches.push(loadMemoryDoc(name, source.scope, filePath));
                     break;
                 }
             }
             // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
-            const pindex = rest
-                ? join(pdir, ...rest.split('/'), 'INDEX.md')
-                : join(pdir, 'INDEX.md');
-            if (pathExists(pindex)) {
-                matches.push(loadMemoryDoc(name, source.scope, pindex));
-                break;
+            const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
+            if (pIndexDir !== null) {
+                const pindex = join(pIndexDir, 'INDEX.md');
+                if (pathExists(pindex)) {
+                    matches.push(loadMemoryDoc(name, source.scope, pindex));
+                    break;
+                }
             }
         }
     }
@@ -207,7 +323,9 @@ function findMemoryByLeaf(leaf, scope) {
         return [];
     let all;
     try {
-        all = listAllMemoryDocs(scope);
+        // Quiet: a targeted read must not spew other docs' frontmatter warnings
+        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+        all = listAllMemoryDocs(scope, true);
     }
     catch {
         return [];

package/dist/core/profiles/manifest.d.ts

@@ -0,0 +1,33 @@
+import type { ProfileManifest } from '../../types.js';
+export declare function profilesRoot(): string;
+export declare function profileRoot(profileId: string): string;
+export declare function profileManifestPath(profileId: string): string;
+export declare function profileMemoryDir(profileId: string): string;
+export interface ProfileEntry {
+    profileId: string;
+    manifest: ProfileManifest;
+}
+/** Every profile with a readable manifest, in directory-listing order.
+ *  Enumerates ONLY immediate children of `profilesRoot()` — never recurses,
+ *  never trusts a caller-supplied id. A dir whose name doesn't match the
+ *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
+ *  rather than crashing the whole listing. */
+export declare function listProfiles(): ProfileEntry[];
+/** Resolve a CLI operand to its profile — exact id first (checked against the
+ *  actually-enumerated dirs, never a blind join), then a unique manifest
+ *  `name` match. Ambiguous names fail listing every matching id; no match
+ *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
+ *  function every command leaf and future runtime consumer (Phase 5/6) should
+ *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
+ *  safe profile id. */
+export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;
+/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
+ *  mutations (create/rename/add-project/remove-project/delete/last-used)
+ *  below run inside this. */
+export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
+export declare function createProfile(name: string, projects?: string[]): ProfileEntry;
+export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
+export declare function renameProfile(profileId: string, name: string): ProfileEntry;
+export declare function addProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function deleteProfile(profileId: string): void;