kibi-cursor 0.3.1 → 0.5.1

package/dist/hook-state-storage.js

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const stateFileName = "hook-state.json";
+const lockFileName = "hook-state.lock";
+export const maxDirtyPaths = 50;
+export const maxGuidedPaths = 100;
+export const maxKbMutationTools = 20;
+const lockRetryCount = 100;
+const lockRetryDelayMs = 5;
+const staleLockAgeMs = 30_000;
+function statePath(pluginData) {
+    return path.join(pluginData, stateFileName);
+}
+function lockPath(pluginData) {
+    return path.join(pluginData, lockFileName);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function normalizePath(dirtyPath) {
+    return dirtyPath.trim().replaceAll("\\", "/");
+}
+function sleepSync(milliseconds) {
+    const buffer = new SharedArrayBuffer(4);
+    const view = new Int32Array(buffer);
+    Atomics.wait(view, 0, 0, milliseconds);
+}
+function uniqueTempPath(pluginData) {
+    return path.join(pluginData, `${stateFileName}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+}
+export function mergeStringPaths(existingPaths, nextPaths) {
+    const merged = [...existingPaths, ...nextPaths]
+        .map(normalizePath)
+        .filter((dirtyPath) => dirtyPath.length > 0);
+    return [...new Set(merged)].slice(-maxGuidedPaths);
+}
+export function emptyHookState() {
+    return {
+        mcpState: "unknown",
+        dirtyPaths: [],
+        guidedReadPaths: [],
+        guidedWritePaths: [],
+        kbMutationTools: [],
+        kbCheckRun: false,
+        impactCheckRun: false,
+        impactCheckedPaths: [],
+    };
+}
+function acquireLock(pluginData) {
+    const targetLockPath = lockPath(pluginData);
+    for (let attempt = 0; attempt < lockRetryCount; attempt++) {
+        try {
+            return fs.openSync(targetLockPath, "wx");
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "EEXIST") {
+                if (removeStaleLock(targetLockPath)) {
+                    continue;
+                }
+                sleepSync(lockRetryDelayMs);
+                continue;
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function removeStaleLock(targetLockPath) {
+    let stats;
+    try {
+        stats = fs.statSync(targetLockPath);
+    }
+    catch {
+        return false;
+    }
+    if (Date.now() - stats.mtimeMs < staleLockAgeMs) {
+        return false;
+    }
+    try {
+        fs.unlinkSync(targetLockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseLock(pluginData, fileDescriptor) {
+    try {
+        fs.closeSync(fileDescriptor);
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+    }
+    try {
+        fs.unlinkSync(lockPath(pluginData));
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+    }
+}
+function coerceHookState(value) {
+    if (!isRecord(value)) {
+        return emptyHookState();
+    }
+    const strings = (candidate, normalize) => Array.isArray(candidate)
+        ? candidate
+            .filter((entry) => typeof entry === "string")
+            .map(normalize)
+            .filter((entry) => entry.length > 0)
+        : [];
+    const dirtyPaths = strings(value.dirtyPaths, normalizePath);
+    const guidedReadPaths = strings(value.guidedReadPaths, normalizePath);
+    const guidedWritePaths = strings(value.guidedWritePaths, normalizePath);
+    const kbMutationTools = strings(value.kbMutationTools, (entry) => entry.trim());
+    const impactCheckedPaths = strings(value.impactCheckedPaths, normalizePath);
+    return {
+        mcpState: value.mcpState === "observed" ? "observed" : "unknown",
+        dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
+        guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
+        guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
+        kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
+        kbCheckRun: value.kbCheckRun === true,
+        impactCheckRun: value.impactCheckRun === true,
+        impactCheckedPaths: [...new Set(impactCheckedPaths)].slice(-maxGuidedPaths),
+    };
+}
+export function resolveStateDir(pluginData, conversationId) {
+    if (pluginData) {
+        return pluginData;
+    }
+    if (!conversationId) {
+        return undefined;
+    }
+    return path.join(os.tmpdir(), "kibi-cursor-hook-state", conversationId.replaceAll(/[^a-zA-Z0-9._-]/g, "_"));
+}
+export function loadHookState(stateDir) {
+    if (!stateDir) {
+        return emptyHookState();
+    }
+    try {
+        return coerceHookState(JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
+    }
+    catch {
+        return emptyHookState();
+    }
+}
+export function saveHookState(stateDir, state) {
+    if (!stateDir) {
+        return;
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const boundedState = coerceHookState(state);
+    const tempPath = uniqueTempPath(stateDir);
+    fs.writeFileSync(tempPath, `${JSON.stringify(boundedState)}\n`);
+    fs.renameSync(tempPath, statePath(stateDir));
+}
+export function updateHookState(stateDir, updater) {
+    const initialState = loadHookState(stateDir);
+    if (!stateDir) {
+        return updater(initialState);
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const lockFileDescriptor = acquireLock(stateDir);
+    if (lockFileDescriptor === undefined) {
+        return updater(initialState);
+    }
+    try {
+        const lockedState = loadHookState(stateDir);
+        const nextState = updater(lockedState);
+        saveHookState(stateDir, nextState);
+        return nextState;
+    }
+    catch {
+        return updater(initialState);
+    }
+    finally {
+        releaseLock(stateDir, lockFileDescriptor);
+    }
+}

package/dist/hook-state.d.ts

@@ -1,4 +1,7 @@
+import type { McpState } from "./kb-mcp-tools.js";
+export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
 export type HookState = {
+    mcpState: McpState;
     dirtyPaths: string[];
     guidedReadPaths: string[];
     guidedWritePaths: string[];
@@ -7,10 +10,6 @@ export type HookState = {
     impactCheckRun: boolean;
     impactCheckedPaths: string[];
 };
-export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
-export declare function loadHookState(stateDir: string | undefined): HookState;
-export declare function saveHookState(stateDir: string | undefined, state: HookState): void;
-export declare function updateHookState(stateDir: string | undefined, updater: (state: HookState) => HookState): HookState;
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
 export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
 export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;

package/dist/hook-state.js

@@ -1,206 +1,5 @@
-// implements REQ-cursor-kibi-plugin-v1
-import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-const stateFileName = "hook-state.json";
-const lockFileName = "hook-state.lock";
-const maxDirtyPaths = 50;
-const maxGuidedPaths = 100;
-const lockRetryCount = 100;
-const lockRetryDelayMs = 5;
-const staleLockAgeMs = 30_000;
-function statePath(pluginData) {
-    return path.join(pluginData, stateFileName);
-}
-function lockPath(pluginData) {
-    return path.join(pluginData, lockFileName);
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizePath(dirtyPath) {
-    return dirtyPath.trim().replaceAll("\\", "/");
-}
-function sleepSync(milliseconds) {
-    const buffer = new SharedArrayBuffer(4);
-    const view = new Int32Array(buffer);
-    Atomics.wait(view, 0, 0, milliseconds);
-}
-function uniqueTempPath(pluginData) {
-    return path.join(pluginData, `${stateFileName}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
-}
-function mergeStringPaths(existingPaths, nextPaths) {
-    const merged = [...existingPaths, ...nextPaths]
-        .map(normalizePath)
-        .filter((dirtyPath) => dirtyPath.length > 0);
-    return [...new Set(merged)].slice(-maxGuidedPaths);
-}
-const maxKbMutationTools = 20;
-function emptyHookState() {
-    return {
-        dirtyPaths: [],
-        guidedReadPaths: [],
-        guidedWritePaths: [],
-        kbMutationTools: [],
-        kbCheckRun: false,
-        impactCheckRun: false,
-        impactCheckedPaths: [],
-    };
-}
-function acquireLock(pluginData) {
-    const targetLockPath = lockPath(pluginData);
-    for (let attempt = 0; attempt < lockRetryCount; attempt++) {
-        try {
-            return fs.openSync(targetLockPath, "wx");
-        }
-        catch (error) {
-            if (error instanceof Error &&
-                "code" in error &&
-                error.code === "EEXIST") {
-                if (removeStaleLock(targetLockPath)) {
-                    continue;
-                }
-                sleepSync(lockRetryDelayMs);
-                continue;
-            }
-            return undefined;
-        }
-    }
-    return undefined;
-}
-function removeStaleLock(targetLockPath) {
-    let stats;
-    try {
-        stats = fs.statSync(targetLockPath);
-    }
-    catch {
-        return false;
-    }
-    if (Date.now() - stats.mtimeMs < staleLockAgeMs) {
-        return false;
-    }
-    try {
-        fs.unlinkSync(targetLockPath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function releaseLock(pluginData, fileDescriptor) {
-    try {
-        fs.closeSync(fileDescriptor);
-    }
-    catch {
-        // Ignore close failures; unlink still gives future hook runs a chance.
-    }
-    try {
-        fs.unlinkSync(lockPath(pluginData));
-    }
-    catch {
-        // A missing lock file is safe: bounded retries prevent permanent blocking.
-    }
-}
-function coerceHookState(value) {
-    if (!isRecord(value)) {
-        return emptyHookState();
-    }
-    const dirtyPaths = Array.isArray(value.dirtyPaths)
-        ? value.dirtyPaths
-            .filter((dirtyPath) => typeof dirtyPath === "string")
-            .map(normalizePath)
-            .filter((dirtyPath) => dirtyPath.length > 0)
-        : [];
-    const guidedReadPaths = Array.isArray(value.guidedReadPaths)
-        ? value.guidedReadPaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    const guidedWritePaths = Array.isArray(value.guidedWritePaths)
-        ? value.guidedWritePaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    const kbMutationTools = Array.isArray(value.kbMutationTools)
-        ? value.kbMutationTools
-            .filter((entry) => typeof entry === "string")
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0)
-        : [];
-    const kbCheckRun = value.kbCheckRun === true;
-    const impactCheckRun = value.impactCheckRun === true;
-    const impactCheckedPaths = Array.isArray(value.impactCheckedPaths)
-        ? value.impactCheckedPaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    return {
-        dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
-        guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
-        guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
-        kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
-        kbCheckRun,
-        impactCheckRun,
-        impactCheckedPaths: [...new Set(impactCheckedPaths)].slice(-maxGuidedPaths),
-    };
-}
-export function resolveStateDir(pluginData, conversationId) {
-    if (pluginData) {
-        return pluginData;
-    }
-    if (!conversationId) {
-        return undefined;
-    }
-    return path.join(os.tmpdir(), "kibi-cursor-hook-state", conversationId.replaceAll(/[^a-zA-Z0-9._-]/g, "_"));
-}
-export function loadHookState(stateDir) {
-    if (!stateDir) {
-        return emptyHookState();
-    }
-    try {
-        return coerceHookState(JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
-    }
-    catch {
-        return emptyHookState();
-    }
-}
-export function saveHookState(stateDir, state) {
-    if (!stateDir) {
-        return;
-    }
-    fs.mkdirSync(stateDir, { recursive: true });
-    const boundedState = coerceHookState(state);
-    const tempPath = uniqueTempPath(stateDir);
-    fs.writeFileSync(tempPath, `${JSON.stringify(boundedState)}\n`);
-    fs.renameSync(tempPath, statePath(stateDir));
-}
-export function updateHookState(stateDir, updater) {
-    const initialState = loadHookState(stateDir);
-    if (!stateDir) {
-        return updater(initialState);
-    }
-    fs.mkdirSync(stateDir, { recursive: true });
-    const lockFileDescriptor = acquireLock(stateDir);
-    if (lockFileDescriptor === undefined) {
-        return updater(initialState);
-    }
-    try {
-        const lockedState = loadHookState(stateDir);
-        const nextState = updater(lockedState);
-        saveHookState(stateDir, nextState);
-        return nextState;
-    }
-    catch {
-        return updater(initialState);
-    }
-    finally {
-        releaseLock(stateDir, lockFileDescriptor);
-    }
-}
+import { emptyHookState, loadHookState, maxDirtyPaths, maxKbMutationTools, mergeStringPaths, normalizePath, updateHookState, } from "./hook-state-storage.js";
+export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
 export function addDirtyPaths(stateDir, dirtyPaths) {
     return updateHookState(stateDir, (state) => ({
         ...state,
@@ -236,9 +35,10 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
         return loadHookState(stateDir);
     }
     return updateHookState(stateDir, (state) => {
+        const observedState = { ...state, mcpState: "observed" };
         if (normalized === "kb_check") {
             return {
-                ...state,
+                ...observedState,
                 kbCheckRun: true,
                 impactCheckRun: state.impactCheckRun || options.impactCheckRun === true,
                 impactCheckedPaths: options.impactCheckRun === true
@@ -248,13 +48,13 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
         }
         if (normalized === "kb_upsert" || normalized === "kb_delete") {
             return {
-                ...state,
+                ...observedState,
                 kbMutationTools: mergeStringPaths(state.kbMutationTools, [
                     normalized,
                 ]).slice(-maxKbMutationTools),
             };
         }
-        return state;
+        return observedState;
     });
 }
 export function clearSessionHookState(stateDir) {

package/dist/kb-mcp-tools.d.ts

@@ -3,5 +3,8 @@ export type KbMcpToolCall = {
     impactCheckRun: boolean;
     sourceFiles: string[];
 };
+export type McpState = "observed" | "unknown";
+export type KibiInterface = "mcp" | "cli" | "setup";
+export declare function resolveKibiInterface(mcpState: McpState, workspaceTrusted: boolean): KibiInterface;
 export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
 export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -39,6 +39,12 @@ function readRecord(record, keys) {
     }
     return undefined;
 }
+export function resolveKibiInterface(mcpState, workspaceTrusted) {
+    if (mcpState === "observed") {
+        return "mcp";
+    }
+    return workspaceTrusted ? "cli" : "setup";
+}
 export function extractKbMcpToolCall(toolName, toolInput) {
     const directToolName = toolName?.trim();
     let normalizedToolName = directToolName?.startsWith("kb_")

package/dist/messages.d.ts

@@ -1,6 +1,8 @@
 import type { HookState } from "./hook-state.js";
-export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
-export declare const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+import { type McpState } from "./kb-mcp-tools.js";
+export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools or a trusted project-local CLI JSON route with --input (peer surfaces) to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools or trusted project-local CLI JSON routes with --input (peer surfaces). Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare function interfaceAdvisory(mcpState: McpState, workspaceTrusted: boolean): string | undefined;
 export declare function stopFollowupMessage(state: HookState): string | undefined;
 /** @deprecated Use stopFollowupMessage */
 export declare function freshnessReminder(dirtyPaths: readonly string[]): string;

package/dist/messages.js

@@ -1,6 +1,18 @@
+import { resolveKibiInterface } from "./kb-mcp-tools.js";
 import { isKbFreshnessRelevantPath, isSourceImpactRelevantPath, } from "./path-policy.js";
-export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
-export const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools or a trusted project-local CLI JSON route with --input (peer surfaces) to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools or trusted project-local CLI JSON routes with --input (peer surfaces). Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export function interfaceAdvisory(mcpState, workspaceTrusted) {
+    const selectedInterface = resolveKibiInterface(mcpState, workspaceTrusted);
+    switch (selectedInterface) {
+        case "mcp":
+            return undefined;
+        case "cli":
+            return "Kibi MCP has not been observed in this session. In this explicitly trusted workspace, the project-local CLI is an advisory fallback: use npx --no-install kibi or bunx --no-install kibi. Do not use global or installing runners.";
+        case "setup":
+            return "Kibi MCP has not been observed in this session and workspace trust is unknown. Do not probe or execute a CLI fallback; ask the operator to enable MCP or explicitly approve the trusted project-local CLI workflow.";
+    }
+}
 export function stopFollowupMessage(state) {
     if (state.kbMutationTools.length > 0) {
         const tools = [...new Set(state.kbMutationTools)];

package/dist/rules/kibi-workflow.mdc

@@ -1,9 +1,9 @@
 ---
-description: Kibi MCP discovery-first workflow and KB mutation discipline
+description: Kibi capability-based discovery-first workflow and KB mutation discipline
 alwaysApply: true
 ---
 
-Use Kibi via MCP tools only. Do not manually read or edit `.kb/` files.
+Use Kibi via MCP tools when available, or via CLI JSON routes when MCP is unavailable. If MCP tools are visible, use MCP. If MCP availability is unknown and a trusted project-local CLI is available, use `kibi <route> --input <file|->`. If neither interface is available, stop and tell the operator. Do not infer MCP availability from config file existence. Do not read or edit `.kb/` files directly.
 
 Discovery workflow:
 - Start with `kb_search` for broad discovery.
@@ -13,7 +13,7 @@ Discovery workflow:
 Mutation workflow:
 - Query before mutate.
 - Create relationship endpoints before linking.
-- Use `kb_upsert` sequentially, then `kb_check`.
+- Use `kb_upsert` sequentially. Run `kb_check` before completion.
 - Use `kb_delete` only for intentional removals with dependency awareness.
 
 Completion must state KB freshness outcome: updated, no-impact with rationale, or deferred/failed.

package/dist/skills/.canon-hash.json

@@ -0,0 +1,12 @@
+{
+  "init-kibi/SKILL.md": "4e936774cd31cf366e9e17452e9030fdaeabab345bce5ee163656e0fe5dc73d7",
+  "kibi-freshness/SKILL.md": "68345a514233503f8f78d53e7d602d8a5fc566e1ec118388c7393716c9f7490d",
+  "kibi-traceability/SKILL.md": "a621553397c1f8813f05fd9552fc30a5e8ed118442e019add35804de7d43a0b1",
+  "kibi-usage/SKILL.md": "292359ad032496abf3a4a68bf97ca79ac875e7b7a208be4b83c34e4b8860d76a",
+  "kibi-usage/resources/fact-lanes.md": "98979dbb35eb0c0f8d7053635fcab2f4a178793a9ce57ca6eab64136de9ef022",
+  "kibi-usage/resources/logic-ir.md": "de6b6833d3c9c628405fa0e0d3c1eb3349a23c2e71fee79d05e27658120123f1",
+  "kibi-usage/resources/operation-access.md": "a5ec895aa9b2f30140b2b72baf444843d32dd99e92d6e10be4279d84f5ea799b",
+  "kibi-usage/resources/relationship-directions.md": "aecbde048bb84e210318e4aca98e07f8370168c640c3a9d65696d2195c8598ec",
+  "kibi-usage/resources/ui-requirements.md": "b7c31ab1affa3ab25ae5242d8fd8c4d546532d1cafc65d84088375317c1682cc",
+  "kibi-usage/resources/workflows.md": "aa86766b06745c22346c2bd7076930b9dab03f2bd829a373f6377af84075c995"
+}

package/dist/skills/init-kibi/SKILL.md

@@ -1,23 +1,62 @@
 ---
+id: init-kibi
 name: init-kibi
 description: Bootstrap and model knowledge safely using approved Kibi MCP initialization and mutation workflow.
+version: 1.0.0
+kibiCompatibility: "*"
+tags:
+  - kibi
+  - mcp
+  - bootstrap
+  - agent-guidance
 ---
-
 ## Goal
 
-Set up or refresh Kibi knowledge for the current branch without manual filesystem edits.
+Set up or refresh Kibi knowledge for the current branch through approved Kibi interfaces only. Maintain source-file traceability for every repository-backed claim, and require explicit operator approval before any mutation.
+
+## Interface Selection
+
+1. If approved Kibi MCP tools are visible, use the MCP route.
+2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback: `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
+3. If neither approved MCP tools nor the project-local CLI are available, stop and tell the operator to enable or install Kibi for this workspace.
+4. Never use a global fallback, an installing runner, or any route outside the approved Kibi interface.
+
+Use `kibi-usage/resources/operation-access.md` for the exact operation-to-route mapping. The CLI preview route accepts the same JSON object as `kb_autopilot_generate`:
+
+```bash
+echo '{"maxCandidates":25,"minConfidence":0.8}' | npx --no-install kibi autopilot-generate --input -
+```
 
-## MCP workflow
+## Capability Workflow
 
-- Run `kb_autopilot_generate` for suggested initial facts and claims.
-- Show the generated preview and get explicit approval before writes.
-- Use `kb_upsert` for reviewed entity creation or updates.
-- If cleanup is needed, use `kb_delete` only after checking dependencies.
-- Finish with `kb_check` to validate the branch snapshot.
+- Generate a read-only bootstrap preview with `kb_autopilot_generate`, or the dedicated CLI route `autopilot-generate --input`.
+- Show the generated preview and obtain explicit approval before writes.
+- Apply reviewed entity creation or updates with `kb_upsert`, or `upsert --input`.
+- If cleanup is needed, use `kb_delete`, or `delete --input`, only after checking dependencies and obtaining approval for the specific removal.
+- Finish with `kb_check`, or `check --input`, to validate the branch snapshot.
 
 ## Guidance
 
-- Keep mutation requests explicit and small.
-- Use source-linked entities where possible so future `kb_query` lookups can verify context.
-- Do not edit `.kb/**` files directly; all changes go through MCP calls.
+- Keep mutation requests explicit, small, and sequential.
+- Prefer source-linked entities so future `kb_query` lookups can verify repository context against source files.
+- Preserve traceability by linking facts, claims, scenarios, and tests to concrete project files whenever repository evidence supports it.
+- Do not read or edit files inside `.kb` directly; all changes go through the selected Kibi interface.
 - Ask at most four bounded context questions, and only when repository evidence is insufficient.
+- Stop at the documented operator repair boundary if the setup appears partial, inconsistent, or unsupported by the approved interface.
+
+## Public Training Trajectories
+
+- `init-kibi-bootstrap-analysis-train-1`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
+- `init-kibi-bootstrap-analysis-train-2`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
+- `init-kibi-bounded-context-questions-train-1`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
+- `init-kibi-bounded-context-questions-train-2`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
+- `init-kibi-approval-sequential-writes-train-1`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
+- `init-kibi-approval-sequential-writes-train-2`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
+- `init-kibi-repair-escalation-train-1`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
+- `init-kibi-repair-escalation-train-2`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
+
+## Training Data
+
+```json
+[{"taskId":"init-kibi-bootstrap-analysis-train-1","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bootstrap-analysis-train-2","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-1","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-2","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-1","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-2","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-1","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-2","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 2; use only the public Kibi MCP surface."}]
+```