knodin 0.8.5 → 0.8.7

package/README.md

@@ -1,5 +1,11 @@
 # knodin
 
+For an approval-gated, evidence-first way to declare a multi-repository system, use the sanitized [assistant prompt](docs/prompts/declare-multi-repository-system.md).
+
+`knodin init` installs focused `knodin-*` assistant skills for detected Codex,
+Claude, and Gemini clients. Use `knodin skills list|install|remove|doctor` to
+inspect or manage them explicitly; CLI-only scope installs none.
+
 <img src="https://cdn.jsdelivr.net/npm/knodin@latest/docs/assets/knodin-favicon.svg" alt="knodin caret-beak logo" width="96" height="96">
 
 > Local code intelligence that remembers how your code connects—and shows what

package/dist/bin/cli.js

@@ -46,7 +46,9 @@ import { runRepositoryInitializationProcess } from "../src/repository-init-proce
 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 { 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";
@@ -422,10 +424,16 @@ function formatStatusHuman(result) {
         `${result.freshness.workingTree.pendingPaths ?? "unknown"} pending path(s).\n` +
         `Last successful refresh: ${result.freshness.lastSuccessfulRefresh ?? "never"}.\n` +
         `Freshness mechanism: ${result.freshnessMechanism.strategy}; watcher ${result.freshnessMechanism.watcher}${result.freshnessMechanism.diagnostic ? ` (${result.freshnessMechanism.diagnostic})` : ""}.\n`;
-    if (result.status === "healthy")
-        return `Graph content is healthy: ${coverage} (knodin ${result.version}; ${result.verification.mode}).\n${freshnessLine}${lifecycleLine}${integrationLine}`;
+    if (result.status === "healthy") {
+        const auditNote = result.verification.mode === "persisted-audit"
+            ? ` Cached deep-audit evidence from ${result.verification.auditVerifiedAt ?? "an earlier run"}; freshness probed ${result.verification.verifiedAt ?? "now"}. Run \`knodin status --deep\` for an exact current audit.`
+            : "";
+        return `Graph content is healthy: ${coverage} (knodin ${result.version}; ${result.verification.mode}).${auditNote}\n${freshnessLine}${lifecycleLine}${integrationLine}`;
+    }
     if (result.status === "stale")
-        return `Graph content is intact but evidence is stale (${coverage}).\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
+        return `Graph content is intact but evidence is stale (${coverage}).${result.verification.mode === "persisted-audit"
+            ? ` Cached deep-audit evidence is from ${result.verification.auditVerifiedAt ?? "an earlier run"}; freshness was probed ${result.verification.verifiedAt ?? "now"}. Run \`knodin status --deep\` for an exact current audit.`
+            : ""}\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
     const outstanding = result.missing.files.length + result.missing.records.length;
     const firstIssue = result.missing.files[0] ?? result.missing.records[0];
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
@@ -637,7 +645,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
@@ -648,7 +655,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)
@@ -799,7 +806,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))
@@ -807,7 +813,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) : {}));
             }
@@ -904,7 +910,6 @@ async function main() {
         }
         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,
@@ -921,7 +926,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`);
@@ -1622,13 +1627,119 @@ 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));
@@ -1667,12 +1778,49 @@ 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 "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;
+            }
+            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 [kind, first, second] = rest;
             let event;
@@ -1864,7 +2012,7 @@ async function main() {
         case "status": {
             const snapshot = async () => ({
                 ...attachLifecycleHealth(repo, await engine.status(repo, {
-                    audit: rest.includes("--deep") ? "deep" : "cached",
+                    audit: rest.includes("--deep") ? "deep" : "adaptive",
                 })),
                 integration: inspectRepositoryIntegrationStatus(repo),
                 update: trustedUpdateStatus({

package/dist/src/cli-model.js

@@ -295,8 +295,38 @@ function createCliProgram(capture = () => { }) {
     for (const action of ["show", "validate", "query"]) {
         const command = leaf(system, `${action} <system-id>`, `${action} one configured system`, capture);
         if (action === "query")
-            command.option("--allow-partial", "return healthy components");
+            command
+                .option("--require-complete", "fail unless every declared repository is available")
+                .option("--allow-partial", "compatibility alias; partial results are now the default");
     }
+    leaf(system, "link <system-id> <repos...>", "declare repositories as one system", capture)
+        .option("--scope <scope>", "personal or team", "personal")
+        .option("--distributed", "write a team fragment to every selected repository")
+        .addOption(option("--repository-id <path=id>", "override a derived repository id", "collect"))
+        .addOption(option("--component <repo=id[:type]>", "override a component id and type", "collect"))
+        .option("--init-missing", "initialize repositories that do not yet have knodin lifecycle state")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "relate <system-id>", "add an explicit evidenced relationship", capture)
+        .requiredOption("--type <type>", "relationship type")
+        .requiredOption("--from <component>", "source component")
+        .requiredOption("--to <component>", "target component")
+        .requiredOption("--evidence <repo:path:line>", "checked-in relationship evidence")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "unlink <system-id> [repos...]", "remove repositories or a whole system", capture).option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "unrelate <system-id>", "remove an explicit relationship", capture)
+        .requiredOption("--type <type>", "relationship type")
+        .requiredOption("--from <component>", "source component")
+        .requiredOption("--to <component>", "target component")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "import <path>", "register an existing system manifest", capture)
+        .option("--scope <scope>", "personal or team", "personal")
+        .option("--dry-run", "preview exact files and semantic changes");
+    const skills = program.command("skills").description("manage packaged knodin assistant skills");
+    for (const action of ["list", "install", "remove", "doctor"])
+        leaf(skills, action, `${action} knodin assistant skills`, capture)
+            .option("--scope <scope>", "personal, team, or cli-only")
+            .addOption(option("--client <client>", "codex, claude, or gemini", "collect"))
+            .option("--dry-run", "preview skill changes without writing");
     const update = program
         .command("update")
         .description("inspect or apply threshold-signed updates")