@north-light/crouter 0.3.186 → 0.3.188

package/dist/commands/pkg/plugin-manage.js

@@ -5,7 +5,7 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
 import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
-import { updateConfig, updateState, ensureScopeInitialized } from '../../core/config.js';
+import { updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons } from '../../core/config.js';
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, atomicWriteJson } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
@@ -45,6 +45,19 @@ function validateHttpInstall(name, endpoint, authEnv) {
         throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
     return transportValidation.transport;
 }
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `kinds` block — the same install-time
+ *  strictness `validatePluginBundle` applies to an archive's bundle.json. The
+ *  read side (`mergeKinds`) drops invalid entries silently, so without this
+ *  the plugin would install cleanly and its kind would just never register. */
+function assertManifestKindsValid(manifest, where) {
+    if (manifest.kinds === undefined)
+        return;
+    const reasons = invalidPluginKindsReasons(manifest.kinds);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid kinds block`, { issues: reasons });
+    }
+}
 function invocationTransport(bundle) {
     return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
 }
@@ -115,6 +128,11 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
         commands: 'commands.json',
         transport,
         bundle,
+        // Kind-registry contributions declared in the archive's bundle.json,
+        // already strictly validated by validatePluginBundle. Copying them here is
+        // what registers them: readMergedLaunchConfig reads kinds from installed
+        // plugin MANIFESTS, never from bundle.json directly.
+        ...(validated.bundle.kinds !== undefined ? { kinds: validated.bundle.kinds } : {}),
     };
     const tmpRoot = join(scopeRootPath, 'tmp');
     const staging = join(tmpRoot, `${name}.${process.pid}`);
@@ -159,7 +177,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
-    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, commands };
+    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, commands };
 }
 async function installHttpPlugin(name, endpoint, authEnv, scope) {
     const source = validateHttpInstall(name, endpoint, authEnv);
@@ -256,6 +274,13 @@ function installFromGit(source, ref, scope) {
         removePath(tempDir);
         throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
     }
+    try {
+        assertManifestKindsValid(manifest, `${source}/.crouter-plugin/plugin.json`);
+    }
+    catch (error) {
+        removePath(tempDir);
+        throw error;
+    }
     const finalName = manifest.name;
     let finalDir = tempDir;
     if (finalName !== tempName) {
@@ -281,6 +306,7 @@ function installFromLocal(source, scope) {
     if (manifest === null) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
+    assertManifestKindsValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
@@ -328,6 +354,13 @@ export function installFromMarketplace(ref, scope) {
         removePath(destPluginDir);
         throw notFound(`plugin manifest not found at ${destPluginDir}/.crouter-plugin/plugin.json`);
     }
+    try {
+        assertManifestKindsValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
+    }
+    catch (error) {
+        removePath(destPluginDir);
+        throw error;
+    }
     const version = entry.version ?? pluginManifest.version;
     updateConfig(scope, (cfg) => {
         const pluginCfg = {
@@ -344,7 +377,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
         const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
-        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, commands: replaced.commands };
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, commands: replaced.commands };
     }
     if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
         rejectLegacyHttpPlugin(plugin.name);
@@ -400,12 +433,13 @@ export const pluginInstall = defineLeaf({
             { name: 'transport', type: 'string', required: false, constraint: 'exec or http when the plugin declares commands. Always http for an --endpoint install.' },
             { name: 'version', type: 'string', required: false, constraint: 'First 12 hex characters of the fetched archive SHA-256 for an --endpoint install.' },
             { name: 'docs', type: 'integer', required: false, constraint: 'Memory document count written from an --endpoint archive.' },
+            { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
         ],
         outputKind: 'object',
         effects: [
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
-            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, and memory docs; a fetch or validation failure preserves the prior package.',
+            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, and any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds); a fetch or validation failure preserves the prior package.',
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
         ],
     },
@@ -552,7 +586,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, commands?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier and docs is the written memory-document count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, commands?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, and kinds is the declared kind-registry entry count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}.' },
         ],
         outputKind: 'object',
         effects: ['Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.'],

package/dist/core/__tests__/plugin-kinds.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/plugin-kinds.test.js

@@ -0,0 +1,180 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/plugin-kinds.test.ts
+//
+// Wiring pins for plugin-declared kinds — the layer whose absence is SILENT:
+// `mergeKinds` drops nothing loudly at read time, so if `readMergedLaunchConfig`
+// stopped layering enabled plugins' manifest `kinds` blocks (or layered them in
+// the wrong precedence slot), every plugin-shipped persona kind would simply
+// vanish from the registry with all suites green. Precedence under pin:
+//   builtin → user plugins → user config → profile → per project root:
+//   (root plugins → root config)
+// Plus the archive path: `validatePluginBundle` must carry a valid bundle.json
+// `kinds` block into `ValidatedBundle.kinds` (what the installer copies into
+// the synthesized manifest) and reject an invalid one loudly.
+import { test, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as tar from 'tar';
+import { resetScopeCache } from '../scope.js';
+import { readMergedLaunchConfig } from '../config.js';
+import { validatePluginBundle } from '../command-plugins/bundle.js';
+let isolatedHome;
+let isolatedCwd;
+let prevHome;
+let prevCwd;
+before(() => {
+    prevHome = process.env.HOME;
+    prevCwd = process.cwd();
+});
+beforeEach(() => {
+    isolatedHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-home-')));
+    isolatedCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-cwd-')));
+    process.env.HOME = isolatedHome;
+    process.chdir(isolatedCwd);
+    resetScopeCache();
+});
+afterEach(() => {
+    process.chdir(prevCwd);
+    rmSync(isolatedHome, { recursive: true, force: true });
+    rmSync(isolatedCwd, { recursive: true, force: true });
+});
+after(() => {
+    process.chdir(prevCwd);
+    process.env.HOME = prevHome;
+    resetScopeCache();
+});
+/** Plant a manifest-only plugin (kinds need no commands or executable). */
+function plantPlugin(scopeRootPath, name, kinds) {
+    const root = join(scopeRootPath, 'plugins', name, '.crouter-plugin');
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, 'plugin.json'), JSON.stringify({ name, version: '0.1.0', kinds }));
+}
+function userRoot() {
+    const root = join(isolatedHome, '.crouter');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+function projectRoot() {
+    const root = join(isolatedCwd, '.crouter');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+test('an enabled user-scope plugin adds a full kind and patches a builtin kind', () => {
+    plantPlugin(userRoot(), 'northlight', {
+        'applet-builder': { whenToUse: 'Build a Northlight applet.', model: 'anthropic/strong' },
+        general: { model: 'openai/light' },
+    });
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['applet-builder']?.whenToUse, 'Build a Northlight applet.');
+    assert.equal(kinds['applet-builder']?.model, 'anthropic/strong');
+    assert.equal(kinds['general']?.model, 'openai/light');
+    // Patch semantics: the builtin general keeps its whenToUse.
+    assert.ok((kinds['general']?.whenToUse ?? '').length > 0);
+});
+test('the scope\u2019s own config.json overrides its plugins; a disabled plugin contributes nothing', () => {
+    const root = userRoot();
+    plantPlugin(root, 'northlight', { 'applet-builder': { whenToUse: 'plugin gloss', model: 'anthropic/strong' } });
+    plantPlugin(root, 'zzz-disabled', { ghost: { whenToUse: 'never registers' } });
+    writeFileSync(join(root, 'config.json'), JSON.stringify({
+        plugins: { 'zzz-disabled': { enabled: false } },
+        kinds: { 'applet-builder': { model: 'openai/medium' } },
+    }));
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['applet-builder']?.model, 'openai/medium'); // config patch wins
+    assert.equal(kinds['applet-builder']?.whenToUse, 'plugin gloss'); // patch merges, not replaces
+    assert.equal(kinds['ghost'], undefined);
+});
+test('a whenToUse-only entry re-glosses an existing kind without stripping its model tier', () => {
+    // The pre-change footgun: `{whenToUse}` parsed as a FULL entry and wholly
+    // replaced the kind, silently dropping explore off its cheap model tier.
+    // Now every entry field-merges over an existing kind; only a NEW kind
+    // requires whenToUse (a whenToUse-less new kind is dropped).
+    const root = userRoot();
+    writeFileSync(join(root, 'config.json'), JSON.stringify({ kinds: { explore: { whenToUse: 'custom explore gloss' }, 'new-glossless': { model: 'openai/light' } } }));
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['explore']?.whenToUse, 'custom explore gloss');
+    assert.equal(kinds['explore']?.model, 'openai/light'); // builtin tier survives
+    assert.equal(kinds['explore']?.orchestratorModel, 'anthropic/strong');
+    assert.equal(kinds['new-glossless'], undefined);
+});
+test('a project-root plugin layers above user config, and the project config above the plugin', () => {
+    const uRoot = userRoot();
+    writeFileSync(join(uRoot, 'config.json'), JSON.stringify({ kinds: { shared: { whenToUse: 'user gloss', model: 'openai/light' } } }));
+    const pRoot = projectRoot();
+    plantPlugin(pRoot, 'proj-plugin', { shared: { model: 'anthropic/strong' }, 'proj-kind': { whenToUse: 'project plugin kind' } });
+    writeFileSync(join(pRoot, 'config.json'), JSON.stringify({ kinds: { 'proj-kind': { model: 'openai/medium' } } }));
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['shared']?.model, 'anthropic/strong'); // project plugin > user config
+    assert.equal(kinds['shared']?.whenToUse, 'user gloss');
+    assert.equal(kinds['proj-kind']?.model, 'openai/medium'); // project config > project plugin
+    assert.equal(kinds['proj-kind']?.whenToUse, 'project plugin kind');
+});
+// --- archive path -----------------------------------------------------------
+function minimalCommandsJson() {
+    return {
+        schemaVersion: 1,
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'app',
+                    description: 'application lifecycle and inspection',
+                    whenToUse: 'you need to inspect an application',
+                    rootEntry: {
+                        concept: 'applications hosted by a crouter home',
+                        description: 'application lifecycle and inspection',
+                        whenToUse: 'you need to inspect an application',
+                    },
+                    summary: 'application lifecycle and inspection',
+                    model: 'Applications are product resources owned by the selected home.',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: 'show one application',
+                            whenToUse: 'inspect a single application by id',
+                            tier: 'important',
+                            summary: 'show one application details',
+                            params: [{ kind: 'positional', name: 'app-id', required: true, constraint: 'the application id' }],
+                            output: [{ name: 'app_id', type: 'string', required: true, constraint: 'the echoed application id' }],
+                            effects: ['None. Read-only.'],
+                            rest: { method: 'GET', path: '/v1/apps/{app-id}', params: { 'app-id': { in: 'path' } } },
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+}
+function makeArchive(bundleJson) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-tar-'));
+    try {
+        writeFileSync(join(dir, 'bundle.json'), JSON.stringify(bundleJson));
+        writeFileSync(join(dir, 'commands.json'), JSON.stringify(minimalCommandsJson()));
+        const pack = tar.create({ sync: true, cwd: dir, portable: true }, ['bundle.json', 'commands.json']);
+        const chunks = [];
+        let chunk;
+        while ((chunk = pack.read()) !== null)
+            chunks.push(chunk);
+        return new Uint8Array(Buffer.concat(chunks));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+test('validatePluginBundle carries a valid bundle.json kinds block into ValidatedBundle', async () => {
+    const archive = makeArchive({ bundleVersion: 1, kinds: { 'applet-builder': { whenToUse: 'Build an applet.', model: 'anthropic/strong' } } });
+    const validated = await validatePluginBundle(archive, { reservedCoreNames: new Set(['node']) });
+    assert.deepEqual(validated.issues, []);
+    assert.deepEqual(validated.bundle?.kinds, { 'applet-builder': { whenToUse: 'Build an applet.', model: 'anthropic/strong' } });
+});
+test('validatePluginBundle rejects an invalid kinds block loudly', async () => {
+    const archive = makeArchive({ bundleVersion: 1, kinds: { broken: { when_to_use: 'typo field' } } });
+    const validated = await validatePluginBundle(archive, { reservedCoreNames: new Set(['node']) });
+    assert.equal(validated.bundle, undefined);
+    assert.equal(validated.issues.length, 1);
+    assert.match(validated.issues[0].message, /kinds block is invalid/);
+    assert.match(validated.issues[0].received, /when_to_use/);
+});

package/dist/core/command-plugins/bundle.d.ts

@@ -1,4 +1,5 @@
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
+import type { KindConfig } from '../../types.js';
 export interface BundleIssue {
     code: string;
     path?: string;
@@ -9,6 +10,11 @@ export interface BundleIssue {
 }
 export interface ValidatedBundle {
     bundleVersion: 1;
+    /** Kind-registry contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `readMergedLaunchConfig` layers it — see
+     *  `PluginManifest.kinds`. */
+    kinds?: Record<string, Partial<KindConfig>>;
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -1,5 +1,6 @@
 import { Parser } from 'tar';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
+import { invalidPluginKindsReasons } from '../config.js';
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -134,12 +135,32 @@ function parseBundleMetadata(bytes) {
         raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
     }
     catch {
-        return bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json');
+        return { issue: bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json') };
     }
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || Object.keys(raw).length !== 1 || raw['bundleVersion'] !== 1) {
-        return bundleInvalid('bundle.json must contain exactly {"bundleVersion":1}', JSON.stringify(raw), 'an object with only bundleVersion set to 1', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json');
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return {
+            issue: bundleInvalid('bundle.json must be a JSON object', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json'),
+        };
     }
-    return undefined;
+    const record = raw;
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds');
+    if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most a kinds block', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object.', 'bundle.json'),
+        };
+    }
+    if (record['kinds'] === undefined)
+        return {};
+    // Install-time strictness: a bad kinds block fails the install loudly here,
+    // because the read side (`mergeKinds`) drops invalid entries silently and
+    // would otherwise ship a kind that never registers.
+    const reasons = invalidPluginKindsReasons(record['kinds']);
+    if (reasons.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
+        };
+    }
+    return { kinds: record['kinds'] };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
     let raw;
@@ -175,15 +196,16 @@ export async function validatePluginBundle(archive, options) {
             issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
         };
     }
-    const metadataIssue = parseBundleMetadata(bundle.bytes);
-    if (metadataIssue !== undefined)
-        return { issues: [metadataIssue] };
+    const metadata = parseBundleMetadata(bundle.bytes);
+    if (metadata.issue !== undefined)
+        return { issues: [metadata.issue] };
     const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames, options.coreCommandPaths);
     if (commandValidation.commands === undefined)
         return { issues: commandValidation.issues };
     return {
         bundle: {
             bundleVersion: 1,
+            ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members

package/dist/core/config.d.ts

@@ -26,6 +26,14 @@ export declare function ensureScopeInitialized(scope: Scope, root: string): void
 /** Normalize the user-owned list of attach actions allowed to bridge through an
  * occupied tmux root binding. Unknown and non-attach ids have no effect. */
 export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export declare function invalidPluginKindsReasons(raw: unknown): string[];
 /** 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
@@ -49,7 +57,10 @@ export interface MergedLaunchConfig {
 }
 /** 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
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. 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;