@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -16,6 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  */
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
 const { stageSkillsForProfile, stageAgentsForProfile, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
@@ -129,7 +130,7 @@ function findAgentsSourceRoot(runtimeConfigDir) {
 const ALLOWED_RUNTIMES = new Set([
     'claude', 'cursor', 'gemini', 'codex', 'copilot', 'antigravity',
     'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy',
-    'cline', 'opencode', 'kilo',
+    'cline', 'kimi', 'opencode', 'kilo',
 ]);
 // ---------------------------------------------------------------------------
 // Layout table builders
@@ -150,6 +151,43 @@ function agentsKind(destSubpath, prefix, configDir) {
         stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
     };
 }
+function kimiAgentsKind(destSubpath, prefix, configDir) {
+    return {
+        kind: 'kimi-agents',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const installExports = getInstallExports();
+            const buildKimiAgentArtifacts = installExports['buildKimiAgentArtifacts'];
+            const stagedAgents = stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved);
+            const subagents = [];
+            if (node_fs_1.default.existsSync(stagedAgents)) {
+                for (const entry of node_fs_1.default.readdirSync(stagedAgents, { withFileTypes: true })) {
+                    if (!entry.isFile() || !entry.name.endsWith('.md'))
+                        continue;
+                    const agentPath = node_path_1.default.join(stagedAgents, entry.name);
+                    subagents.push({
+                        path: node_path_1.default.join('agents', entry.name).replace(/\\/g, '/'),
+                        content: node_fs_1.default.readFileSync(agentPath, 'utf8'),
+                    });
+                }
+            }
+            const rootAgent = `---\nname: gsd\ndescription: Run GSD workflows in Kimi CLI.\ntools: Agent\n---\n\n# GSD for Kimi CLI\n\nCoordinate installed /skill:gsd-* workflows and route work to generated GSD subagents when a workflow requires an agent handoff.\n`;
+            const artifacts = buildKimiAgentArtifacts({ rootAgent, subagents });
+            const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-kimi-agents-'));
+            installProfiles.STAGED_DIRS.add(stageDir);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, 'gsd.yaml'), artifacts.root.yaml);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, 'gsd.md'), artifacts.root.prompt);
+            const subagentsDir = node_path_1.default.join(stageDir, 'subagents');
+            node_fs_1.default.mkdirSync(subagentsDir, { recursive: true });
+            for (const artifact of artifacts.subagents) {
+                node_fs_1.default.writeFileSync(node_path_1.default.join(subagentsDir, `${artifact.name}.yaml`), artifact.yaml);
+                node_fs_1.default.writeFileSync(node_path_1.default.join(subagentsDir, `${artifact.name}.md`), artifact.prompt);
+            }
+            return stageDir;
+        },
+    };
+}
 /**
  * Build a skills kind descriptor.
  *
@@ -158,8 +196,13 @@ function agentsKind(destSubpath, prefix, configDir) {
  * @param converterName  name of converter function in bin/install.js exports
  * @param runtime        canonical runtime ID (gates Hermes/Qwen branding in converter)
  * @param configDir      runtime config dir (for .gsd-source marker resolution)
+ * @param nested         if true, nest concrete skills under their ns-* routers (#69)
+ * @param scope          install scope; converted to isGlobal and passed as 5th positional
+ *                       arg so scope-aware converters (antigravity, copilot) can choose
+ *                       between global home paths and workspace-relative paths without
+ *                       colliding with the `runtime` string at position 3.
  */
-function skillsKind(destSubpath, prefix, converterName, runtime, configDir) {
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global') {
     return {
         kind: 'skills',
         destSubpath,
@@ -168,10 +211,15 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir) {
             const installExports = getInstallExports();
             const realConverter = installExports[converterName];
             // Compute cmdNames once per stage call for performance (#3583).
-            // Extra args are ignored by converters that don't need runtime/cmdNames.
+            // Extra trailing args are ignored by converters that don't need them. The
+            // isGlobal flag is the 5th positional (NOT the 3rd): the 3rd positional is
+            // `runtime` for the claude/kimi/cline converters, so the scope-aware
+            // converters (antigravity, copilot) read isGlobal from position 5 to avoid
+            // colliding with `runtime` and always taking the global branch.
             const cmdNames = installExports.readGsdCommandNames();
-            const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames);
-            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix);
+            const isGlobal = scope === 'global';
+            const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames, isGlobal);
+            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
         },
     };
 }
@@ -203,11 +251,41 @@ function convertedCommandsKind(destSubpath, prefix, converterName, configDir) {
         },
     };
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+/** Lazy registry accessor — mirrors pattern from 5b/5c (runtime-homes.cts). */
+function getRegistry() {
+    return _require('./capability-registry.cjs');
+}
+/**
+ * Map a single ArtifactKindDescriptor entry to an ArtifactKind using the
+ * matching builder function. Mirrors the hand-built calls in the old switch.
+ */
+function dispatchKindEntry(entry, runtime, configDir, scope) {
+    const { kind, destSubpath, prefix, nesting, converter } = entry;
+    const nested = nesting === 'nested';
+    switch (kind) {
+        case 'commands':
+            if (converter == null) {
+                return commandsKind(destSubpath, prefix, configDir);
+            }
+            return convertedCommandsKind(destSubpath, prefix, converter, configDir);
+        case 'agents':
+            return agentsKind(destSubpath, prefix, configDir);
+        case 'skills':
+            if (converter == null) {
+                throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
+            }
+            return skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+        case 'kimi-agents':
+            return kimiAgentsKind(destSubpath, prefix, configDir);
+        default:
+            throw new TypeError(`resolveRuntimeArtifactLayout: unknown kind '${kind}' in descriptor for runtime '${runtime}'`);
+    }
+}
 /**
  * Resolve the artifact layout for a given runtime and config directory.
+ *
+ * ADR-857 phase 5d: driven by the capability-registry artifactLayout descriptor
+ * instead of a hardcoded switch statement.
  */
 function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
     if (typeof configDir !== 'string' || configDir === '') {
@@ -219,94 +297,13 @@ function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
     if (!ALLOWED_RUNTIMES.has(runtime)) {
         throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
-    let kinds;
-    switch (runtime) {
-        case 'claude':
-            if (scope === 'local') {
-                kinds = [
-                    commandsKind('commands/gsd', 'gsd-', configDir),
-                    agentsKind('agents', 'gsd-', configDir),
-                ];
-            }
-            else {
-                kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'claude', configDir)];
-            }
-            break;
-        case 'cursor':
-            // Cursor 1.6+ supports two artifact surfaces:
-            //   1. skills/gsd-<name>/SKILL.md  — rich skills with frontmatter + adapter header
-            //   2. commands/gsd-<name>.md      — plain markdown slash commands (no frontmatter)
-            //      accessed via '/' in the Agent input (#785)
-            kinds = [
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCursorSkill', 'cursor', configDir),
-                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCursorCommand', configDir),
-            ];
-            break;
-        case 'gemini':
-            kinds = [commandsKind('commands/gsd', 'gsd-', configDir)];
-            break;
-        case 'codex':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodexSkill', 'codex', configDir)];
-            break;
-        case 'copilot':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCopilotSkill', 'copilot', configDir)];
-            break;
-        case 'antigravity':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAntigravitySkill', 'antigravity', configDir)];
-            break;
-        case 'windsurf':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToWindsurfSkill', 'windsurf', configDir)];
-            break;
-        case 'augment':
-            kinds = [
-                commandsKind('commands', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToAugmentSkill', 'augment', configDir),
-            ];
-            break;
-        case 'trae':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToTraeSkill', 'trae', configDir)];
-            break;
-        case 'qwen':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'qwen', configDir)];
-            break;
-        case 'hermes':
-            kinds = [skillsKind('skills/gsd', '', 'convertClaudeCommandToClaudeSkill', 'hermes', configDir)];
-            break;
-        case 'codebuddy':
-            // CodeBuddy (Tencent) reads two user-level surfaces (codebuddy.ai/docs/cli):
-            //   1. commands/gsd-<name>.md      — slash commands shown in the '/' menu (#789)
-            //   2. skills/gsd-<name>/SKILL.md  — model-invocable skills, emitted with
-            //      user-invocable:false so they stay OUT of '/' (the commands surface is
-            //      the sole '/' entry point) — avoids a duplicated /gsd-* per workflow.
-            // Subagents (~/.codebuddy/agents/) are already emitted by the generic agents
-            // block in bin/install.js; MCP is excluded (gsd ships no MCP server).
-            kinds = [
-                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCodebuddyCommand', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodebuddySkill', 'codebuddy', configDir),
-            ];
-            break;
-        case 'cline':
-            kinds = scope === 'global' ? [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClineSkill', 'cline', configDir)] : [];
-            break;
-        case 'opencode':
-            // OpenCode reads flat slash commands from command/ and on-demand skills
-            // from skills/<name>/SKILL.md (https://opencode.ai/docs/skills). Emit both.
-            kinds = [
-                commandsKind('command', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToOpencodeSkill', 'opencode', configDir),
-            ];
-            break;
-        case 'kilo':
-            // Kilo derives from OpenCode and shares the skills/<name>/SKILL.md layout
-            // (https://kilo.ai/docs/customize/skills). Emit flat commands + skills.
-            kinds = [
-                commandsKind('command', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToKiloSkill', 'kilo', configDir),
-            ];
-            break;
-        default:
-            throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
+    const desc = getRegistry().runtimes[runtime]?.runtime?.artifactLayout;
+    if (!desc) {
+        // Runtime is in ALLOWED_RUNTIMES but has no descriptor — reproduce old default: throw.
+        throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
+    const entries = desc[scope] ?? [];
+    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope));
     return { runtime, configDir, scope, kinds };
 }
 module.exports = { resolveRuntimeArtifactLayout, findInstallSourceRoot, getInstallExports };

package/gsd-core/bin/lib/runtime-config-adapter-registry.cjs

@@ -1,29 +1,39 @@
 'use strict';
-// ---------------------------------------------------------------------------
-// Registry
-// ---------------------------------------------------------------------------
-const REGISTRY = Object.freeze({
-    claude: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    gemini: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    antigravity: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    augment: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    qwen: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    hermes: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    codebuddy: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
-    opencode: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: 'opencode' }),
-    kilo: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: false, finishPermissionWriter: 'kilo' }),
-    codex: Object.freeze({ installSurface: 'codex-toml', writesSharedSettings: false, finishPermissionWriter: null }),
-    copilot: Object.freeze({ installSurface: 'copilot-instructions', writesSharedSettings: false, finishPermissionWriter: null }),
-    cline: Object.freeze({ installSurface: 'cline-rules', writesSharedSettings: false, finishPermissionWriter: null }),
-    cursor: Object.freeze({ installSurface: 'cursor-hooks-json', writesSharedSettings: false, finishPermissionWriter: null }),
-    windsurf: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
-    trae: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
-});
+/**
+ * Runtime config adapter registry — dispatch table for install-phase config
+ * mutations (issue #60), replacing inline `runtime === '...'` branching in
+ * bin/install.js.
+ *
+ * ADR-857 phase 5g drive 2: The hand-kept REGISTRY const has been retired.
+ * Values are now read directly from the capability-registry.cjs descriptor
+ * (capabilities/<id>/capability.json runtime block) so a single source of
+ * truth drives all surfaces.
+ *
+ * Design notes:
+ * - `installSurface` selects which config handler install() runs:
+ *     'settings-json'        → fall through to the shared settings.json accumulation.
+ *     'codex-toml'           → early-return after writing codex.toml.
+ *     'copilot-instructions' → early-return after writing .github/copilot-instructions.md.
+ *     'cline-rules'          → early-return after writing .clinerules.
+ *     'cursor-hooks-json'    → early-return after writing .cursor/hooks.json (issue #777).
+ *     'profile-marker-only'  → early-return after writing only the profile marker.
+ * - `writesSharedSettings` is the finishInstall writeSettings gate:
+ *     false for codex / copilot / kilo / cursor / windsurf / trae / cline / kimi (legacy exclusion list).
+ *     true for all other runtimes.
+ * - `finishPermissionWriter` names the finishInstall-phase dedicated config writer:
+ *     'opencode' → writes BOTH shared settings AND its own permissions file.
+ *     'kilo'     → writes only its own permissions file.
+ *     null       → no dedicated permission writer.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { runtimes } = require('./capability-registry.cjs');
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
-/** The complete set of 15 supported runtimes for config-adapter dispatch. */
-const ALLOWED_CONFIG_RUNTIMES = new Set(Object.keys(REGISTRY));
+/** The complete set of 16 supported runtimes for config-adapter dispatch. */
+const ALLOWED_CONFIG_RUNTIMES = new Set(Object.entries(runtimes)
+    .filter(([, cap]) => cap && cap.runtime && typeof cap.runtime['installSurface'] === 'string')
+    .map(([id]) => id));
 /** All valid installSurface values. */
 const INSTALL_SURFACES = Object.freeze([
     'settings-json',
@@ -42,15 +52,44 @@ const INSTALL_SURFACES = Object.freeze([
  * @throws {TypeError} if runtime is not a known supported runtime.
  */
 function resolveRuntimeConfigIntent(runtime) {
-    if (!Object.hasOwn(REGISTRY, runtime)) {
+    const entry = runtimes[runtime]?.runtime;
+    if (!entry)
         throw new TypeError(`Unknown runtime for config adapter: ${runtime}`);
-    }
-    const entry = REGISTRY[runtime];
+    const permissionWriter = entry['permissionWriter'];
+    return {
+        runtime,
+        installSurface: entry['installSurface'],
+        writesSharedSettings: entry['writesSharedSettings'],
+        finishPermissionWriter: permissionWriter == null ? null : permissionWriter,
+    };
+}
+/**
+ * Resolve the complete install plan for a given runtime.
+ *
+ * Composes the config-intent axes from resolveRuntimeConfigIntent PLUS the
+ * three hook axes (hookEvents / extendedHookEvents / hooksSurface) that
+ * install() previously read scattered from the capability registry.
+ *
+ * ADR-857 phase 5g capstone — single typed seam for all install-level
+ * descriptor reads. Returns a fresh object each call.
+ *
+ * @throws {TypeError} if runtime is not a known supported runtime.
+ */
+function resolveInstallPlan(runtime) {
+    const desc = runtimes[runtime]?.runtime;
+    if (!desc)
+        throw new TypeError(`Unknown runtime for install plan: ${runtime}`);
+    const configIntent = resolveRuntimeConfigIntent(runtime);
     return {
         runtime,
-        installSurface: entry.installSurface,
-        writesSharedSettings: entry.writesSharedSettings,
-        finishPermissionWriter: entry.finishPermissionWriter,
+        installSurface: configIntent.installSurface,
+        writesSharedSettings: configIntent.writesSharedSettings,
+        finishPermissionWriter: configIntent.finishPermissionWriter,
+        hookEvents: desc['hookEvents'],
+        extendedHookEvents: Array.isArray(desc['extendedHookEvents']) ? desc['extendedHookEvents'] : [],
+        hooksSurface: desc['hooksSurface'] != null
+            ? desc['hooksSurface']
+            : ((runtime === 'opencode' || runtime === 'kilo') ? 'none' : 'settings-json'),
     };
 }
-module.exports = { resolveRuntimeConfigIntent, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };
+module.exports = { resolveRuntimeConfigIntent, resolveInstallPlan, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -15,12 +15,28 @@
  *   cline   — Skills-capable since v3.48.0 (#782). SKILL.md files live at
  *             ~/.cline/skills/<skillName>/SKILL.md (same flat layout as cursor/codex).
  *             .clinerules is also emitted (rules-based compatibility layer).
+ *   kimi    — Agent Skills are discovered from Kimi's generic user roots:
+ *             ~/.config/agents/skills (recommended) then ~/.agents/skills,
+ *             with Kimi selecting the first existing generic skills directory.
+ *             ~/.kimi-code/skills is brand-specific and can be selected as a
+ *             GSD write target with --config-dir or KIMI_CONFIG_DIR.
+ *   trae    — Targets Trae IDE (trae.ai), the Electron-based IDE — NOT
+ *             trae-agent (github.com/bytedance/trae-agent), a Python CLI that
+ *             uses trae_config.yaml, has no ~/.trae directory, and has no
+ *             skills system. Both are ByteDance "Trae" products; they are
+ *             entirely distinct. The global ~/.trae/skills/ path is
+ *             community-soft-confirmed: docs.trae.ai/ide/skills documents the
+ *             SKILL.md format and project-level .trae/skills/, but does NOT
+ *             publish the global on-disk path; ~/.trae/skills/ rests on
+ *             community evidence incl. Trae-AI/TRAE#2253. Best-effort only.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
+exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
 exports.getGlobalSkillsBase = getGlobalSkillsBase;
 exports.getGlobalSkillDir = getGlobalSkillDir;
@@ -38,26 +54,142 @@ function expandTilde(p) {
         return node_path_1.default.join(node_os_1.default.homedir(), p.slice(1));
     return p;
 }
+/**
+ * Resolve a configHome descriptor to an absolute directory path.
+ *
+ * Implements the four descriptor kinds:
+ *   - dot-home:           env-override → path.join(home, name)
+ *   - dot-home-nested:    env-override → probed subdir of path.join(home, parent)
+ *   - xdg:                env[0] → env[1](dirname) → env[2](XDG subdir) → ~/.config/<name>
+ *   - generic-agents-root:env[0] → first probe where probeExists exists → probe[0]
+ */
+function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
+    switch (configHome.kind) {
+        case 'dot-home': {
+            // First env var that is set wins
+            for (const varName of configHome.env) {
+                const val = env[varName];
+                if (val)
+                    return expandTilde(val);
+            }
+            return node_path_1.default.join(home, configHome.name);
+        }
+        case 'dot-home-nested': {
+            // env override
+            const nestedEnv0Val = env[configHome.env[0]];
+            if (configHome.env[0] && nestedEnv0Val) {
+                return expandTilde(nestedEnv0Val);
+            }
+            const base = node_path_1.default.join(home, configHome.parent);
+            if (configHome.probe && configHome.probe.length > 0) {
+                // probe each candidate under base; return first that exists
+                for (const candidate of configHome.probe) {
+                    const resolved = node_path_1.default.join(base, candidate);
+                    if (existsSyncFn(resolved))
+                        return resolved;
+                }
+                // fallback: first probe candidate
+                return node_path_1.default.join(base, configHome.probe[0]);
+            }
+            // no probe (e.g. windsurf): always name under parent
+            return node_path_1.default.join(base, configHome.name);
+        }
+        case 'xdg': {
+            // env[0]: direct override dir
+            const xdgEnv0Val = env[configHome.env[0]];
+            if (configHome.env[0] && xdgEnv0Val) {
+                return expandTilde(xdgEnv0Val);
+            }
+            // env[1]: FILE path → dirname
+            const xdgEnv1Val = env[configHome.env[1]];
+            if (configHome.env[1] && xdgEnv1Val) {
+                return node_path_1.default.dirname(expandTilde(xdgEnv1Val));
+            }
+            // env[2]: XDG_CONFIG_HOME → subdir
+            const xdgEnv2Val = env[configHome.env[2]];
+            if (configHome.env[2] && xdgEnv2Val) {
+                return node_path_1.default.join(expandTilde(xdgEnv2Val), configHome.name);
+            }
+            return node_path_1.default.join(home, '.config', configHome.name);
+        }
+        case 'generic-agents-root': {
+            // env override
+            const garEnv0Val = env[configHome.env[0]];
+            if (configHome.env[0] && garEnv0Val) {
+                return expandTilde(garEnv0Val);
+            }
+            // probe each candidate; return first where probeExists subpath exists
+            for (const candidate of configHome.probe) {
+                const resolved = expandTildeWithHome(candidate, home);
+                if (existsSyncFn(node_path_1.default.join(resolved, configHome.probeExists))) {
+                    return resolved;
+                }
+            }
+            // fallback: first probe candidate
+            return expandTildeWithHome(configHome.probe[0], home);
+        }
+    }
+}
+/**
+ * Expand ~ using an explicit home directory (for hermetic testing).
+ */
+function expandTildeWithHome(p, home) {
+    if (!p)
+        return p;
+    if (p.startsWith('~/') || p === '~')
+        return node_path_1.default.join(home, p.slice(1));
+    return p;
+}
 /**
  * Resolve Antigravity global config dir across 1.x and 2.x layouts.
+ *
+ * Thin wrapper delegating to resolveConfigHomeFromDescriptor with the
+ * antigravity descriptor shape. Preserved for external callers and tests.
  */
 function resolveAntigravityGlobalDir(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? node_os_1.default.homedir();
     const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
-    if (env['ANTIGRAVITY_CONFIG_DIR'])
-        return expandTilde(env['ANTIGRAVITY_CONFIG_DIR']);
-    const base = node_path_1.default.join(home, '.gemini');
-    const candidates = [
-        node_path_1.default.join(base, 'antigravity'),
-        node_path_1.default.join(base, 'antigravity-ide'),
-        node_path_1.default.join(base, 'antigravity-cli'),
-    ];
-    for (const candidate of candidates) {
-        if (existsSyncFn(candidate))
-            return candidate;
-    }
-    return node_path_1.default.join(base, 'antigravity');
+    return resolveConfigHomeFromDescriptor({
+        kind: 'dot-home-nested',
+        name: 'antigravity',
+        parent: '.gemini',
+        env: ['ANTIGRAVITY_CONFIG_DIR'],
+        probe: ['antigravity', 'antigravity-ide', 'antigravity-cli'],
+    }, { env, home, existsSync: existsSyncFn });
+}
+/**
+ * Resolve Kimi's generic user root using Kimi CLI's documented first-existing
+ * generic skills directory policy:
+ *
+ *   1. ~/.config/agents/skills  (recommended)
+ *   2. ~/.agents/skills
+ *
+ * If neither generic skills directory exists yet, install to the recommended
+ * ~/.config/agents root so the generated skills become the first generic
+ * candidate Kimi discovers.
+ *
+ * KIMI_CONFIG_DIR is a GSD installer write-location override. It is not Kimi's
+ * upstream data-root variable, and arbitrary roots are discoverable by Kimi only
+ * when the user also configures Kimi --skills-dir or extra_skill_dirs.
+ *
+ * Thin wrapper delegating to resolveConfigHomeFromDescriptor with the
+ * kimi descriptor shape. Preserved for external callers and tests.
+ */
+function resolveKimiGlobalDir(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
+    return resolveConfigHomeFromDescriptor({
+        kind: 'generic-agents-root',
+        name: 'agents',
+        env: ['KIMI_CONFIG_DIR'],
+        probe: ['~/.config/agents', '~/.agents'],
+        probeExists: 'skills',
+    }, { env, home, existsSync: existsSyncFn });
 }
 /**
  * Return the global config base directory for the given runtime.
@@ -71,81 +203,25 @@ function resolveAntigravityGlobalDir(opts = {}) {
 function getGlobalConfigDir(runtime, explicitDir) {
     if (explicitDir)
         return expandTilde(explicitDir);
-    const home = node_os_1.default.homedir();
-    const env = process.env;
-    switch (runtime) {
-        // ── Claude Code ──────────────────────────────────────────────────────────
-        case 'claude':
-            return env['CLAUDE_CONFIG_DIR'] ? expandTilde(env['CLAUDE_CONFIG_DIR']) : node_path_1.default.join(home, '.claude');
-        // ── Cursor ───────────────────────────────────────────────────────────────
-        case 'cursor':
-            return env['CURSOR_CONFIG_DIR'] ? expandTilde(env['CURSOR_CONFIG_DIR']) : node_path_1.default.join(home, '.cursor');
-        // ── Gemini CLI ───────────────────────────────────────────────────────────
-        case 'gemini':
-            return env['GEMINI_CONFIG_DIR'] ? expandTilde(env['GEMINI_CONFIG_DIR']) : node_path_1.default.join(home, '.gemini');
-        // ── Codex ────────────────────────────────────────────────────────────────
-        case 'codex':
-            return env['CODEX_HOME'] ? expandTilde(env['CODEX_HOME']) : node_path_1.default.join(home, '.codex');
-        // ── Grok Build ───────────────────────────────────────────────────────────
-        case 'grok':
-            return env['GROK_AGENTS_HOME'] ? expandTilde(env['GROK_AGENTS_HOME']) : node_path_1.default.join(home, '.agents');
-        // ── Copilot (VS Code) ────────────────────────────────────────────────────
-        case 'copilot':
-            if (env['COPILOT_CONFIG_DIR'])
-                return expandTilde(env['COPILOT_CONFIG_DIR']);
-            if (env['COPILOT_HOME'])
-                return expandTilde(env['COPILOT_HOME']);
-            return node_path_1.default.join(home, '.copilot');
-        // ── Antigravity ──────────────────────────────────────────────────────────
-        case 'antigravity':
-            return resolveAntigravityGlobalDir({ env, home });
-        // ── Windsurf ─────────────────────────────────────────────────────────────
-        case 'windsurf':
-            return env['WINDSURF_CONFIG_DIR']
-                ? expandTilde(env['WINDSURF_CONFIG_DIR'])
-                : node_path_1.default.join(home, '.codeium', 'windsurf');
-        // ── Augment ──────────────────────────────────────────────────────────────
-        case 'augment':
-            return env['AUGMENT_CONFIG_DIR'] ? expandTilde(env['AUGMENT_CONFIG_DIR']) : node_path_1.default.join(home, '.augment');
-        // ── Trae ─────────────────────────────────────────────────────────────────
-        case 'trae':
-            return env['TRAE_CONFIG_DIR'] ? expandTilde(env['TRAE_CONFIG_DIR']) : node_path_1.default.join(home, '.trae');
-        // ── Qwen Code ────────────────────────────────────────────────────────────
-        case 'qwen':
-            return env['QWEN_CONFIG_DIR'] ? expandTilde(env['QWEN_CONFIG_DIR']) : node_path_1.default.join(home, '.qwen');
-        // ── Hermes Agent ─────────────────────────────────────────────────────────
-        case 'hermes':
-            return env['HERMES_HOME'] ? expandTilde(env['HERMES_HOME']) : node_path_1.default.join(home, '.hermes');
-        // ── CodeBuddy ────────────────────────────────────────────────────────────
-        case 'codebuddy':
-            return env['CODEBUDDY_CONFIG_DIR'] ? expandTilde(env['CODEBUDDY_CONFIG_DIR']) : node_path_1.default.join(home, '.codebuddy');
-        // ── Cline ────────────────────────────────────────────────────────────────
-        case 'cline':
-            return env['CLINE_CONFIG_DIR'] ? expandTilde(env['CLINE_CONFIG_DIR']) : node_path_1.default.join(home, '.cline');
-        // ── OpenCode (XDG) ───────────────────────────────────────────────────────
-        case 'opencode': {
-            if (env['OPENCODE_CONFIG_DIR'])
-                return expandTilde(env['OPENCODE_CONFIG_DIR']);
-            if (env['OPENCODE_CONFIG'])
-                return node_path_1.default.dirname(expandTilde(env['OPENCODE_CONFIG']));
-            if (env['XDG_CONFIG_HOME'])
-                return node_path_1.default.join(expandTilde(env['XDG_CONFIG_HOME']), 'opencode');
-            return node_path_1.default.join(home, '.config', 'opencode');
-        }
-        // ── Kilo (XDG) ───────────────────────────────────────────────────────────
-        case 'kilo': {
-            if (env['KILO_CONFIG_DIR'])
-                return expandTilde(env['KILO_CONFIG_DIR']);
-            if (env['KILO_CONFIG'])
-                return node_path_1.default.dirname(expandTilde(env['KILO_CONFIG']));
-            if (env['XDG_CONFIG_HOME'])
-                return node_path_1.default.join(expandTilde(env['XDG_CONFIG_HOME']), 'kilo');
-            return node_path_1.default.join(home, '.config', 'kilo');
-        }
-        // ── Default (Claude fallback) ─────────────────────────────────────────────
-        default:
-            return env['CLAUDE_CONFIG_DIR'] ? expandTilde(env['CLAUDE_CONFIG_DIR']) : node_path_1.default.join(home, '.claude');
+    // ── Grok: not in the registry — hardcoded branch ─────────────────────────
+    if (runtime === 'grok') {
+        const env = process.env;
+        return env['GROK_AGENTS_HOME'] ? expandTilde(env['GROK_AGENTS_HOME']) : node_path_1.default.join(node_os_1.default.homedir(), '.agents');
     }
+    // ── Descriptor-driven: look up in capability-registry ────────────────────
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { runtimes } = require('./capability-registry.cjs');
+    const runtimeEntry = runtimes[runtime];
+    if (runtimeEntry?.runtime?.configHome) {
+        return resolveConfigHomeFromDescriptor(runtimeEntry.runtime.configHome, {
+            env: process.env,
+            home: node_os_1.default.homedir(),
+            existsSync: node_fs_1.default.existsSync,
+        });
+    }
+    // ── Default (unknown runtime → Claude fallback) ───────────────────────────
+    const env = process.env;
+    return env['CLAUDE_CONFIG_DIR'] ? expandTilde(env['CLAUDE_CONFIG_DIR']) : node_path_1.default.join(node_os_1.default.homedir(), '.claude');
 }
 /**
  * Return the global skills base directory for the given runtime.