knodin 0.8.6 → 0.8.7

package/dist/src/tools/knodin-tools.js

@@ -35,7 +35,8 @@ import { discoverRepositories, initializeRepositories, inventoryRepository, sear
 import { applyResponseBudget } from "../response-budget.js";
 import { loadSharedIndexConfig } from "../shared-index/config.js";
 import { EMPTY_OVERLAY, readSharedIndexProvenance, readSharedRestoreAttempt, } from "../shared-index/provenance.js";
-import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, RELATIONSHIP_TYPES, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../system-management.js";
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
@@ -317,7 +318,7 @@ function buildDocumentedKnodinTools() {
                     },
                     from: {
                         type: "string",
-                        description: "review: older ref of an explicit revision pair; requires `to`.",
+                        description: "review: older ref of a revision pair; system relate/unrelate: source component id.",
                     },
                     toRevision: {
                         type: "string",
@@ -494,9 +495,30 @@ function buildDocumentedKnodinTools() {
                     },
                     systemAction: {
                         type: "string",
-                        enum: ["list", "show", "validate", "query"],
-                        description: "system only: list configured systems, show or validate one system, or query its declared relationships.",
+                        enum: [
+                            "list",
+                            "show",
+                            "validate",
+                            "query",
+                            "link",
+                            "relate",
+                            "unlink",
+                            "unrelate",
+                            "import",
+                        ],
                     },
+                    planDigest: {
+                        type: "string",
+                        description: "system writes: digest returned by the approved preview",
+                    },
+                    repositories: { type: "array", items: { type: "string" } },
+                    scope: { type: "string", enum: ["personal", "team"] },
+                    distributed: { type: "boolean" },
+                    repositoryIds: { type: "object", additionalProperties: { type: "string" } },
+                    components: { type: "object", additionalProperties: { type: "object" } },
+                    evidence: { type: "string" },
+                    relationshipType: { type: "string", enum: RELATIONSHIP_TYPES },
+                    requireComplete: { type: "boolean" },
                     repositoryAction: {
                         type: "string",
                         enum: ["discover", "init", "status", "doctor", "search"],
@@ -731,14 +753,14 @@ const RESPONSE_DEFAULTS = {
     "diagnostics:archive": { bytes: 65_536, tokens: 16_384, items: 100 },
     default: { bytes: 65_536, tokens: 16_384, items: 100 },
 };
-async function populateRepositoryDiagnoses(records, repositories, configRoot) {
+async function populateRepositoryDiagnoses(records, repositories) {
     repositories.length = 0;
     for (const record of records) {
         try {
             const graph = attachLifecycleHealth(record.path, await engine.status(record.path, { audit: "deep" }));
             const repository = await inventoryRepository(record, {
                 status: async () => graph,
-                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(configRoot), target),
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
             });
             repositories.push({
                 ...repository,
@@ -770,12 +792,11 @@ async function handleRepositoriesOperation(options) {
     };
     const inventory = async () => {
         const discovery = await discoverRepositories(discoveryRoots, discoveryOptions);
-        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
         const repositories = [];
         for (const record of discovery.repositories) {
             repositories.push(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),
             }));
         }
         return { discovery, repositories };
@@ -792,7 +813,7 @@ async function handleRepositoriesOperation(options) {
             worktrees: linkedWorktrees,
             dryRun,
             manifestPath,
-            indexMode: (target) => indexModeForPath(systemConfig, target),
+            indexMode: (target) => indexModeForPath(loadSystemConfiguration(target), target),
             isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command, memoryLimitBytes }),
         });
         const { repositories } = await inventory();
@@ -801,7 +822,6 @@ async function handleRepositoriesOperation(options) {
     if (repositoryAction === "search") {
         if (!query?.trim())
             throw new Error("knodin repositories search requires a non-empty `query`");
-        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
         return searchRepositories(discoveryRoots, query, {
             ...discoveryOptions,
             include,
@@ -817,12 +837,12 @@ async function handleRepositoriesOperation(options) {
                 includeSource: true,
                 federate: false,
             }),
-            systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+            systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
         });
     }
     const { discovery, repositories } = await inventory();
     if (repositoryAction === "doctor")
-        await populateRepositoryDiagnoses(discovery.repositories, repositories, discoveryRoots[0] ?? repo);
+        await populateRepositoryDiagnoses(discovery.repositories, repositories);
     return bounded({
         schemaVersion: 1,
         linkedWorktrees: discoveryOptions.linkedWorktrees,
@@ -833,7 +853,67 @@ async function handleRepositoriesOperation(options) {
     }, `repositories:${repositoryAction}`);
 }
 async function handleSystemOperation(options) {
-    const { systemAction, symbol, repo, allowPartial, bounded } = options;
+    const { systemAction, symbol, repo, bounded } = options;
+    if (["link", "relate", "unlink", "unrelate", "import"].includes(systemAction)) {
+        if (systemAction !== "import" && !symbol)
+            throw new Error(`knodin system ${systemAction} requires \`symbol\``);
+        const systemId = symbol ?? "";
+        let plan;
+        if (systemAction === "import") {
+            if (!options.manifestPath)
+                throw new Error("system import requires manifestPath");
+            plan = planSystemImport({
+                manifestPath: options.manifestPath,
+                scope: options.scope,
+                repoPath: repo,
+            });
+        }
+        else if (systemAction === "link")
+            plan = planSystemLink({
+                systemId,
+                repositories: options.repositories ?? [],
+                scope: options.scope,
+                distributed: options.distributed,
+                repositoryIds: options.repositoryIds,
+                components: options.components,
+            });
+        else if (systemAction === "relate") {
+            if (!options.relationshipType || !options.from || !options.to || !options.evidence)
+                throw new Error("system relate requires relationshipType, from, to, and evidence");
+            plan = planSystemRelate({
+                systemId,
+                type: options.relationshipType,
+                from: options.from,
+                to: options.to,
+                evidence: options.evidence,
+                repoPath: repo,
+            });
+        }
+        else if (systemAction === "unlink")
+            plan = planSystemUnlink({
+                systemId,
+                repositories: options.repositories,
+                repoPath: repo,
+            });
+        else {
+            if (!options.relationshipType || !options.from || !options.to)
+                throw new Error("system unrelate requires relationshipType, from, and to");
+            plan = planSystemUnrelate({
+                systemId,
+                type: options.relationshipType,
+                from: options.from,
+                to: options.to,
+                repoPath: repo,
+            });
+        }
+        if (options.apply === true) {
+            if (!options.planDigest)
+                throw new Error("system writes require planDigest from an approved preview");
+            if (options.planDigest !== plan.planDigest)
+                throw new Error("system plan changed after preview; preview again");
+        }
+        return bounded(options.apply === true ? applySystemPlan(plan) : plan, `system:${systemAction}`);
+    }
     const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
     if (systemAction === "list") {
         return bounded({
@@ -859,7 +939,7 @@ async function handleSystemOperation(options) {
     const validation = await validateSystemHealth(config, symbol, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
     if (systemAction === "validate")
         return bounded({ systemId: symbol, ...validation }, "system:validate");
-    return bounded(queryConfiguredSystem(config, symbol, allowPartial === true, validation), "system:query");
+    return bounded(queryConfiguredSystem(config, symbol, options.requireComplete === true, validation), "system:query");
 }
 async function handlePullRequestsOperation(options) {
     const { repo, engine, limit, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, } = options;
@@ -1296,7 +1376,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
 async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
-    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
     const repo = repoPath ?? process.cwd();
     const selector = {
         identity: expandCompactIdentity(identity),
@@ -1519,6 +1599,19 @@ async function dispatchKnodinTool(args) {
                 symbol,
                 repo,
                 allowPartial,
+                apply,
+                repositories,
+                scope,
+                distributed,
+                repositoryIds,
+                components,
+                relationshipType,
+                from,
+                to,
+                evidence,
+                requireComplete,
+                manifestPath,
+                planDigest,
                 bounded,
             });
         }

package/docs/CLI.md

@@ -35,6 +35,13 @@ knodin repos search --help
 knodin update --help
 ```
 
+`repos search` resolves configured system memberships independently for every
+discovered checkout. Symbol search remains primary. When it returns no matches,
+or a multi-term query has only weak single-term symbol coverage, Knodin performs
+a bounded lexical fallback over tracked YAML and shell files. These results are
+labeled `matchType: "tracked-text"` with file and line evidence; they are not
+parsed symbols or a claim of general YAML/shell semantic support.
+
 Help uses the active terminal width. Non-TTY output uses a deterministic
 100-column layout so snapshots, documentation, and automation do not depend on
 the caller's environment. Narrow and wide formatting are covered by pure tests;

package/docs/SYSTEMS-AND-RELATIONSHIPS.md

@@ -1,17 +1,29 @@
 # Systems and relationships
 
+To have an assistant inspect existing checkouts, propose evidenced membership and relationships, preview exact changes, wait for approval, and validate the result, start from the sanitized [multi-repository system prompt](prompts/declare-multi-repository-system.md).
+
 A system is an explicitly configured set of cooperating components. Components
 may represent APIs, resources, repositories, or artifacts. Unrelated
 repositories remain separate even when they share a parent directory or match
 the same search query.
 
-Team configuration belongs in repository-root `knodin.yaml` and contains stable
-identities without local absolute paths. Personal checkout paths belong in:
+Personal system declarations live outside source checkouts at
+`$XDG_CONFIG_HOME/knodin/systems/<system-id>.yaml`; checkout paths remain in:
 
 ```text
 $XDG_CONFIG_HOME/knodin/repositories.yaml
 ```
 
+Knodin also reads the legacy nested layout
+`$XDG_CONFIG_HOME/knodin/systems/<name>/knodin.yaml`. From either layout, a
+mapped participating checkout discovers its systems without pointing `--repo`
+at the external configuration directory.
+
+Team declarations belong in repository-root `knodin.yaml` and contain stable
+identities without absolute paths. Central configuration writes one selected
+manifest. `--distributed` repeats stable membership/components in each selected
+manifest and keeps an evidenced relationship in its evidence repository.
+
 Commands:
 
 ```bash
@@ -19,10 +31,18 @@ knodin system list
 knodin system show <system-id>
 knodin system validate <system-id>
 knodin system query <system-id>
+knodin system link <system-id> <repo...> --dry-run
+knodin system relate <system-id> --type <type> --from <component> --to <component> \
+  --evidence <repo-id>:<path>:<line> --dry-run
+knodin system unlink <system-id> [repo-id...]
+knodin system unrelate <system-id> --type <type> --from <component> --to <component>
+knodin system import <manifest>
 ```
 
 The existing single MCP gateway exposes the same `system` operation with
-`systemAction=list|show|validate|query`.
+inspection and lifecycle actions. Link/relate/unlink/unrelate preview by
+default; MCP writes require `apply: true` and return exact planned files and
+semantic changes.
 
 Relationship types include dependency, API provider/consumer, deployment,
 provisioning, output/config/path references, events, images, and provenance.
@@ -40,6 +60,7 @@ source.
 discarded. Loaded entries are labeled `legacy-federation` until migrated to
 stable identities.
 
-System validation fails closed for unresolved repository identities or missing
-required checkouts. Partial query behavior must be explicit and name every
-omitted component; absent evidence is never reported as zero.
+System queries return prominently labeled partial results by default and name
+every unavailable repository and omitted relationship. Use
+`--require-complete` when a partial answer must fail. `--allow-partial` remains
+accepted as a compatibility option; absent evidence is never reported as zero.

package/docs/prompts/declare-multi-repository-system.md

@@ -0,0 +1,18 @@
+# Declare a knodin multi-repository system
+
+Use this command-first prompt after replacing every `<PLACEHOLDER>`; do not include credentials, tokens, private URLs, or source text that is not safe to share with the assistant.
+
+```text
+Help me declare the knodin system <SYSTEM_ID> from these existing checkouts:
+
+- <REPOSITORY_PATH_1>
+- <REPOSITORY_PATH_2>
+
+Use <personal|team> scope. For team scope, use <central|distributed> configuration.
+
+First run knodin status in each checkout and inspect existing manifests. Propose membership and explicit directional relationships; do not infer membership from sibling paths or repository names and do not invent relationships. Provide an evidence table with repository ID, component IDs/types, relationship type, from, to, repository-relative evidence path, and line.
+
+Preview the exact knodin system link and system relate changes. Show every planned file and semantic change, then wait for my approval. After approval, apply the same plan and run system validate and system query. Clearly label unavailable repositories and omitted evidence.
+
+For personal scope, record each checkout's branch, tracked files, tracked .gitignore content, and git status before applying; confirm they remain unchanged afterward.
+```

package/docs/releases/0.8.7.md

@@ -0,0 +1,27 @@
+# knodin 0.8.7
+
+This release makes explicit multi-repository systems practical from ordinary
+participating checkouts and ships task-focused assistant workflows.
+
+- `knodin system link`, `relate`, `unlink`, `unrelate`, and `import` replace
+  manual multi-repository YAML plumbing for personal, central-team, and
+  distributed-team systems. Mutations preview exact files and semantic changes;
+  MCP writes are bound to the approved preview.
+- Personal systems auto-discover from mapped checkouts, including legacy nested
+  manifests. System queries label unavailable repositories and omitted evidence,
+  while `--require-complete` preserves fail-closed workflows.
+- Portfolio search resolves system memberships per checkout and uses a bounded,
+  explicitly labeled committed-text fallback for weak YAML/shell workflow
+  queries. It does not claim general YAML or shell semantic parsing.
+- Seven packaged `knodin-*` skills cover exploration, debugging, impact,
+  refactoring, review, systems, and lifecycle work for Codex, Claude, and Gemini.
+  Managed installation preserves user-authored and modified skills.
+- Personal initialization remains byte-clean in source checkouts, including
+  tracked `.gitignore` content and branch/worktree state.
+- Release builds now mark `dist/bin/launcher.js` executable before packing. This
+  fixes Homebrew installations where `knodin` was linked correctly but shells
+  ignored the non-executable launcher or returned `permission denied`.
+
+Knodin still treats ordinary YAML and shell files as lexical fallback evidence,
+not native graph inputs. Partial system results remain useful only within their
+reported unavailable repositories and omitted relationships.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.8.6",
+	"version": "0.8.7",
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -21,6 +21,8 @@
 	},
 	"files": [
 		"dist",
+		"skills",
+		"docs/prompts/declare-multi-repository-system.md",
 		"docs/DEAD-CODE-AND-IMPACT.md",
 		"docs/DOCTOR-AND-UPDATES.md",
 		"docs/DIAGNOSTICS.md",
@@ -63,6 +65,7 @@
 		"docs/releases/0.8.4.md",
 		"docs/releases/0.8.5.md",
 		"docs/releases/0.8.6.md",
+		"docs/releases/0.8.7.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",
@@ -87,7 +90,7 @@
 		"start": "tsx src/server.ts",
 		"cli": "tsx bin/cli.ts",
 		"clean": "node scripts/clean-dist.mjs",
-		"build": "npm run clean && tsc -p tsconfig.build.json",
+		"build": "npm run clean && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
 		"typecheck": "tsc --noEmit",
 		"test": "tsx scripts/run-vitest-shards.ts",
 		"test:handles": "vitest run --reporter=verbose --reporter=hanging-process",

package/skills/knodin-debug/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: knodin-debug
+description: Debug a local software failure by tracing source-evidenced flows, callers, dependencies, and recent changes with knodin. Use for reproducible defects, exceptions, failing tests, regressions, or root-cause investigation.
+---
+
+# Debug with knodin
+
+1. Establish the failure and call MCP `context` with the symptom; fall back to `knodin context` if MCP is unavailable.
+2. Use `explain`, `query` with callers/callees/data-flow patterns, and bounded source to test one cause at a time.
+3. Use `review` against the relevant base when a regression is plausible.
+4. Separate observed evidence from hypotheses; name stale, missing, or ambiguous graph coverage.
+5. Load `knodin docs diagnostics` or command help only for parameters not already known.

package/skills/knodin-debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Debug"
+  short_description: "Use knodin for debug workflows"
+  default_prompt: "Use $knodin-debug to help with this codebase task."

package/skills/knodin-explore/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: knodin-explore
+description: Explore an unfamiliar local codebase with source-evidenced architecture, symbols, flows, and bounded context. Use for codebase orientation, locating implementations, understanding architecture, or answering “where/how does this work?” questions.
+---
+
+# Explore with knodin
+
+1. Call the connected knodin MCP `context` operation with the task before broad traversal. If MCP is unavailable, run `knodin context <task>`.
+2. Use MCP `search`, `map`, or `explain` for the smallest source-evidenced answer. Fall back to the matching CLI commands.
+3. Report file paths, symbol identities, evidence, freshness, and known bounds. Treat ambiguity or stale evidence explicitly.
+4. Load `knodin docs query-patterns` or command help only when detailed parameters are needed.

package/skills/knodin-explore/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Explore"
+  short_description: "Use knodin for explore workflows"
+  default_prompt: "Use $knodin-explore to help with this codebase task."

package/skills/knodin-impact/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: knodin-impact
+description: Assess upstream and downstream change impact with source-evidenced dependencies and known bounds. Use before meaningful edits, API changes, deletions, migrations, or when asked what could break.
+---
+
+# Assess impact with knodin
+
+1. Resolve the symbol unambiguously with MCP `explain` or `search`.
+2. Call MCP `query` with the `impact` pattern and explicit direction; fall back to `knodin query impact <symbol> --direction upstream|downstream|both`.
+3. Report direct and transitive consumers, tests, cross-repository evidence, freshness, and omissions.
+4. Never turn heuristic or partial evidence into a safe-deletion claim. Load `knodin docs dead-code` only when deletion policy details are needed.

package/skills/knodin-impact/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Impact"
+  short_description: "Use knodin for impact workflows"
+  default_prompt: "Use $knodin-impact to help with this codebase task."

package/skills/knodin-lifecycle/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: knodin-lifecycle
+description: Inspect and repair knodin graph freshness, lifecycle hooks, agent integration, installation, and packaged skills. Use for init, status, repair, doctor, stale graphs, broken hooks, configuration, or assistant-skill installation.
+---
+
+# Maintain knodin
+
+1. Run MCP status; fall back to `knodin status`. Do not rely on graph evidence when repair is required.
+2. Follow reported repair steps: use `knodin repair` for graph damage and `knodin init` for displaced lifecycle hooks.
+3. Use `knodin skills doctor` for managed-skill health and `knodin skills install|remove` for explicit lifecycle changes.
+4. Preserve scope: personal locations remain outside repositories; team locations are commit-ready; CLI-only installs no skills.
+5. Report freshness, hook state, supported clients, managed/unmanaged collisions, and remaining limitations. Load `knodin docs doctor` only for detailed procedures.

package/skills/knodin-lifecycle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Lifecycle"
+  short_description: "Use knodin for lifecycle workflows"
+  default_prompt: "Use $knodin-lifecycle to help with this codebase task."

package/skills/knodin-refactor/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: knodin-refactor
+description: Plan and verify source-evidenced local refactors and renames with ambiguity-safe symbol identity and impact checks. Use for renaming, moving, extracting, deleting, or restructuring code.
+---
+
+# Refactor with knodin
+
+1. Resolve the exact symbol using MCP `explain`; fall back to `knodin explain` and stop on ambiguity.
+2. Run MCP `query` with `impact` upstream before editing and summarize material risk.
+3. Prefer knodin’s rename operation for supported renames; preview before apply. Otherwise edit only source-confirmed references.
+4. Reindex changed files when immediate freshness is required, then rerun impact and relevant tests.
+5. Load `knodin docs rename-safety` or command help only for detailed parameters.

package/skills/knodin-refactor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Refactor"
+  short_description: "Use knodin for refactor workflows"
+  default_prompt: "Use $knodin-refactor to help with this codebase task."

package/skills/knodin-review/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: knodin-review
+description: Review a local change or branch using source-evidenced risk, dependency, history, and bounded context. Use for code review, pre-PR review, regression risk, or checking whether a diff missed consumers.
+---
+
+# Review with knodin
+
+1. Call MCP `review` with an explicit diff scope and base; fall back to `knodin review --scope compare <base>`.
+2. Inspect high-risk changed symbols with `explain` and upstream `impact` queries.
+3. Verify findings in source and report severity, evidence paths, affected consumers, and coverage bounds.
+4. Do not equate a zero-match or partial result with safety. Load `knodin docs git-history` only when deeper history parameters are needed.

package/skills/knodin-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Review"
+  short_description: "Use knodin for review workflows"
+  default_prompt: "Use $knodin-review to help with this codebase task."

package/skills/knodin-systems/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: knodin-systems
+description: Discover, declare, validate, and query explicit multi-repository knodin systems and evidenced relationships. Use for linking repositories, cross-repository architecture, partial checkouts, system manifests, or relationship maintenance.
+---
+
+# Manage systems with knodin
+
+1. Inspect candidate repositories; never infer membership from sibling paths or names.
+2. Propose repository/component IDs and explicit directional relationships in an evidence table with repository-relative path and line.
+3. Preview with MCP `system` actions (omit `apply` or set it false); fall back to CLI `system link|relate --dry-run`. Show exact files and semantic changes.
+4. Wait for approval before applying. For MCP writes set `apply: true`; for CLI rerun without `--dry-run`.
+5. Validate the system and label unavailable members and omitted evidence. Use `--require-complete` only when completeness is mandatory.
+6. For personal scope, confirm branches, tracked files, and working-tree state in every checkout remain unchanged.
+7. Load `knodin docs systems` or command help only when detailed options are needed.

package/skills/knodin-systems/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Knodin Systems"
+  short_description: "Use knodin for systems workflows"
+  default_prompt: "Use $knodin-systems to help with this codebase task."