knodin 0.8.6 → 0.9.0

package/dist/bin/cli.js

@@ -14,12 +14,12 @@
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { canUseSessionContextCache, parseClaudeHookPayload, readSessionContextCache, recordClaudeLifecycleEvent, renderSessionContext, SESSION_CONTEXT_BUDGET_LINE, sessionStartHookOutput, writeSessionContextCache, } from "../src/agent-events.js";
 import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentHooks, } from "../src/agent-hooks.js";
 import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
 import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.js";
+import { formatBackupHuman, installBackupRetention, listBackups, maybeRunOpportunisticRetention, pruneBackups, removeBackupRetention, retentionDoctor, retentionStatus, runInstalledRetention, } from "../src/backup-retention.js";
 import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, planIndex, resolveCliRuntimeCommand, resolveRepo, } from "../src/cli-args.js";
 import { helpCommandPath, parseCliInvocation, renderCliHelp } from "../src/cli-model.js";
 import { buildKnodinContext } from "../src/context.js";
@@ -33,20 +33,26 @@ import { diagnoseFailure, } from "../src/failure-diagnosis.js";
 import { gitExecutable } from "../src/git-executable.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
 import { createIndexActivityReporter } from "../src/index-activity.js";
-import { detectTrackedTeamIntegration, InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, } from "../src/init.js";
+import { InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, } from "../src/init.js";
 import { createInitProgressRenderer } from "../src/init-progress.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../src/lifecycle-health.js";
+import { acknowledgeUpdateFailure, queryOwnerAvailability, readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, setManualPin, unpinUpdate, updateAttention, writeManagerUpdateState, } from "../src/manager-update.js";
 import { addMirror, listMirrors, refreshMirror, removeMirror } from "../src/mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../src/output-compression.js";
 import { clearTelemetry, exportTelemetry, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../src/output-telemetry.js";
 import { auditPullRequests } from "../src/pr-triage.js";
 import { deliverProgressiveEvidence, } from "../src/progressive-evidence.js";
+import { acquireRepairLease } from "../src/repair-lease.js";
 import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, resolveRepairProgressMode, serializeRepairJsonlRecord, } from "../src/repair-progress.js";
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
 import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, repositorySignalInspectionLimit, searchRepositories, withRepositorySignals, } from "../src/repository-management.js";
 import { applyResponseBudget } from "../src/response-budget.js";
 import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
+import { inspectKnodinSkills, installKnodinSkills, KNODIN_SKILLS, removeKnodinSkills, } from "../src/skill-management.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
+import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../src/system-management.js";
+import { coordinationStatus } from "../src/update-coordination.js";
+import { certifyAutomaticUpdates, executeManagerUpdate, recoverInterruptedUpdate, } from "../src/update-executor.js";
 import { applyTrustedUpdate, checkTrustedUpdate, claimScheduledUpdateCheck, detectUpdateInstallMethod, explainTrustedUpdate, releaseScheduledUpdateCheck, rollbackTrustedUpdate, trustedUpdateStatus, } from "../src/update-policy.js";
 import { KNODIN_VERSION } from "../src/version.js";
 import { writeVisualization, } from "../src/visualization.js";
@@ -63,44 +69,6 @@ function explicitScope(args) {
     const equals = args.find((argument) => argument.startsWith("--scope="));
     return equals ? parseInitScope(equals.slice("--scope=".length)) : null;
 }
-async function chooseInitScope(args, repo) {
-    const selected = explicitScope(args);
-    if (selected)
-        return selected;
-    if (detectTrackedTeamIntegration(repo)) {
-        process.stderr.write("[init:scope] Detected tracked knodin team integration; preserving team scope\n");
-        return "team";
-    }
-    if (!process.stdin.isTTY || !process.stderr.isTTY)
-        return "personal";
-    const prompt = readline.createInterface({
-        input: process.stdin,
-        output: process.stderr,
-    });
-    try {
-        const answer = await prompt.question([
-            "How should knodin integrate with coding agents?",
-            "  1. Personal (recommended) — all detected agents; Git stays clean",
-            "  2. Team — create commit-ready shared configuration",
-            "  3. CLI-only — agents will not discover or invoke knodin automatically",
-            "Select [1]: ",
-        ].join("\n"));
-        if (!answer.trim() || answer.trim() === "1")
-            return "personal";
-        if (answer.trim() === "2")
-            return "team";
-        if (answer.trim() === "3") {
-            const confirmation = await prompt.question("CLI-only requires manual knodin commands. Continue? [y/N] ");
-            if (!/^y(?:es)?$/i.test(confirmation.trim()))
-                throw new Error("knodin init: CLI-only selection cancelled");
-            return "cli-only";
-        }
-        return parseInitScope(answer.trim());
-    }
-    finally {
-        prompt.close();
-    }
-}
 function integrationAgents(repo) {
     const previous = readRepositoryIntegrationConfig(repo)?.agents ?? [];
     const repositoryDetected = inspectRepositoryIntegrationStatus(repo)?.agents ?? [];
@@ -149,7 +117,7 @@ function formatConfigureHuman(result) {
     const externalOutcomeLines = result.paths.externalConfigurationOutcomes
         .map(({ system, state }) => `\nExternal configuration outcome: ${system} ${state} (external mutation not locally observable)`)
         .join("");
-    return `${result.message}\nAgent integration: ${result.paths.scope} — ${configured}${failures}${filesystemMutationLines}${externalOutcomeLines}\nGraph initialization: unchanged\nLifecycle refresh: ${refresh}\nNext: ${result.nextAction}\n`;
+    return `${result.message}\nAgent integration: ${result.paths.scope} — ${configured}${failures}${filesystemMutationLines}${externalOutcomeLines}\nGraph initialization: refreshed and verified\nLifecycle refresh: ${refresh}\nNext: ${result.nextAction}\n`;
 }
 function formatRepairHuman(result) {
     const coverage = result.after.coverage;
@@ -643,7 +611,6 @@ async function main() {
         process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
         const engine = createEngine({ watcher: "disabled" });
         try {
-            const systemConfig = loadSystemConfiguration(repository);
             const summary = await initializeRepositories([repository], {
                 // A portfolio worker owns exactly one already-discovered worktree.
                 // Do not recursively initialize nested repositories inside the same
@@ -654,7 +621,7 @@ async function main() {
                 index: (target) => engine.index(target),
                 status: (target) => engine.status(target),
                 agents: detectSupportedAgents(),
-                indexMode: (target) => indexModeForPath(systemConfig, target),
+                indexMode: (target) => indexModeForPath(loadSystemConfiguration(target), target),
             });
             const result = summary.results.find(({ repository: target }) => target === repository);
             if (!result)
@@ -704,6 +671,26 @@ async function main() {
     // `--json` is a shared output flag. Repair owns its richer --json/--jsonl
     // parser; all other commands receive their original arguments minus it.
     const rest = cmd === "repair" ? rawRest : rawRest.filter((argument) => argument !== "--json");
+    let recoveryJournal = readUpdateJournal();
+    const recoverySafeStates = new Set(["planned", "candidate-verified", "rollback-verified"]);
+    if (recoveryJournal && !recoverySafeStates.has(recoveryJournal.state) && cmd !== "doctor") {
+        const recovery = await recoverInterruptedUpdate({ runtimeCommand, env: process.env });
+        recoveryJournal = readUpdateJournal();
+        if (recovery?.status === "terminal-unhealthy" && cmd !== "update") {
+            throw new Error(`knodin update recovery is terminal-unhealthy: ${recovery.reason ?? "candidate and rollback verification failed"}`);
+        }
+    }
+    if (recoveryJournal &&
+        !recoverySafeStates.has(recoveryJournal.state) &&
+        cmd !== "update" &&
+        cmd !== "doctor") {
+        throw new Error(`knodin is in unverified update state ${recoveryJournal.state}; run \`knodin update status\` for recovery guidance`);
+    }
+    if (!jsonOutput && cmd !== "update") {
+        const attention = updateAttention(readManagerUpdateState());
+        if (attention)
+            process.stderr.write(`${attention}\n`);
+    }
     const selector = {
         identity: selectorValue("--identity"),
         file: selectorValue("--file"),
@@ -805,7 +792,6 @@ async function main() {
                 linkedWorktrees: plan.linkedWorktrees,
             });
             const engine = createEngine({ watcher: "disabled" });
-            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const repositories = [];
             const discoveryRecords = plan.signals
                 ? discovery.repositories.slice(0, repositorySignalInspectionLimit(plan))
@@ -813,7 +799,7 @@ async function main() {
             for (const record of discoveryRecords) {
                 const inventory = await inventoryRepository(record, {
                     status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
-                    systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                    systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
                 });
                 repositories.push(withRepositorySignals(inventory, plan.signals, plan.signals ? await detectRepositorySignals(record.path) : {}));
             }
@@ -826,7 +812,11 @@ async function main() {
                 repositories,
             };
             const boundedOutput = plan.signals
-                ? applyResponseBudget(output, "repositories:discover", { bytes: plan.byteBudget, tokens: plan.tokenBudget, items: plan.itemBudget }, { bytes: 65_536, tokens: 16_384, items: 100 })
+                ? applyResponseBudget(output, "repositories:discover", {
+                    bytes: plan.byteBudget,
+                    tokens: plan.tokenBudget,
+                    items: plan.itemBudget,
+                }, { bytes: 65_536, tokens: 16_384, items: 100 })
                 : output;
             process.stdout.write(`${JSON.stringify(boundedOutput, null, plan.json ? 0 : 2)}\n`);
             process.exitCode = discovery.issues.length > 0 ? 1 : 0;
@@ -903,14 +893,18 @@ async function main() {
                 }));
             }
             await engine.close();
-            const output = { schemaVersion: 1, command: "init", ...summary, repositories };
+            const output = {
+                schemaVersion: 1,
+                command: "init",
+                ...summary,
+                repositories,
+            };
             process.stdout.write(plan.json ? `${JSON.stringify(output)}\n` : formatRepositoryHuman(summary));
             process.exitCode = summary.exitCode;
             return;
         }
         if (plan.command === "search") {
             const engine = createEngine({ watcher: "disabled" });
-            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const output = await searchRepositories(plan.roots, plan.query ?? "", {
                 depth: plan.depth,
                 linkedWorktrees: plan.linkedWorktrees,
@@ -927,7 +921,7 @@ async function main() {
                     includeSource: true,
                     federate: false,
                 }),
-                systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
             });
             await engine.close();
             process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
@@ -1011,13 +1005,15 @@ async function main() {
     if (cmd === "update") {
         if (repoFlag !== undefined)
             throw new Error("knodin update does not accept --repo");
-        const [action, ...unsupported] = rest;
-        if (!action || !["status", "check", "explain", "apply", "rollback"].includes(action)) {
-            throw new Error("knodin update requires status, check, explain, apply, or rollback");
-        }
-        if (unsupported.length > 0)
-            throw new Error(`knodin update ${action}: unknown argument ${unsupported[0]}`);
+        const [action, ...actionArguments] = rest;
+        if (!action)
+            throw new Error("knodin update requires an action");
         const method = detectUpdateInstallMethod(runtimeCommand);
+        const owner = resolveManagerOwnership({
+            runtimeCommand,
+            executablePath: runtimeCommand.at(-1),
+            env: process.env,
+        });
         const runManager = async (argv) => {
             const [executable, ...arguments_] = argv;
             if (!executable)
@@ -1053,8 +1049,16 @@ async function main() {
             healthCheck,
         };
         let output;
-        if (action === "status")
-            output = trustedUpdateStatus(options);
+        if (action === "status") {
+            output = {
+                ...trustedUpdateStatus(options),
+                owner,
+                managerState: readManagerUpdateState(),
+                journal: readUpdateJournal(),
+                coordination: coordinationStatus(),
+                attention: updateAttention(readManagerUpdateState()),
+            };
+        }
         else if (action === "check") {
             try {
                 output = await checkTrustedUpdate(options);
@@ -1068,11 +1072,178 @@ async function main() {
             output = explainTrustedUpdate(options);
         else if (action === "apply")
             output = await applyTrustedUpdate(options);
-        else
+        else if (action === "rollback")
             output = await rollbackTrustedUpdate(options);
+        else if (action === "available") {
+            output = await queryOwnerAvailability({ installedVersion: KNODIN_VERSION, owner });
+            const availability = output;
+            const state = readManagerUpdateState();
+            if (availability.latestVersion &&
+                state.pin?.kind === "automatic-rollback" &&
+                state.pin.acknowledgedFailedVersion === state.pin.failedVersion &&
+                availability.latestVersion !== state.pin.failedVersion) {
+                writeManagerUpdateState({
+                    ...state,
+                    lastAvailableVersion: availability.latestVersion,
+                    pin: { ...state.pin, newerAvailableVersion: availability.latestVersion },
+                });
+            }
+        }
+        else if (action === "upgrade") {
+            const apply = actionArguments.includes("--apply");
+            const explicitVersion = actionArguments.find((argument) => argument !== "--apply");
+            let targetVersion = explicitVersion;
+            if (!targetVersion) {
+                const availability = await queryOwnerAvailability({
+                    installedVersion: KNODIN_VERSION,
+                    owner,
+                });
+                if (!availability.latestVersion)
+                    output = availability;
+                else
+                    targetVersion = availability.latestVersion;
+            }
+            if (targetVersion)
+                output = await executeManagerUpdate({
+                    currentVersion: KNODIN_VERSION,
+                    targetVersion,
+                    runtimeCommand,
+                    env: process.env,
+                    apply,
+                });
+        }
+        else if (action === "pin") {
+            const apply = actionArguments.includes("--apply");
+            const version = actionArguments.find((argument) => argument !== "--apply");
+            if (!version)
+                throw new Error("knodin update pin requires a version");
+            output = apply
+                ? await executeManagerUpdate({
+                    currentVersion: KNODIN_VERSION,
+                    targetVersion: version,
+                    runtimeCommand,
+                    env: process.env,
+                    apply: true,
+                    pinKind: "manual",
+                })
+                : setManualPin(version);
+        }
+        else if (action === "unpin")
+            output = unpinUpdate();
+        else if (action === "acknowledge")
+            output = acknowledgeUpdateFailure();
+        else if (action === "auto") {
+            const subaction = actionArguments[0];
+            if (!subaction || !["status", "enable", "disable", "run"].includes(subaction))
+                throw new Error("knodin update auto requires status, enable, disable, or run");
+            const state = readManagerUpdateState();
+            if (subaction === "status")
+                output = state;
+            else if (subaction === "disable") {
+                output = { ...state, autoEnabled: false };
+                writeManagerUpdateState(output);
+            }
+            else if (subaction === "enable") {
+                if (state.platformAutoEligible) {
+                    output = { ...state, autoEnabled: true };
+                    writeManagerUpdateState(output);
+                }
+                else
+                    output = await certifyAutomaticUpdates({
+                        currentVersion: KNODIN_VERSION,
+                        runtimeCommand,
+                        env: process.env,
+                    });
+            }
+            else if (!state.autoEnabled || !state.platformAutoEligible) {
+                output = { ...state, status: "disabled" };
+            }
+            else {
+                const availability = await queryOwnerAvailability({
+                    installedVersion: KNODIN_VERSION,
+                    owner,
+                });
+                output =
+                    availability.status === "available" &&
+                        availability.autoEligible &&
+                        availability.latestVersion
+                        ? await executeManagerUpdate({
+                            currentVersion: KNODIN_VERSION,
+                            targetVersion: availability.latestVersion,
+                            runtimeCommand,
+                            env: process.env,
+                            apply: true,
+                        })
+                        : availability;
+            }
+        }
+        else
+            throw new Error(`knodin update: unknown action ${action}`);
         process.stdout.write(jsonOutput ? `${JSON.stringify(output)}\n` : formatGenericHuman("update", output));
         return;
     }
+    if (cmd === "backups") {
+        const action = invocation.commandPath[1];
+        const retentionAction = invocation.commandPath[2];
+        const roots = invocation.positionals;
+        const defaultRoots = () => {
+            if (roots.length > 0)
+                return roots;
+            const target = resolveRepo(repoFlag, process.cwd());
+            if (!target.ok)
+                throw new Error(target.error);
+            return [target.repo];
+        };
+        const depth = invocation.options.depth;
+        const retentionDays = invocation.options.retentionDays;
+        const keepNewest = invocation.options.keepNewest;
+        let output;
+        if (action === "list")
+            output = listBackups(defaultRoots(), { depth });
+        else if (action === "prune") {
+            output = pruneBackups(defaultRoots(), {
+                depth,
+                retentionDays,
+                keepNewest,
+                apply: invocation.options.apply === true,
+            });
+        }
+        else if (action === "retention" && retentionAction === "install") {
+            output = installBackupRetention(roots, {
+                depth,
+                retentionDays,
+                keepNewest,
+                schedule: invocation.options.schedule,
+                dryRun: invocation.options.dryRun === true,
+                launcher: runtimeCommand,
+            });
+        }
+        else if (action === "retention" && retentionAction === "status") {
+            output = retentionStatus();
+        }
+        else if (action === "retention" && retentionAction === "doctor") {
+            output = retentionDoctor();
+        }
+        else if (action === "retention" && retentionAction === "remove") {
+            output = removeBackupRetention();
+        }
+        else if (action === "retention" && retentionAction === "run") {
+            output = runInstalledRetention();
+        }
+        else {
+            throw new Error("knodin backups requires list, prune, or retention install|status|doctor|remove");
+        }
+        if (invocation.options.jsonl === true) {
+            const records = output.backups ??
+                output.candidates ?? [output];
+            for (const record of records)
+                process.stdout.write(`${JSON.stringify(record)}\n`);
+        }
+        else {
+            process.stdout.write(jsonOutput ? `${JSON.stringify(output)}\n` : formatBackupHuman("backups", output));
+        }
+        return;
+    }
     if (process.stdout.isTTY &&
         claimScheduledUpdateCheck({
             currentVersion: KNODIN_VERSION,
@@ -1124,6 +1295,14 @@ async function main() {
         process.exit(1);
     }
     const repo = resolved.repo;
+    if (cmd !== "doctor") {
+        try {
+            maybeRunOpportunisticRetention(repo);
+        }
+        catch {
+            // Best-effort cleanup must never make an ordinary command fail.
+        }
+    }
     if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))
         return;
     if (cmd === "doctor") {
@@ -1247,7 +1426,10 @@ async function main() {
             const input = positionals[0] === "create" ? (positionals[1] ?? "-") : (positionals[0] ?? "-");
             compressionResult =
                 input === "-"
-                    ? compressOutput(repo, { ...request, text: await readBoundedStdin(maxInputBytes) })
+                    ? compressOutput(repo, {
+                        ...request,
+                        text: await readBoundedStdin(maxInputBytes),
+                    })
                     : compressOutputFile(repo, input, request);
         }
         if (action === "diagnose" &&
@@ -1326,7 +1508,10 @@ async function main() {
                     if (existing.state !== "configured")
                         throw new Error("knodin shared configure --disable requires a valid existing configuration");
                     writeSharedIndexConfig(repo, { ...existing.config, enabled: false });
-                    result = { state: "configured", config: { ...existing.config, enabled: false } };
+                    result = {
+                        state: "configured",
+                        config: { ...existing.config, enabled: false },
+                    };
                     break;
                 }
                 const required = (name) => {
@@ -1361,7 +1546,11 @@ async function main() {
                     },
                 };
                 const target = writeSharedIndexConfig(repo, config);
-                result = { state: "configured", path: target, config: loadSharedIndexConfig(repo) };
+                result = {
+                    state: "configured",
+                    path: target,
+                    config: loadSharedIndexConfig(repo),
+                };
                 break;
             }
             if (action === "publisher-metadata") {
@@ -1395,7 +1584,10 @@ async function main() {
                 if (!bundlePath)
                     throw new Error("knodin shared publisher-finalize requires <bundle>");
                 const bundle = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), bundlePath), "utf8"));
-                const pointer = finalizeSharedPublisherBundle({ config: configuration.config, bundle });
+                const pointer = finalizeSharedPublisherBundle({
+                    config: configuration.config,
+                    bundle,
+                });
                 result = { bundle, pointer: JSON.parse(pointer.toString("utf8")) };
                 break;
             }
@@ -1422,12 +1614,19 @@ async function main() {
                 let credentialProbe = "not-requested";
                 if (invocation.options.probe === true) {
                     if (configuration.state !== "configured" || !configuration.config.enabled) {
-                        credentialProbe = { state: "unavailable", category: "configuration" };
+                        credentialProbe = {
+                            state: "unavailable",
+                            category: "configuration",
+                        };
                     }
                     else {
                         const store = createSharedObjectStore(configuration.config);
                         try {
-                            const current = spawnSync(gitExecutable(), ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).stdout.trim();
+                            const current = spawnSync(gitExecutable(), ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+                                cwd: repo,
+                                encoding: "utf8",
+                                stdio: ["ignore", "pipe", "ignore"],
+                            }).stdout.trim();
                             const branch = configuredBranchCandidates(configuration.config, current || undefined)[0];
                             if (!store || !branch)
                                 throw new SharedIndexError("configuration", "shared-index probe has no configured local branch candidate");
@@ -1628,13 +1827,123 @@ async function main() {
             break;
         }
         case "system": {
-            const allowPartial = rest.includes("--allow-partial");
-            const [action, systemId, ...unsupported] = rest.filter((argument) => argument !== "--allow-partial");
+            const requestedAction = invocation.commandPath[1];
+            if (requestedAction === "link") {
+                const [systemId, ...repositories] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system link requires <system-id>");
+                const overrides = Object.fromEntries((Array.isArray(invocation.options.repositoryId) ? invocation.options.repositoryId : [])
+                    .map(String)
+                    .map((value) => {
+                    const at = value.lastIndexOf("=");
+                    if (at < 1)
+                        throw new Error("--repository-id must be <path>=<id>");
+                    return [value.slice(0, at), value.slice(at + 1)];
+                }));
+                const componentOverrides = Object.fromEntries((Array.isArray(invocation.options.component) ? invocation.options.component : [])
+                    .map(String)
+                    .map((value) => {
+                    const at = value.indexOf("=");
+                    if (at < 1)
+                        throw new Error("--component must be <repo-id>=<component-id>[:type]");
+                    const repositoryId = value.slice(0, at);
+                    const [id, componentType] = value.slice(at + 1).split(":");
+                    if (!id)
+                        throw new Error("--component requires a component id");
+                    if (componentType &&
+                        !["component", "api", "resource", "artifact"].includes(componentType))
+                        throw new Error(`--component: unsupported type ${componentType}`);
+                    return [
+                        repositoryId,
+                        {
+                            id,
+                            type: componentType,
+                        },
+                    ];
+                }));
+                if (invocation.options.initMissing === true && invocation.options.dryRun !== true) {
+                    for (const checkout of repositories.map((value) => path.resolve(repo, value))) {
+                        if (fs.existsSync(path.join(checkout, ".knodin")))
+                            continue;
+                        await initializeRepository(checkout, {
+                            command: runtimeCommand,
+                            index: (target, indexOptions) => engine.index(target, undefined, false, indexOptions),
+                            scope: "personal",
+                            agents: [],
+                        });
+                    }
+                }
+                const plan = planSystemLink({
+                    systemId,
+                    repositories,
+                    scope: invocation.options.scope === "team" ? "team" : "personal",
+                    distributed: invocation.options.distributed === true,
+                    repositoryIds: overrides,
+                    components: componentOverrides,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "relate") {
+                const [systemId] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system relate requires <system-id>");
+                const plan = planSystemRelate({
+                    systemId,
+                    type: String(invocation.options.type),
+                    from: String(invocation.options.from),
+                    to: String(invocation.options.to),
+                    evidence: String(invocation.options.evidence),
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "unlink") {
+                const [systemId, ...repositories] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system unlink requires <system-id>");
+                const plan = planSystemUnlink({
+                    systemId,
+                    repositories,
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "unrelate") {
+                const [systemId] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system unrelate requires <system-id>");
+                const plan = planSystemUnrelate({
+                    systemId,
+                    type: String(invocation.options.type),
+                    from: String(invocation.options.from),
+                    to: String(invocation.options.to),
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "import") {
+                const [manifestPath] = invocation.positionals;
+                if (!manifestPath)
+                    throw new Error("knodin system import requires <path>");
+                const plan = planSystemImport({
+                    manifestPath,
+                    scope: invocation.options.scope === "team" ? "team" : "personal",
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            const requireComplete = rest.includes("--require-complete");
+            const [action, systemId, ...unsupported] = rest.filter((argument) => argument !== "--allow-partial" && argument !== "--require-complete");
             if (!action || !["list", "show", "validate", "query"].includes(action)) {
                 throw new Error("knodin system requires list, show, validate, or query");
             }
-            if (allowPartial && action !== "query")
-                throw new Error(`knodin system ${action}: --allow-partial applies only to query`);
+            if (requireComplete && action !== "query")
+                throw new Error(`knodin system ${action}: --require-complete applies only to query`);
             if (unsupported.length > 0)
                 throw new Error(`knodin system ${action}: unknown argument ${unsupported[0]}`);
             const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
@@ -1673,39 +1982,83 @@ async function main() {
             }
             else {
                 const validation = await validateSystemHealth(config, systemId, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
-                result = queryConfiguredSystem(config, systemId, allowPartial, validation);
+                result = queryConfiguredSystem(config, systemId, requireComplete, validation);
                 if (result.status === "unavailable")
                     process.exitCode = 1;
             }
             break;
         }
-        case "hook-refresh": {
-            const [kind, first, second] = rest;
-            let event;
-            if (kind === "commit")
-                event = { kind };
-            else if (kind === "checkout" && first && second) {
-                event = { kind, before: first, after: second };
-            }
-            else if (kind === "merge" && first && second) {
-                event = { kind, before: first, after: second };
+        case "skills": {
+            const action = invocation.commandPath[1];
+            const requested = Array.isArray(invocation.options.client)
+                ? invocation.options.client.map(String)
+                : [];
+            const supported = new Set(["codex", "claude", "gemini"]);
+            for (const client of requested)
+                if (!supported.has(client))
+                    throw new Error(`knodin skills: unsupported client ${client}`);
+            const clients = (requested.length ? requested : ["codex", "claude", "gemini"]);
+            const scope = typeof invocation.options.scope === "string"
+                ? parseInitScope(invocation.options.scope)
+                : "personal";
+            if (action === "list") {
+                result = { skills: KNODIN_SKILLS, clients, scope };
+                break;
             }
-            else if (kind === "rewrite" && first) {
-                event = { kind, inputPath: first };
+            if (action === "install")
+                result = installKnodinSkills({
+                    repo,
+                    scope,
+                    clients,
+                    dryRun: invocation.options.dryRun === true,
+                });
+            else if (action === "remove")
+                result = removeKnodinSkills({
+                    repo,
+                    scope,
+                    clients,
+                    dryRun: invocation.options.dryRun === true,
+                });
+            else if (action === "doctor")
+                result = inspectKnodinSkills({ repo, scope, clients });
+            else
+                throw new Error("knodin skills requires list, install, remove, or doctor");
+            break;
+        }
+        case "hook-refresh": {
+            const lifecycleLease = acquireRepairLease(repo, "lifecycle-hook");
+            try {
+                const [kind, first, second] = rest;
+                let event;
+                if (kind === "commit")
+                    event = { kind };
+                else if (kind === "checkout" && first && second) {
+                    event = { kind, before: first, after: second };
+                }
+                else if (kind === "merge" && first && second) {
+                    event = { kind, before: first, after: second };
+                }
+                else if (kind === "rewrite" && first) {
+                    event = { kind, inputPath: first };
+                }
+                else {
+                    throw new Error("knodin hook-refresh: invalid lifecycle event");
+                }
+                const shared = await opportunisticSharedRestore();
+                const indexed = shared?.restored
+                    ? []
+                    : await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
+                result = { indexed, ...(shared ? { sharedRestore: shared } : {}) };
             }
-            else {
-                throw new Error("knodin hook-refresh: invalid lifecycle event");
+            finally {
+                lifecycleLease.release();
             }
-            const shared = await opportunisticSharedRestore();
-            const indexed = shared?.restored
-                ? []
-                : await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
-            result = { indexed, ...(shared ? { sharedRestore: shared } : {}) };
             break;
         }
         case "init": {
-            const scope = await chooseInitScope(rawRest, repo);
-            const agents = scope === "team" ? [] : integrationAgents(repo);
+            const requestedScope = explicitScope(rawRest);
+            const scope = requestedScope ?? readRepositoryIntegrationConfig(repo)?.scope ?? "cli-only";
+            const agents = requestedScope && scope !== "team" ? integrationAgents(repo) : [];
             const renderer = createInitRenderer();
             const activity = createIndexActivityReporter(repo);
             activity.start();
@@ -1723,6 +2076,7 @@ async function main() {
                         index: (target, options) => engine.index(target, undefined, false, options),
                         scope,
                         agents,
+                        configureIntegration: requestedScope !== null,
                         onProgress: (event) => {
                             activity.update(event);
                             renderer.onProgress(event);
@@ -1767,16 +2121,17 @@ async function main() {
             const agents = scope === "team" ? [] : integrationAgents(repo);
             const paths = await initializeRepository(repo, {
                 command: runtimeCommand,
-                index: async () => undefined,
+                index: (target, options) => engine.index(target, undefined, false, options),
                 scope,
                 agents,
                 allowTrackedTransition: true,
                 auditConfigurationChanges: true,
+                configureIntegration: true,
             });
             result = {
                 status: "success",
                 message: `knodin agent integration changed to ${scope}.`,
-                graphInitialization: "unchanged",
+                graphInitialization: "refreshed",
                 nextAction: "run `knodin status` and reload the configured client",
                 paths,
             };
@@ -1926,7 +2281,9 @@ async function main() {
             }
             const progressMode = resolveRepairProgressMode(options, process.env, process.stderr.isTTY);
             const renderer = progressMode === "tty"
-                ? createProgressWorkerRenderer("repair-progress-worker", { type: "start" })
+                ? createProgressWorkerRenderer("repair-progress-worker", {
+                    type: "start",
+                })
                 : (() => {
                     const direct = createRepairProgressRenderer({
                         mode: progressMode,
@@ -2367,7 +2724,10 @@ async function main() {
             else if (action === "export")
                 result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "clear")
-                result = { ...clearTelemetry(repo, input), session: clearSessionTelemetry(repo) };
+                result = {
+                    ...clearTelemetry(repo, input),
+                    session: clearSessionTelemetry(repo),
+                };
             else
                 throw new Error("knodin telemetry requires enable, disable, status, report, export, or clear");
             break;
@@ -2439,7 +2799,11 @@ async function main() {
                 result =
                     action === "preview"
                         ? persistDiagnosticsPreview(repo, options)
-                        : collectDiagnostics(repo, { ...options, outputPath: outputOption, previewId });
+                        : collectDiagnostics(repo, {
+                            ...options,
+                            outputPath: outputOption,
+                            previewId,
+                        });
             }
             else {
                 throw new Error("knodin diagnostics requires enable, status, preview, archive, inspect, clear, or disable");