kibi-runtime 1.0.1

package/dist/skill-operations.d.ts

@@ -0,0 +1,69 @@
+import type { OperationResult } from "kibi-cli/operations";
+import type { OperationContext } from "kibi-cli/operations/runtime-types";
+import type { SkillManifest } from "./skill-system/types.js";
+declare function executeSkillsList(_input: Readonly<Record<string, unknown>>, _context: OperationContext): Promise<OperationResult<{
+    readonly skills: readonly SkillManifest[];
+}>>;
+declare function executeSkillsLoad(input: Readonly<Record<string, unknown>>, _context: OperationContext): Promise<OperationResult<{
+    readonly metadata: SkillManifest;
+    readonly body: string;
+    readonly resources: readonly string[];
+    readonly contentHash: string;
+    readonly sourceType: "bundled";
+}>>;
+declare function executeSkillsRead(input: Readonly<Record<string, unknown>>, _context: OperationContext): Promise<OperationResult<{
+    readonly content: string;
+}>>;
+export declare const skillsListSpec: {
+    readonly name: "kb_skills_list";
+    readonly cliName: "skills list";
+    readonly description: "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.";
+    readonly businessInputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+    readonly requiresProlog: false;
+    readonly effects: readonly ["local-read"];
+    readonly execute: typeof executeSkillsList;
+};
+export declare const skillsLoadSpec: {
+    readonly name: "kb_skills_load";
+    readonly cliName: "skills load";
+    readonly description: "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.";
+    readonly businessInputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["id"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly description: "Bundled skill ID to load. Example: 'kibi-usage'.";
+            };
+        };
+    };
+    readonly requiresProlog: false;
+    readonly effects: readonly ["local-read"];
+    readonly execute: typeof executeSkillsLoad;
+};
+export declare const skillsReadSpec: {
+    readonly name: "kb_skills_read";
+    readonly cliName: "skills read";
+    readonly description: "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.";
+    readonly businessInputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["id", "resource"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly description: "Bundled skill ID. Example: 'kibi-usage'.";
+            };
+            readonly resource: {
+                readonly type: "string";
+                readonly description: "Manifest-declared resource path to read. Example: 'resources/workflows.md'.";
+            };
+        };
+    };
+    readonly requiresProlog: false;
+    readonly effects: readonly ["local-read"];
+    readonly execute: typeof executeSkillsRead;
+};
+export {};

package/dist/skill-operations.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { listBundledSkills, loadBundledSkill, readBundledSkillResource, } from "./skills.js";
+function assertNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+}
+async function executeSkillsList(_input, _context) {
+    const skills = listBundledSkills();
+    const ids = skills.map((skill) => skill.id).join(", ") || "none";
+    return {
+        content: [
+            { type: "text", text: `Found ${skills.length} bundled skills: ${ids}` },
+        ],
+        structuredContent: { skills },
+    };
+}
+async function executeSkillsLoad(input, _context) {
+    const id = typeof input.id === "string" ? input.id : "";
+    assertNonEmptyString(id, "id");
+    const bundle = loadBundledSkill(id);
+    const resources = bundle.manifest.resources ?? [];
+    const contentHash = createHash("sha256")
+        .update(bundle.body, "utf8")
+        .digest("hex");
+    const resourceList = resources.length === 0 ? "none" : resources.join(", ");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Loaded bundled skill ${bundle.manifest.id} with ${resources.length} resources: ${resourceList}`,
+            },
+        ],
+        structuredContent: {
+            metadata: bundle.manifest,
+            body: bundle.body,
+            resources,
+            contentHash,
+            sourceType: "bundled",
+        },
+    };
+}
+async function executeSkillsRead(input, _context) {
+    const id = typeof input.id === "string" ? input.id : "";
+    const resource = typeof input.resource === "string" ? input.resource : "";
+    assertNonEmptyString(id, "id");
+    assertNonEmptyString(resource, "resource");
+    return {
+        content: [
+            { type: "text", text: `Read bundled skill resource ${id}/${resource}` },
+        ],
+        structuredContent: {
+            content: readBundledSkillResource(id, resource),
+        },
+    };
+}
+export const skillsListSpec = {
+    name: "kb_skills_list",
+    cliName: "skills list",
+    description: "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.",
+    businessInputSchema: { type: "object", properties: {} },
+    requiresProlog: false,
+    effects: ["local-read"],
+    execute: executeSkillsList,
+};
+export const skillsLoadSpec = {
+    name: "kb_skills_load",
+    cliName: "skills load",
+    description: "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.",
+    businessInputSchema: {
+        type: "object",
+        required: ["id"],
+        properties: {
+            id: {
+                type: "string",
+                description: "Bundled skill ID to load. Example: 'kibi-usage'.",
+            },
+        },
+    },
+    requiresProlog: false,
+    effects: ["local-read"],
+    execute: executeSkillsLoad,
+};
+export const skillsReadSpec = {
+    name: "kb_skills_read",
+    cliName: "skills read",
+    description: "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.",
+    businessInputSchema: {
+        type: "object",
+        required: ["id", "resource"],
+        properties: {
+            id: {
+                type: "string",
+                description: "Bundled skill ID. Example: 'kibi-usage'.",
+            },
+            resource: {
+                type: "string",
+                description: "Manifest-declared resource path to read. Example: 'resources/workflows.md'.",
+            },
+        },
+    },
+    requiresProlog: false,
+    effects: ["local-read"],
+    execute: executeSkillsRead,
+};

package/dist/skill-system/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class SkillNotFoundError extends Error {
+    constructor(id: string);
+}
+export declare class SkillResourceNotFoundError extends Error {
+    constructor(id: string, resourcePath: string);
+}
+export declare class SkillResourceOutOfBoundsError extends Error {
+    constructor(id: string, resourcePath: string);
+}
+export declare class SkillValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+export declare class SkillOversizeError extends Error {
+    readonly maxBytes: number;
+    readonly actualBytes: number;
+    constructor(pathLike: string, maxBytes: number, actualBytes: number);
+}

package/dist/skill-system/errors.js

@@ -0,0 +1,36 @@
+export class SkillNotFoundError extends Error {
+    constructor(id) {
+        super(`Skill not found: ${id}`);
+        this.name = "SkillNotFoundError";
+    }
+}
+export class SkillResourceNotFoundError extends Error {
+    constructor(id, resourcePath) {
+        super(`Skill resource not found: ${id}/${resourcePath}`);
+        this.name = "SkillResourceNotFoundError";
+    }
+}
+export class SkillResourceOutOfBoundsError extends Error {
+    constructor(id, resourcePath) {
+        super(`Skill resource escapes bundle root: ${id}/${resourcePath}`);
+        this.name = "SkillResourceOutOfBoundsError";
+    }
+}
+export class SkillValidationError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = "SkillValidationError";
+        this.field = field;
+    }
+}
+export class SkillOversizeError extends Error {
+    maxBytes;
+    actualBytes;
+    constructor(pathLike, maxBytes, actualBytes) {
+        super(`Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`);
+        this.name = "SkillOversizeError";
+        this.maxBytes = maxBytes;
+        this.actualBytes = actualBytes;
+    }
+}

package/dist/skill-system/loader.d.ts

@@ -0,0 +1,8 @@
+import type { SkillBundle, SkillManifest } from "./types.js";
+export declare function setBundledSkillsDir(dir: string): void;
+export declare function resetBundledSkillsDir(): void;
+export declare function listBundledSkills(): SkillManifest[];
+export declare function loadBundledSkill(id: string): SkillBundle;
+export declare function loadBundledSkillFrom(skillsDir: string, id: string): SkillBundle;
+export declare function readBundledSkillResource(id: string, resourcePath: string): string;
+export declare function readBundledSkillResourceFrom(skillsDir: string, id: string, resourcePath: string): string;

package/dist/skill-system/loader.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SkillNotFoundError, SkillResourceNotFoundError, SkillResourceOutOfBoundsError, } from "./errors.js";
+import { SKILL_FILE_NAME, isPathOutOfBounds, isWithinRoot, normalizeResourcePath, } from "./paths.js";
+import { RESOURCE_MAX_BYTES, assertMaxBytes, parseSkillBundle, } from "./validation.js";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+// Source tests load this module from src/skill-system, while the published
+// bundle inlines it into dist/index.js and copies assets to dist/skills.
+const defaultBundledSkillsDir = existsSync(resolve(moduleDir, "skills"))
+    ? resolve(moduleDir, "skills")
+    : resolve(moduleDir, "../skills");
+let bundledSkillsDir = defaultBundledSkillsDir;
+export function setBundledSkillsDir(dir) {
+    bundledSkillsDir = dir;
+}
+export function resetBundledSkillsDir() {
+    bundledSkillsDir = defaultBundledSkillsDir;
+}
+export function listBundledSkills() {
+    return listFrom(bundledSkillsDir);
+}
+export function loadBundledSkill(id) {
+    return loadBundledSkillFrom(bundledSkillsDir, id);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function loadBundledSkillFrom(skillsDir, id) {
+    const root = findRoot(resolve(skillsDir), id);
+    if (!root)
+        throw new SkillNotFoundError(id);
+    return parseSkillBundle(root);
+}
+export function readBundledSkillResource(id, resourcePath) {
+    return readBundle(loadBundledSkill(id), id, resourcePath);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function readBundledSkillResourceFrom(skillsDir, id, resourcePath) {
+    return readBundle(loadBundledSkillFrom(skillsDir, id), id, resourcePath);
+}
+function listFrom(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(dir, entry.name))
+        .filter((root) => existsSync(join(root, SKILL_FILE_NAME)))
+        .map((root) => parseSkillBundle(root).manifest)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function findRoot(dir, id) {
+    return listRoots(dir).find((root) => parseSkillBundle(root).manifest.id === id);
+}
+function listRoots(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(dir, entry.name))
+        .filter((root) => existsSync(join(root, SKILL_FILE_NAME)));
+}
+function readBundle(bundle, id, resourcePath) {
+    const resource = normalizeResourcePath(resourcePath);
+    if (!resource || isPathOutOfBounds(resourcePath))
+        throw new SkillResourceOutOfBoundsError(id, resourcePath);
+    if (!(bundle.manifest.resources ?? []).some((declared) => normalizeResourcePath(declared) === resource))
+        throw new SkillResourceNotFoundError(id, resourcePath);
+    const candidate = resolve(bundle.rootDir, resource);
+    try {
+        if (!isWithinRoot(realpathSync(bundle.rootDir), realpathSync(candidate)))
+            throw new SkillResourceOutOfBoundsError(id, resourcePath);
+    }
+    catch (error) {
+        if (error instanceof SkillResourceOutOfBoundsError)
+            throw error;
+        throw new SkillResourceNotFoundError(id, resourcePath);
+    }
+    assertMaxBytes(candidate, RESOURCE_MAX_BYTES);
+    return readFileSync(candidate, "utf8");
+}

package/dist/skill-system/paths.d.ts

@@ -0,0 +1,5 @@
+export declare const SKILL_FILE_NAME = "SKILL.md";
+export declare function normalizeResourcePath(pathLike: string): string;
+export declare function isPathOutOfBounds(pathLike: string): boolean;
+export declare function isWithinRoot(rootDir: string, candidatePath: string): boolean;
+export declare function resolveSkillFilePath(pathLike: string): string;

package/dist/skill-system/paths.js

@@ -0,0 +1,25 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, normalize, relative, resolve } from "node:path";
+export const SKILL_FILE_NAME = "SKILL.md";
+export function normalizeResourcePath(pathLike) {
+    return normalize(pathLike).replaceAll("\\", "/");
+}
+export function isPathOutOfBounds(pathLike) {
+    const normalized = normalizeResourcePath(pathLike);
+    return (isAbsolute(pathLike) ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../"));
+}
+export function isWithinRoot(rootDir, candidatePath) {
+    const rel = relative(rootDir, candidatePath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function resolveSkillFilePath(pathLike) {
+    const resolved = resolve(pathLike);
+    if (existsSync(resolved) && statSync(resolved).isDirectory())
+        return join(resolved, SKILL_FILE_NAME);
+    return resolved.endsWith(SKILL_FILE_NAME)
+        ? resolved
+        : join(resolved, SKILL_FILE_NAME);
+}

package/dist/skill-system/types.d.ts

@@ -0,0 +1,14 @@
+export interface SkillManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    kibiCompatibility: string;
+    tags?: string[];
+    resources?: string[];
+}
+export interface SkillBundle {
+    manifest: SkillManifest;
+    body: string;
+    rootDir: string;
+}

package/dist/skill-system/types.js

@@ -0,0 +1 @@
+export {};

package/dist/skill-system/validation.d.ts

@@ -0,0 +1,9 @@
+import { SkillValidationError } from "./errors.js";
+import type { SkillBundle } from "./types.js";
+export declare const RESOURCE_MAX_BYTES: number;
+export declare function assertMaxBytes(pathLike: string, maxBytes: number): void;
+export declare function parseSkillBundle(rootDir: string): SkillBundle;
+export declare function validateSkillBundle(pathLike: string): {
+    valid: boolean;
+    errors: SkillValidationError[];
+};

package/dist/skill-system/validation.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import matter from "gray-matter";
+import { SkillOversizeError, SkillValidationError } from "./errors.js";
+import { SKILL_FILE_NAME, isPathOutOfBounds, isWithinRoot, normalizeResourcePath, resolveSkillFilePath, } from "./paths.js";
+const SKILL_MARKDOWN_MAX_BYTES = 256 * 1024;
+export const RESOURCE_MAX_BYTES = 128 * 1024;
+export function assertMaxBytes(pathLike, maxBytes) {
+    const size = statSync(pathLike).size;
+    if (size > maxBytes)
+        throw new SkillOversizeError(pathLike, maxBytes, size);
+}
+export function parseSkillBundle(rootDir) {
+    const path = resolve(rootDir, SKILL_FILE_NAME);
+    assertMaxBytes(path, SKILL_MARKDOWN_MAX_BYTES);
+    const parsed = matter(readFileSync(path, "utf8"));
+    const [error] = validateManifestData(parsed.data);
+    if (error)
+        throw error;
+    return {
+        manifest: coerceManifest(parsed.data),
+        body: parsed.content,
+        rootDir: resolve(rootDir),
+    };
+}
+export function validateSkillBundle(pathLike) {
+    const path = resolveSkillFilePath(pathLike);
+    const errors = [];
+    if (!existsSync(path))
+        return {
+            valid: false,
+            errors: [
+                new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`),
+            ],
+        };
+    const parsed = matter(readFileSync(path, "utf8"));
+    errors.push(...validateManifestData(parsed.data));
+    if (errors.length === 0)
+        validateBundleContents(path, coerceManifest(parsed.data), errors);
+    return { valid: errors.length === 0, errors };
+}
+function validateBundleContents(path, manifest, errors) {
+    try {
+        assertMaxBytes(path, SKILL_MARKDOWN_MAX_BYTES);
+    }
+    catch (error) {
+        errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+    }
+    let root;
+    try {
+        root = realpathSync(dirname(path));
+    }
+    catch (error) {
+        errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+        return;
+    }
+    for (const resource of manifest.resources ?? []) {
+        const resourcePath = resolve(dirname(path), resource);
+        try {
+            if (!existsSync(resourcePath)) {
+                errors.push(new SkillValidationError("resources", `Missing skill resource: ${resource}`));
+                continue;
+            }
+            const real = realpathSync(resourcePath);
+            if (!isWithinRoot(root, real)) {
+                errors.push(new SkillValidationError("resources", `Skill resource escapes bundle root: ${resource}`));
+                continue;
+            }
+            assertMaxBytes(resourcePath, RESOURCE_MAX_BYTES);
+        }
+        catch (error) {
+            errors.push(new SkillValidationError("resources", error instanceof Error ? error.message : String(error)));
+        }
+    }
+}
+function validateManifestData(data) {
+    const errors = [];
+    for (const field of [
+        "id",
+        "name",
+        "description",
+        "version",
+        "kibiCompatibility",
+    ])
+        if (typeof data[field] !== "string" || data[field].trim() === "")
+            errors.push(new SkillValidationError(field, `Missing required skill field: ${field}`));
+    if (typeof data.version === "string" &&
+        !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.version))
+        errors.push(new SkillValidationError("version", `Invalid skill version: ${data.version}`));
+    for (const [field, value] of [
+        ["tags", data.tags],
+        ["resources", data.resources],
+    ]) {
+        if (value !== undefined && !isStringArray(value))
+            errors.push(new SkillValidationError(field, `Skill ${field} must be strings`));
+    }
+    if (isStringArray(data.resources))
+        for (const resource of data.resources)
+            if (!normalizeResourcePath(resource) || isPathOutOfBounds(resource))
+                errors.push(new SkillValidationError("resources", `Invalid skill resource: ${resource}`));
+    return errors;
+}
+function coerceManifest(data) {
+    const manifest = {
+        id: String(data.id),
+        name: String(data.name),
+        description: String(data.description),
+        version: String(data.version),
+        kibiCompatibility: String(data.kibiCompatibility),
+    };
+    if (isStringArray(data.tags))
+        manifest.tags = data.tags;
+    if (isStringArray(data.resources))
+        manifest.resources = data.resources.map(normalizeResourcePath);
+    return manifest;
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}

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

@@ -0,0 +1,58 @@
+---
+id: kibi-bootstrap
+name: kibi-bootstrap
+description: Bootstrap Kibi from the current Git checkout with exact Git attachment, preview approval, source-first writes, and repair-safe completion.
+version: 3.0.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - bootstrap
+  - source-first
+  - agent-guidance
+resources:
+  - resources/bootstrap.md
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
+---
+## Goal
+
+Seed branch-local Kibi knowledge for an attached but thin repository without
+creating a parallel human-maintained ticket system. Ask at most four bounded
+context questions only when the planner says repository evidence is
+insufficient; agents own deterministic translation and humans resolve genuine
+ambiguity. A seeded repository hands off to the normal Kibi workflow.
+
+## Interface and preview
+
+Use the visible approved MCP surface or the trusted project-local CLI as equal
+peer interfaces. If neither is available, stop. Run `kb_plan_bootstrap` (or
+`plan-bootstrap --input`) read-only. If it returns `needs_context`, ask only its
+bounded questions (never more than four), then rerun the planner. Show the
+complete returned `structuredContent.plan`, including its canonical hash, and
+get explicit approval before any write. Pass that plan object unchanged to
+`kb_apply_plan`; do not reconstruct it from preview fields.
+
+For CLI JSON, use the trusted route with `--input` (for example
+`printf '%s\n' '{}' | kibi status --input -`); MCP and CLI are semantic peers.
+Read the branch-lifecycle and source-authoring resources before migration,
+source writes, or repair actions.
+
+## Apply and verify
+
+Apply the approved `kibi.bootstrap-plan.v1` by calling `kb_apply_plan` with the
+exact plan and approved hash. The operation owns dependency ordering,
+source-first writes, sequential mutation, and recovery journaling. Direct
+`kb_upsert` is forbidden for every kibi-bootstrap task, including after
+approval; never replay plan actions manually. Use `kb_delete` only for an
+approved hash-bound deletion plan; evolve requirements with `supersedes`.
+Finish with `kb_check` and `kb_status`.
+
+Consume the versioned `kibiProtocol: 1` result envelope: inspect `status`, `effects`,
+`diagnostics`, and `nextActions`. On `committed_with_repairs`, execute required
+repair actions and never retry the original mutation.
+
+Kibi may author tracked Markdown/YAML/manifests and relationship shards
+transactionally, but never Git-stages or commits them. Never read or edit
+`.kb` directly. Missing exact branch stores are compiled from this checkout's
+tracked sources by `kibi sync`; Kibi does not copy another branch's store.

package/dist/skills/kibi-bootstrap/resources/bootstrap.md

@@ -0,0 +1,11 @@
+# Bootstrap resource
+
+`kb_plan_bootstrap` is read-only and returns `kibi.bootstrap-plan.v1`. Review
+candidate evidence, exact actions, dependencies, expected snapshots, source
+hashes, bounded questions, diagnostics, and the canonical `planHash` before
+approving. A preview does not authorize source edits. After approval, pass the
+unchanged returned `structuredContent.plan` to `kb_apply_plan` once with its
+approved hash; inspect its typed result
+and follow `nextActions` if it returns `committed_with_repairs`. Direct
+`kb_upsert` is forbidden for every bootstrap task; never manually replay the
+plan through it.

package/dist/skills/kibi-bootstrap/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+Use the exact `KIBI_BRANCH` value or Git symbolic HEAD. Hashed stores carry a
+matching `branch.json`; missing stores are compiled from tracked sources by
+`kibi sync`. Legacy literal stores require explicit migration. Kibi never
+copies stores between branches or resolves Git conflicts. Read the preview,
+approval hash, quarantine, restore, and purge details before lifecycle work.

package/dist/skills/kibi-bootstrap/resources/operation-access.md

@@ -0,0 +1,5 @@
+# Operation access
+
+MCP tools and the trusted project-local CLI are peer surfaces for the same
+operation contracts. Use the dedicated JSON route; parse the shared
+`KibiResult` envelope and follow required `nextActions` after partial commits.

package/dist/skills/kibi-bootstrap/resources/source-authoring.md

@@ -0,0 +1,8 @@
+# Source authoring
+
+Tracked documents, manifests, and relationship shards are authoritative.
+Kibi may write them transactionally but does not stage or commit them. Use
+`document.path` for ambiguous new targets, preserve existing bodies when the
+body is omitted, and use hash-bound deletion plans. On
+`committed_with_repairs`, follow typed `nextActions` and never retry the
+original mutation.