aiden-runtime 4.0.1 → 4.1.0

package/dist/cli/v4/commands/mcp.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/mcp.ts — Phase v4.1-mcp
+ *
+ * `aiden mcp <action>` subcommand. Three actions:
+ *
+ *   serve   — spawn the MCP stdio server. Blocks until parent closes
+ *             stdio (this is the canonical Claude Desktop /
+ *             Cursor / Claude Code lifecycle).
+ *   status  — print build fingerprint, exposed tool/skill counts, and
+ *             current env config. Quick sanity check before pointing
+ *             a client at the binary.
+ *   tools   — list every exposed tool name + category. Useful when the
+ *             user wants to know what their allowlist currently maps
+ *             to before they save the client config.
+ *
+ * `serve` runs in a deliberately stripped-down runtime: tools,
+ * skill loader, sessions, memory, processes — but NO provider /
+ * adapter / agent loop. The MCP protocol IS the agent loop here; the
+ * spawning client owns the model. This keeps `aiden mcp serve`
+ * startable on a freshly-installed Aiden with zero provider keys.
+ *
+ * Phase-9 approval engine is intentionally NOT wired. The bridge
+ * env-gate (`AIDEN_MCP_ALLOW_DESTRUCTIVE`) is the consent layer when
+ * there's no human at the REPL. The bridge filter blocks mutating
+ * tools by default; opting in means the user accepted server-side
+ * execution risk at config time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_MCP_BUILD = void 0;
+exports.runMcpSubcommand = runMcpSubcommand;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const paths_1 = require("../../../core/v4/paths");
+const toolRegistry_1 = require("../../../core/v4/toolRegistry");
+const skillLoader_1 = require("../../../core/v4/skillLoader");
+const sessionStore_1 = require("../../../core/v4/sessionStore");
+const sessionManager_1 = require("../../../core/v4/sessionManager");
+const memoryManager_1 = require("../../../core/v4/memoryManager");
+const processRegistry_1 = require("../../../core/v4/processRegistry");
+const config_1 = require("../../../core/v4/config");
+const providerFallback_1 = require("../../../core/v4/providerFallback");
+const chatCompletionsAdapter_1 = require("../../../providers/v4/chatCompletionsAdapter");
+const aidenAgent_1 = require("../../../core/v4/aidenAgent");
+const factory_1 = require("../../../core/v4/logger/factory");
+const index_1 = require("../../../tools/v4/index");
+const envSources_1 = require("../envSources");
+const credentialResolver_1 = require("../../../providers/v4/credentialResolver");
+const runtimeResolver_1 = require("../../../providers/v4/runtimeResolver");
+const stdioServer_1 = require("../../../core/v4/mcp/server/stdioServer");
+Object.defineProperty(exports, "AIDEN_MCP_BUILD", { enumerable: true, get: function () { return stdioServer_1.AIDEN_MCP_BUILD; } });
+const diagnostics_1 = require("../../../core/v4/mcp/server/diagnostics");
+const toolBridge_1 = require("../../../core/v4/mcp/server/toolBridge");
+/** Build the slim runtime an MCP server needs. Tools + skills + the
+ *  subsystems they consume — no provider, no agent. */
+async function buildMcpRuntime(opts = {}) {
+    const paths = opts.pathsOverride ?? (0, paths_1.resolveAidenPaths)();
+    await (0, paths_1.ensureAidenDirsExist)(paths);
+    // ── Phase v4.1-mcp.2 — eager .env load ───────────────────────
+    // Stdio MCP clients (Claude Desktop, Cursor) spawn `aiden mcp
+    // serve` with an EMPTY env block by default. Without an explicit
+    // `env: {...}` per-server entry in their config, our spawned
+    // process has no GROQ_API_KEY etc., and any provider-using tool
+    // (subagent_fanout, web_search, fetch_url, …) fails. Load the
+    // well-known .env locations BEFORE the registry is built so tool
+    // factories that read env at registration time see live values.
+    // Fill-only — process.env wins, file values fill gaps.
+    const envReport = (0, envSources_1.loadMcpEnvSources)({
+        aidenHomeEnv: paths.envFile,
+    });
+    // mcp-stdio mode: file sink + stderr only. Crucial: this MUST happen
+    // before any module emits via console.* — but we don't use console in
+    // this module, and mcp-stdio mode + the no-stdout-sink invariant in
+    // factory.ts guarantee the protocol channel stays clean.
+    const { logger } = (0, factory_1.createBootLogger)({ mode: 'mcp-stdio', logsDir: paths.logsDir });
+    // Log the env-load report. NEVER log values — only paths + key
+    // NAMES. The mcp-stdio logger writes to file + stderr (zero stdout
+    // sinks per v4.1-mcp), so spawning clients see this in their MCP
+    // log stream and grep can confirm keys loaded.
+    for (const a of envReport.attempts) {
+        logger.info(`mcp env: ${a.exists ? 'loaded' : 'skipped (missing)'} ${a.path}`, {
+            scope: 'mcp',
+            path: a.path,
+            exists: a.exists,
+            applied: a.appliedKeys.length,
+            keyNames: a.appliedKeys,
+        });
+    }
+    const registry = new toolRegistry_1.ToolRegistry();
+    (0, index_1.registerAllTools)(registry);
+    const skillLoader = new skillLoader_1.SkillLoader(paths);
+    await skillLoader.loadAll().catch(() => undefined);
+    const store = new sessionStore_1.SessionStore(paths.sessionsDb);
+    const sessions = new sessionManager_1.SessionManager(store);
+    const memory = new memoryManager_1.MemoryManager(paths);
+    const processes = new processRegistry_1.ProcessRegistry();
+    const toolContext = {
+        cwd: process.cwd(),
+        paths,
+        sessions,
+        memory,
+        processes,
+        skillLoader,
+        // approvalEngine / ssrfProtection / tirithScanner / memoryGuard
+        // intentionally omitted — see header comment.
+    };
+    // ── Phase v4.1-subagent.2 — wire real subagent_fanout factory ────
+    //
+    // Without this, the stub registered by `registerAllTools` (from
+    // `registerReadOnlyTools`) returns "no providers configured" on
+    // every MCP-side call because its `resolveProviders` is `() => []`.
+    // The CLI path replaces the stub inside `buildAgentRuntime`; the
+    // MCP path is a different runtime build, so it needs its own
+    // replacement here.
+    //
+    // Provider resolution mirrors `buildAgentRuntime` but stripped:
+    //   1. Read config.yaml when present; fall back to groq /
+    //      llama-3.3-70b-versatile (the same default the CLI uses).
+    //   2. RuntimeResolver constructs the active adapter.
+    //   3. If providerId is groq/together (chat_completions with
+    //      multi-slot fallback), wrap in FallbackAdapter so subagent
+    //      rotation gets a real list of provider options.
+    //
+    // When credentials are missing, leave the stub in place — the
+    // status command's "provider keys" block tells the user what to
+    // fix. We never throw out of buildMcpRuntime; an unwired stub is
+    // strictly better UX than a crashed MCP server.
+    await wireSubagentFanout({
+        registry,
+        paths,
+        sessionManager: sessions,
+        memoryManager: memory,
+        skillLoader,
+        logger: logger.child('subagent'),
+    });
+    return { paths, registry, skillLoader, toolContext, logger };
+}
+/** Mirror of `buildAgentFallbackSlots` (cli/v4/aidenCLI.ts) inlined
+ *  here to avoid a load-time module cycle between aidenCLI and mcp.ts.
+ *  Wraps the resolver-resolved primary adapter as slot 0 and appends
+ *  the env-var-derived defaults so multi-key Groq fanouts and
+ *  Together failover work without a config-yaml round-trip. */
+function buildMcpFallbackSlots(primary, primaryProviderId, primaryModelId) {
+    const defaults = (0, providerFallback_1.buildDefaultSlots)({
+        adapterFactory: (cfg) => new chatCompletionsAdapter_1.ChatCompletionsAdapter({
+            baseUrl: cfg.baseUrl,
+            apiKey: cfg.apiKey,
+            model: cfg.model,
+            providerName: cfg.providerName,
+        }),
+    });
+    const primarySlot = {
+        id: 'primary',
+        providerId: primaryProviderId,
+        modelId: primaryModelId,
+        keyPresent: true,
+        keyTail: null,
+        build: () => primary,
+    };
+    return [primarySlot, ...defaults];
+}
+/** Resolve adapter + wire `subagent_fanout` into the MCP registry.
+ *  Soft-fails (logs + leaves stub) when credentials are missing. */
+async function wireSubagentFanout(opts) {
+    const config = new config_1.ConfigManager(opts.paths);
+    try {
+        await config.load();
+    }
+    catch {
+        // ENOENT → defaults. Other parse errors are logged but non-fatal.
+        opts.logger.warn('config.yaml load failed; using defaults', { scope: 'mcp' });
+    }
+    const providerId = config.getValue('model.provider', 'groq');
+    const modelId = config.getValue('model.modelId', 'llama-3.3-70b-versatile');
+    const credentialResolver = new credentialResolver_1.CredentialResolver(opts.paths.authJson);
+    const resolver = new runtimeResolver_1.RuntimeResolver(credentialResolver);
+    let adapter;
+    try {
+        adapter = await resolver.resolve({ providerId, modelId, config, paths: opts.paths });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        opts.logger.warn('subagent_fanout NOT wired — provider resolution failed (run `aiden setup` or set keys in .env)', { scope: 'mcp', providerId, modelId, error: msg });
+        return;
+    }
+    // Wrap in FallbackAdapter when the active provider is one of the
+    // chat-completions families with multi-slot fallback support.
+    // Same pattern aidenCLI.ts uses (line ~562); slot construction is
+    // inlined to avoid a module cycle between aidenCLI and mcp.ts.
+    let wrapped = adapter;
+    if (adapter.apiMode === 'chat_completions'
+        && (providerId === 'groq' || providerId === 'together')) {
+        const slots = buildMcpFallbackSlots(adapter, providerId, modelId);
+        const reachable = slots.filter((s) => s.keyPresent);
+        if (reachable.length >= 2) {
+            wrapped = new providerFallback_1.FallbackAdapter({
+                apiMode: 'chat_completions',
+                slots,
+                onRateLimit: (slotId) => opts.logger.info(`slot ${slotId} rate-limited`, { scope: 'mcp' }),
+            });
+        }
+    }
+    const finalAdapter = wrapped;
+    opts.registry.register((0, index_1.makeSubagentFanoutTool)({
+        logger: opts.logger,
+        resolveActiveModel: () => ({ providerId, modelId }),
+        aggregatorAdapter: finalAdapter,
+        resolveProviders: () => {
+            if (finalAdapter instanceof providerFallback_1.FallbackAdapter) {
+                const diag = finalAdapter.getDiagnostics();
+                const live = diag.slots.filter((s) => s.keyPresent);
+                if (live.length > 0) {
+                    return live.map((s) => ({
+                        providerId: s.providerId,
+                        modelId: s.modelId,
+                        label: s.id,
+                    }));
+                }
+            }
+            return [{ providerId, modelId }];
+        },
+        runChild: async (childOpts) => {
+            const childCtx = {
+                cwd: process.cwd(),
+                paths: opts.paths,
+                sessions: opts.sessionManager,
+                memory: opts.memoryManager,
+                skillLoader: opts.skillLoader,
+                // approvalEngine intentionally undefined — N children
+                // contending for one stdin REPL would deadlock under MCP.
+            };
+            // Filter the child tool surface — read-only by default; opt-in
+            // via AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE=1 (mirrors MCP env from
+            // v4.1-mcp). Recursive fanout disallowed (depth=1).
+            const allowDestructive = process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === '1' ||
+                process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === 'true';
+            const childToolNames = [];
+            for (const name of opts.registry.list()) {
+                const h = opts.registry.get(name);
+                if (!h)
+                    continue;
+                if (h.mutates && !allowDestructive)
+                    continue;
+                if (name === 'subagent_fanout')
+                    continue;
+                childToolNames.push(name);
+            }
+            const childExecutor = opts.registry.buildExecutor(childCtx);
+            const childTools = childToolNames
+                .map((n) => opts.registry.get(n)?.schema)
+                .filter((s) => !!s);
+            // Per-child cloned FallbackAdapter — own rate-limit state.
+            const childProvider = finalAdapter instanceof providerFallback_1.FallbackAdapter
+                ? finalAdapter.clone()
+                : finalAdapter;
+            const child = new aidenAgent_1.AidenAgent({
+                provider: childProvider,
+                tools: childTools,
+                toolExecutor: childExecutor,
+                maxTurns: childOpts.maxIterations,
+                providerId: childOpts.provider.providerId,
+                modelId: childOpts.provider.modelId,
+                // No promptBuilder — children get a brief system prompt
+                // (same lesson as v4.1-subagent.1: full SOUL.md makes
+                // trivial fanouts spend 30s+ on verbose self-introductions).
+            });
+            if (childOpts.signal.aborted) {
+                throw new Error('aborted before dispatch');
+            }
+            const roleLine = childOpts.role ? `Role: ${childOpts.role}. ` : '';
+            const childSystemPrompt = `You are one of N parallel subagents. ${roleLine}` +
+                `Answer the user's request concisely. Use available tools when ` +
+                `the answer requires real-world information you don't have memorized.`;
+            const history = [
+                { role: 'system', content: childSystemPrompt },
+                { role: 'user', content: childOpts.prompt },
+            ];
+            const result = await child.runConversation(history);
+            return result.finalContent;
+        },
+    }));
+    opts.logger.info('subagent_fanout: wired (replaces stub) [mcp serve]', {
+        providerId,
+        modelId,
+        fallback: finalAdapter instanceof providerFallback_1.FallbackAdapter ? 'FallbackAdapter' : 'direct',
+    });
+}
+async function runMcpSubcommand(action, opts = {}) {
+    const writeOut = opts.writeOut ?? ((t) => process.stdout.write(t));
+    const writeErr = opts.writeErr ?? ((t) => process.stderr.write(t));
+    switch (action) {
+        case 'serve': {
+            const { registry, skillLoader, toolContext, logger } = await buildMcpRuntime(opts);
+            await (0, stdioServer_1.startStdioMcpServer)({
+                registry,
+                skillLoader,
+                toolContext,
+                logger,
+            });
+            // Block forever — parent closes stdio when the client disconnects,
+            // which tears down the SDK transport and unwinds the process.
+            await new Promise(() => undefined);
+            return 0;
+        }
+        case 'status': {
+            const { registry, skillLoader } = await buildMcpRuntime(opts);
+            const diag = await (0, diagnostics_1.collectMcpDiagnostics)(registry, skillLoader);
+            writeOut(`Aiden MCP server\n`);
+            writeOut(`  build:           ${diag.build}\n`);
+            writeOut(`  tools (total):   ${diag.toolsTotal}\n`);
+            writeOut(`  tools (exposed): ${diag.toolsExposed}\n`);
+            writeOut(`  skills:          ${diag.skillsTotal}\n`);
+            writeOut(`  allowDestructive: ${diag.env.allowDestructive ? 'yes' : 'no'}\n`);
+            writeOut(`  allowlist:       ${diag.env.allowlist
+                ? diag.env.allowlist.join(', ') || '(empty)'
+                : '(unset — all)'}\n`);
+            // Phase v4.1-mcp.2 — provider key presence + source. NEVER log
+            // values; only the source tag (preset / aiden-env / unset).
+            writeOut(`  provider keys:\n`);
+            const keys = (0, envSources_1.describeProviderKeys)();
+            const present = keys.filter((k) => k.present).length;
+            writeOut(`    detected:      ${present}/${keys.length}\n`);
+            for (const k of keys) {
+                const tag = k.present ? '✓' : '✗';
+                // Lower-case the key for display: "GROQ_API_KEY" → "groq".
+                const label = k.key.replace(/_API_KEY$/, '').toLowerCase();
+                const src = k.present
+                    ? (k.source === 'aiden-env' ? '(.env)' : '(preset)')
+                    : '(unset)';
+                writeOut(`    ${tag} ${label.padEnd(12)} ${src}\n`);
+            }
+            return 0;
+        }
+        case 'tools': {
+            const { registry } = await buildMcpRuntime(opts);
+            const env = (0, toolBridge_1.readToolBridgeEnv)();
+            const list = (0, toolBridge_1.buildToolsList)(registry, env);
+            writeOut(`Aiden MCP — exposed tools (${list.length})\n`);
+            for (const tool of list) {
+                const handler = registry.get(tool.name);
+                const cat = handler?.category ?? '?';
+                const set = handler?.toolset ?? '-';
+                writeOut(`  ${tool.name.padEnd(28)}  ${cat.padEnd(8)}  [${set}]\n`);
+            }
+            return 0;
+        }
+        default: {
+            writeErr(`Unknown 'aiden mcp' action: ${action}\n`);
+            writeErr(`Actions: serve | status | tools\n`);
+            return 1;
+        }
+    }
+}

package/dist/cli/v4/commands/setup.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setup = void 0;
+const setupWizard_1 = require("../setupWizard");
+exports.setup = {
+    name: 'setup',
+    description: 'Re-run the setup wizard (configure provider + API key).',
+    category: 'system',
+    icon: '⚙',
+    handler: async (ctx) => {
+        if (!ctx.paths) {
+            ctx.display.printError('Cannot run wizard from this context — no paths available.', 'This is a wiring bug; please report.');
+            return;
+        }
+        const result = await (0, setupWizard_1.runSetupWizard)({
+            paths: ctx.paths,
+            display: ctx.display,
+            force: true,
+        });
+        if (result.status === 'configured' && result.ran) {
+            ctx.display.write('\nProvider configured. ' +
+                'Restart Aiden (`/quit` then re-run `aiden`) to pick up the new provider.\n\n');
+        }
+        else if (result.status === 'skipped') {
+            ctx.display.write('\nStill in explore mode. Run /setup again whenever you\'re ready.\n\n');
+        }
+        else if (result.status === 'exited') {
+            // Wizard explicitly chose to exit — but we're inside a REPL,
+            // so just report and stay in the session.
+            ctx.display.dim('Wizard exited; continuing existing session.');
+        }
+        return;
+    },
+};

package/dist/cli/v4/commands/show.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/show.ts — Tier-3.1 (v4.1-tier3.1)
+ *
+ * `/show <id>` — print a previously compressed paste. Compressed
+ * pastes are echoed in the REPL as `[paste #<id>: <N> lines, <KB>]`
+ * and stored on disk; this command reverses that for the user
+ * (NOT the agent — the agent receives the full original text at
+ * paste time).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.show = void 0;
+const pasteCompression_1 = require("../pasteCompression");
+exports.show = {
+    name: 'show',
+    description: 'Print the original content of a compressed paste (/show <id>).',
+    category: 'system',
+    icon: '>',
+    handler: async (ctx) => {
+        const id = (ctx.args[0] ?? '').trim();
+        if (!id) {
+            ctx.display.warn('Usage: /show <id>  (id from the [paste #<id>: ...] echo)');
+            return {};
+        }
+        const original = await (0, pasteCompression_1.expandPaste)(id);
+        if (original == null) {
+            ctx.display.warn(`No paste with id ${id} found.`);
+            return {};
+        }
+        ctx.display.write('\n');
+        ctx.display.write(original);
+        if (!original.endsWith('\n'))
+            ctx.display.write('\n');
+        ctx.display.write('\n');
+        return {};
+    },
+};

package/dist/cli/v4/commands/skills.js

@@ -1,6 +1,27 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skills = void 0;
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/skills.ts — Phase 14b
+ *
+ * `/skills [list|view <name>|install <id>]` — minimal CLI surface to
+ * Phase 10's SkillLoader + Phase 14a's SkillsHub. Default subcommand: list.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const table_1 = require("../table");
+const candidateStore_1 = require("../../../core/v4/skillMining/candidateStore");
+const paths_1 = require("../../../core/v4/paths");
+const skillSpec_1 = require("../../../core/v4/skillSpec");
 exports.skills = {
     name: 'skills',
     description: 'List, view, or install skills.',
@@ -19,9 +40,12 @@ exports.skills = {
                 return {};
             }
             ctx.display.info(`Installed skills (${skills.length}):`);
-            for (const s of skills) {
-                ctx.display.write(`  • ${s.name.padEnd(24)} ${s.description ?? ''}\n`);
-            }
+            ctx.display.write((0, table_1.renderTable)(skills.map((s) => ({ name: s.name, description: s.description ?? '' })), [
+                { key: 'name', header: 'Name', align: 'left', minWidth: 16 },
+                // Tier-3.1b: drop the legacy `truncate: 60` cap so the
+                // description column flexes to fill available width.
+                { key: 'description', header: 'Description', align: 'left', flex: true },
+            ]));
             return {};
         }
         if (sub === 'view') {
@@ -69,7 +93,148 @@ exports.skills = {
             }
             return {};
         }
-        ctx.display.printError(`Unknown subcommand: ${sub}`, 'Try: /skills list | view <name> | install <id>');
+        // ── Phase v4.1-skill-mining ──────────────────────────────────
+        // /skills review              — list pending mined candidates
+        // /skills view-candidate <id> — preview a candidate's SKILL.md
+        // /skills accept <id>         — promote candidate to live skill
+        // /skills reject <id> [reason]— record rejection (dedup-aware)
+        // /skills propose             — explanation of the mining hook
+        const store = new candidateStore_1.CandidateStore();
+        if (sub === 'review') {
+            const candidates = await store.list();
+            if (candidates.length === 0) {
+                ctx.display.dim('(no pending candidates — mined skills appear here after a successful 3+ tool turn)');
+                return {};
+            }
+            ctx.display.info(`Pending mined candidates (${candidates.length}):`);
+            ctx.display.write((0, table_1.renderTable)(candidates.map((c) => {
+                // Pull the name + 1-line description from the candidate's
+                // own SKILL.md so the table reflects what the user will
+                // accept verbatim.
+                let name = '(unparsed)';
+                let description = '';
+                try {
+                    const parsed = (0, skillSpec_1.parseSkillContent)(c.skillContent);
+                    name = parsed.frontmatter.name ?? name;
+                    description = parsed.frontmatter.description ?? '';
+                }
+                catch { /* fall through to defaults */ }
+                return {
+                    id: c.id.slice(0, 8),
+                    name,
+                    confidence: c.candidateConfidence.toFixed(2),
+                    session: c.sourceSessionId.slice(0, 8),
+                    created: c.createdAt.slice(0, 19).replace('T', ' '),
+                    description,
+                };
+            }), [
+                { key: 'id', header: 'ID', align: 'left' },
+                { key: 'name', header: 'Name', align: 'left' },
+                { key: 'confidence', header: 'Conf', align: 'right' },
+                { key: 'session', header: 'Session', align: 'left' },
+                { key: 'created', header: 'Created', align: 'left' },
+                { key: 'description', header: 'Description', align: 'left', flex: true },
+            ]));
+            ctx.display.dim('Use `/skills view-candidate <id-prefix>` to preview, `/skills accept <id>` to promote, `/skills reject <id> [reason]` to dismiss.');
+            return {};
+        }
+        if (sub === 'view-candidate') {
+            const idPrefix = ctx.args[1];
+            if (!idPrefix) {
+                ctx.display.printError('Usage: /skills view-candidate <id>');
+                return {};
+            }
+            const all = await store.list();
+            const match = all.find((c) => c.id.startsWith(idPrefix));
+            if (!match) {
+                ctx.display.printError(`No candidate matches id prefix '${idPrefix}'.`);
+                return {};
+            }
+            ctx.display.info(`Candidate ${match.id} (confidence ${match.candidateConfidence.toFixed(2)}):`);
+            ctx.display.write('\n');
+            ctx.display.write(match.skillContent);
+            ctx.display.write('\n');
+            return {};
+        }
+        if (sub === 'accept') {
+            const idPrefix = ctx.args[1];
+            if (!idPrefix) {
+                ctx.display.printError('Usage: /skills accept <id>');
+                return {};
+            }
+            const all = await store.list();
+            const match = all.find((c) => c.id.startsWith(idPrefix));
+            if (!match) {
+                ctx.display.printError(`No candidate matches id prefix '${idPrefix}'.`);
+                return {};
+            }
+            let parsed;
+            try {
+                parsed = (0, skillSpec_1.parseSkillContent)(match.skillContent);
+            }
+            catch (err) {
+                ctx.display.printError(`Candidate did not round-trip through the parser: ${err.message}`);
+                return {};
+            }
+            const skillName = parsed.frontmatter.name;
+            if (!skillName) {
+                ctx.display.printError('Candidate missing required `name` frontmatter field.');
+                return {};
+            }
+            const paths = (0, paths_1.resolveAidenPaths)();
+            const targetDir = node_path_1.default.join(paths.skillsDir, skillName);
+            if (!(0, node_fs_1.existsSync)(paths.skillsDir))
+                (0, node_fs_1.mkdirSync)(paths.skillsDir, { recursive: true });
+            if (!(0, node_fs_1.existsSync)(targetDir))
+                (0, node_fs_1.mkdirSync)(targetDir, { recursive: true });
+            const targetFile = node_path_1.default.join(targetDir, 'SKILL.md');
+            try {
+                await node_fs_1.promises.writeFile(targetFile, match.skillContent, 'utf8');
+            }
+            catch (err) {
+                ctx.display.printError(`Failed to write skill: ${err.message}`);
+                return {};
+            }
+            await store.remove(match.id);
+            // Invalidate the loader cache so the new skill is visible
+            // on the next /skills list call without a session restart.
+            try {
+                ctx.skillLoader?.invalidate?.();
+            }
+            catch { /* best-effort */ }
+            ctx.display.success(`Promoted '${skillName}' to ${targetFile}.`);
+            return {};
+        }
+        if (sub === 'reject') {
+            const idPrefix = ctx.args[1];
+            if (!idPrefix) {
+                ctx.display.printError('Usage: /skills reject <id> [reason]');
+                return {};
+            }
+            const reason = ctx.args.slice(2).join(' ').trim() || undefined;
+            const all = await store.list();
+            const match = all.find((c) => c.id.startsWith(idPrefix));
+            if (!match) {
+                ctx.display.printError(`No candidate matches id prefix '${idPrefix}'.`);
+                return {};
+            }
+            await store.recordRejection(match.fingerprint, reason);
+            await store.remove(match.id);
+            ctx.display.success(`Rejected candidate '${match.id.slice(0, 8)}'.` +
+                (reason ? ` Reason recorded: "${reason}"` : ''));
+            return {};
+        }
+        if (sub === 'propose') {
+            // Manual mining fires automatically post-turn via aidenAgent;
+            // this subcommand surfaces what's currently pending so the
+            // user understands the hook without needing to remember
+            // /skills review.
+            const candidates = await store.list();
+            ctx.display.info(`Skill mining is active — successful 3+ tool turns auto-stage candidates.`);
+            ctx.display.dim(`Pending: ${candidates.length}. Run /skills review to inspect.`);
+            return {};
+        }
+        ctx.display.printError(`Unknown subcommand: ${sub}`, 'Try: /skills list | view <name> | install <id> | review | view-candidate <id> | accept <id> | reject <id> [reason] | propose');
         return {};
     },
 };