kibi-agent-core 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # kibi-agent-core
 
+## 0.2.1
+
+### Patch Changes
+
+- 2a2b2db: Every Kibi package page on npm now has a README that says what the package is for and how to install it, and links to the documentation site. Package metadata now points npm's "Homepage" link at the documentation site, its "Repository" link at the package's own folder on GitHub, and adds an "Issues" link.
+
+  Adds READMEs to `kibi-cli`, `kibi-mcp`, `kibi-core`, `kibi-runtime`, `kibi-agent-core`, `kibi-codex`, `kibi-plugin-builtin` and `kibi-plugin-sdk`. Sets `homepage` to https://looted.github.io/kibi/, adds `repository.directory` and `bugs` to every package, and refreshes the `kibi-plugin-treesitter` integrity manifest and source-analyzer approval for its changed `package.json`.
+
+## 0.2.0
+
+### Minor Changes
+
+- f8fff87: The telemetry acceptance and remediation reports now show whether agents look requirements up before they change requirement-linked code. A new `lookup_before_first_edit` metric gives, per host session, the share of sessions that ran `kb_search` or `kb_query` (through MCP or the CLI) before their first edit of a file whose symbols implement a requirement. Sessions that edited first appear in the report with the file and its exact `.kb/usage.log` line. The data comes from opt-in hook rows that every Kibi host plugin now writes when `KIBI_DIAGNOSTIC_MODE` is set; nothing is recorded otherwise.
+  - `kibi usage-metrics` / `kb_check` telemetry acceptance: new metric `lookup_before_first_edit` (threshold `>=` policy `lookupBeforeFirstEditMinimum`, default 1) with evidence `unguidedEditPaths` and `lookupOperations`. It is `not_applicable` when no host hook recorded a requirement-linked edit, so logs without hook rows are judged as before. A failed metric adds the advisory diagnostic `lookup_before_first_edit_bypassed` (rank 35).
+  - `kibi usage-remediation`: one event item per session whose first linked edit had no earlier lookup, pointing at that hook row.
+  - `parseTelemetryUsageLog` still returns only Kibi operation rows; hook rows stay attached to the returned array (read them with `partitionTelemetryUsage`). Remediation `logLine` values now count hook rows and blank lines, so they match the file.
+  - `kibi-agent-core/hook-usage-log`: shared `appendHookUsage` / `appendHookUsageRows`, `kbUsageTrace` and `editTraces`. Hook rows (`interface: "hook"`) carry `host`, `session_id`, `hook_action` (`kb_usage` or `edited`), `kb_operation`, `path`, `path_kind` and `requirement_ids`. `hostKbOperation` recognizes MCP tool names and `kibi <route>` shell commands; `extractEditedPaths` reads `apply_patch` headers.
+  - Claude Code: `edited` rows now carry the file's `requirement_ids`, and every row names its `host`. Cursor (`postToolUse`), Codex and ZCode (`PostToolUse`) and OpenCode (`tool.execute.after`) now write the same `kb_usage` and `edited` rows.
+
+- 1012d1c: When an agent edits a file that implements a requirement, every Kibi host plugin (Claude Code, Cursor, Codex, ZCode and OpenCode) now says what that requirement must keep true and the decision behind it, not just its ID. The extra lines come from the requirement's linked facts and ADR, so agents see the constraint before they change the code. All hosts build the snippet with one shared builder in `kibi-agent-core`, so they show the same lines within each host's size limits, and none of them presents a superseded or retired requirement as current.
+  - New `kibi-agent-core/snippets` export: `fileKnowledgeSnippet`, `requirementGroundingLines`, `editKnowledgeContext`, `editFocus` and `createEntitySummarizer`. Edit snippets add "`<REQ>` must keep true: …" (up to two facts linked via `constrains`, `requires_property`, `requires_predicate` or `requires_rule`) and "Decision: `<ADR>`" for the lead requirement. Read snippets keep the requirement and test lines only.
+  - A superseded, deprecated or retired lead requirement gets no "must keep true" or "Decision" lines, so retired policy is not shown as current.
+  - Claude Code: the `PreToolUse` edit snippet now comes from the shared builder (no change in content).
+  - Cursor: `preToolUse` edit guidance and `beforeReadFile` / read guidance include the shared snippet for files whose symbols implement a requirement, followed by the existing "query before you change it" follow-up.
+  - Codex: `PreToolUse` on `apply_patch` (and other edit tools) returns the snippet as `additionalContext`, for up to three changed files per call and once per file per session. Paths come from the patch's `*** Update/Add/Delete File:` headers.
+  - ZCode: `PreToolUse` on edit tools returns the snippet as `additionalContext`, including "The edit is inside `<symbol>`" when the edited text is found, once per file per session.
+  - OpenCode: the edit-guidance system prompt adds one "must keep true … Decision …" bullet (one fact) for the focus file, within the existing word budget.
+  - `readEntitySummary` returns frontmatter `links` (plain entries read as `relates_to`; `type` and `target` in either order) merged with the entity's records in `.kb/relationships` shards, so grounding stored only in shards still reaches the snippet.
+  - Session and discovery hints point at `kb_search` questions and its answer layer instead of asking for `rankingMode: "intent-v1"`, which is now the default.
+
+### Patch Changes
+
+- 15356de: Host hooks no longer ask for a `kb_check` after a `kb_upsert` dry run. A dry run only validates, so the Cursor, Codex, ZCode and OpenCode hooks now count it as validation rather than a KB write.
+  - `extractKbMcpToolCall` reports `kb_upsert` with `dryRun: true` as `kb_validate_upsert`.
+  - OpenCode's freshness evidence records a dry-run upsert as `kb_validate_upsert`, which carries no mutation evidence.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,17 @@
+# kibi-agent-core
+
+Shared, low-latency helpers for [Kibi](https://looted.github.io/kibi/) agent-host adapters. The Claude Code, Cursor, Codex, OpenCode and ZCode integrations use it to build the short requirement snippets their hooks show before an agent reads or edits linked code (the requirement, what it must keep true, the decision behind it and its tests), to classify paths, and to log opt-in hook usage.
+
+Entry points: `kibi-agent-core`, plus the subpaths `/snippets`, `/knowledge-index`, `/path-policy`, `/kb-mcp-tools` and `/hook-usage-log`.
+
+It is an internal building block of the host plugins, not something you install by hand. To use Kibi, see the [quick start](https://looted.github.io/kibi/guide/quick-start.html).
+
+## Links
+
+- [Documentation](https://looted.github.io/kibi/)
+- [Source](https://github.com/Looted/kibi)
+- [Issues](https://github.com/Looted/kibi/issues)
+
+## License
+
+AGPL-3.0-or-later

package/dist/hook-usage-log.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Opt-in hook telemetry shared by every host adapter.
+ *
+ * MCP and CLI usage rows show which Kibi operations ran, but not what the
+ * agent was doing around them. Hook rows fill that gap: they record when the
+ * agent read or edited a source file (and which requirements the file's
+ * symbols implement), whether Kibi context was shown or suppressed, and which
+ * Kibi operations the agent ran through MCP or the project-local CLI. Joined
+ * on the host session id they show whether lookups happen before edits or
+ * only afterwards; the telemetry acceptance report turns that into the
+ * `lookup_before_first_edit` metric.
+ *
+ * Rows go to the same `.kb/usage.log` as MCP and CLI rows, tagged
+ * `interface: "hook"`, so the existing ignore rule covers them. They are
+ * written only when the operator opted in with `KIBI_DIAGNOSTIC_MODE`, the
+ * same signal the MCP server and CLI honor; installing a plugin never
+ * enables them.
+ */
+/** What the hook did for one tool call. Unset `action` means "nothing to record". */
+export type HookTrace = {
+    action?: string;
+    path?: string;
+    pathKind?: string;
+    /** Requirements the touched file's symbols implement (symbol manifest). */
+    requirementIds?: string[];
+    /** Canonical Kibi operation (`kb_search`, `kb_query`, …) a call ran. */
+    kbOperation?: string;
+    /** Session state before this call: had the agent used Kibi yet? */
+    kbUsedBefore?: boolean | undefined;
+};
+/** Hook actions the acceptance report reads; hosts emit these names. */
+export declare const HOOK_ACTION_EDITED = "edited";
+export declare const HOOK_ACTION_KB_USAGE = "kb_usage";
+export declare function hookTelemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
+export type HookUsageRow = {
+    /** Host agent, e.g. `claude-code`, `cursor`, `codex`, `zcode`, `opencode`. */
+    host: string;
+    /** Version of the adapter package that wrote the row, when known. */
+    packageVersion?: string | null | undefined;
+    workspaceRoot: string;
+    event: string;
+    sessionId: string | undefined;
+    hostTool: string | undefined;
+    trace: HookTrace;
+    startedAt: Date;
+};
+/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+export declare function appendHookUsage(row: HookUsageRow, env?: NodeJS.ProcessEnv): void;
+/**
+ * Trace for a tool call that ran a Kibi operation through MCP or the
+ * project-local CLI, or undefined for any other tool.
+ */
+export declare function kbUsageTrace(toolName: string | undefined, toolInput: unknown): HookTrace | undefined;
+/**
+ * One `edited` trace per workspace-relative path an edit tool changed,
+ * skipping docs, config, and generated paths. `requirementIdsFor` names the
+ * requirements a file's symbols implement; KB files implement none.
+ */
+export declare function editTraces(relativePaths: readonly string[], requirementIdsFor: (relativePath: string) => string[]): HookTrace[];
+/** Append one row per trace, sharing the call's host, session and tool. */
+export declare function appendHookUsageRows(row: Omit<HookUsageRow, "trace">, traces: readonly HookTrace[], env?: NodeJS.ProcessEnv): void;
+/**
+ * Version of the adapter package whose `package.json` sits at
+ * `packageJsonPath`, or null when it cannot be read.
+ */
+export declare function readPackageVersion(packageJsonPath: string): string | null;

package/dist/hook-usage-log.js

@@ -0,0 +1,112 @@
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { hostKbOperation } from "./kb-mcp-tools.js";
+import { classifyPath } from "./path-policy.js";
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
+/** Hook actions the acceptance report reads; hosts emit these names. */
+export const HOOK_ACTION_EDITED = "edited";
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
+export const HOOK_ACTION_KB_USAGE = "kb_usage";
+// implements REQ-claude-hook-usage-telemetry-v2
+export function hookTelemetryEnabled(env = process.env) {
+    const value = env.KIBI_DIAGNOSTIC_MODE?.trim().toLowerCase();
+    return value === "1" || value === "true";
+}
+// implements REQ-claude-hook-usage-telemetry-v2
+/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+export function appendHookUsage(row, env = process.env) {
+    if (!hookTelemetryEnabled(env) || row.trace.action === undefined)
+        return;
+    const finishedAt = new Date();
+    const { trace } = row;
+    const record = {
+        timestamp: finishedAt.toISOString(),
+        request_id: `hook-${randomUUID()}`,
+        tool: `hook_${row.event}`,
+        interface: "hook",
+        host: row.host,
+        package_version: row.packageVersion ?? null,
+        workspace_root: row.workspaceRoot,
+        session_id: row.sessionId ?? null,
+        hook_event: row.event,
+        host_tool: row.hostTool ?? null,
+        hook_action: trace.action,
+        path: trace.path ?? null,
+        path_kind: trace.pathKind ?? null,
+        requirement_ids: trace.requirementIds ?? [],
+        kb_operation: trace.kbOperation ?? null,
+        kb_used_before: trace.kbUsedBefore ?? null,
+        status: "success",
+        duration_ms: finishedAt.getTime() - row.startedAt.getTime(),
+    };
+    try {
+        const logPath = path.join(row.workspaceRoot, ".kb", "usage.log");
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the tool call.
+    }
+}
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
+/**
+ * Trace for a tool call that ran a Kibi operation through MCP or the
+ * project-local CLI, or undefined for any other tool.
+ */
+export function kbUsageTrace(toolName, toolInput) {
+    const kbOperation = hostKbOperation(toolName, toolInput);
+    return kbOperation
+        ? { action: HOOK_ACTION_KB_USAGE, kbOperation }
+        : undefined;
+}
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
+/**
+ * One `edited` trace per workspace-relative path an edit tool changed,
+ * skipping docs, config, and generated paths. `requirementIdsFor` names the
+ * requirements a file's symbols implement; KB files implement none.
+ */
+export function editTraces(relativePaths, requirementIdsFor) {
+    const traces = [];
+    for (const relativePath of new Set(relativePaths)) {
+        const pathKind = classifyPath(relativePath);
+        if (pathKind === "other")
+            continue;
+        traces.push({
+            action: HOOK_ACTION_EDITED,
+            path: relativePath,
+            pathKind,
+            requirementIds: pathKind === "kb" ? [] : requirementIdsFor(relativePath),
+        });
+    }
+    return traces;
+}
+// implements REQ-claude-hook-usage-telemetry-v2
+/** Append one row per trace, sharing the call's host, session and tool. */
+export function appendHookUsageRows(row, traces, env = process.env) {
+    if (!hookTelemetryEnabled(env))
+        return;
+    for (const trace of traces)
+        appendHookUsage({ ...row, trace }, env);
+}
+// implements REQ-claude-hook-usage-telemetry-v2
+/**
+ * Version of the adapter package whose `package.json` sits at
+ * `packageJsonPath`, or null when it cannot be read.
+ */
+export function readPackageVersion(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "version" in parsed &&
+            typeof parsed.version === "string") {
+            return parsed.version;
+        }
+    }
+    catch {
+        // An unreadable manifest leaves the version unknown.
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";
 export * from "./path-policy.js";
+export * from "./snippets.js";

package/dist/index.js

@@ -1,3 +1,5 @@
+export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";
 export * from "./path-policy.js";
+export * from "./snippets.js";

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

@@ -32,3 +32,13 @@ 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;
+/**
+ * The Kibi operation a shell command runs through the project-local CLI
+ * (`kibi search`, `npx --no-install kibi query --input -`), or undefined.
+ */
+export declare function kibiCliOperation(command: unknown): string | undefined;
+/**
+ * The Kibi operation a host tool call ran through either peer surface: a Kibi
+ * MCP tool under any host prefix, or the project-local CLI in a shell tool.
+ */
+export declare function hostKbOperation(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -112,6 +112,12 @@ export function extractKbMcpToolCall(toolName, toolInput) {
             "sourceFiles",
             "source_files",
         ]);
+        // A dry-run upsert only validates; report it as the read-only operation
+        // it routes to so hooks do not treat it as a KB write.
+        if (normalizedToolName === "kb_upsert" &&
+            readBoolean(payload, ["dryRun"]) === true) {
+            normalizedToolName = "kb_validate_upsert";
+        }
         if (normalizedToolName?.startsWith("kb_")) {
             return {
                 toolName: normalizedToolName,
@@ -194,3 +200,44 @@ export function extractKbMcpToolName(toolName, toolInput) {
     }
     return undefined;
 }
+/** Project-local CLI routes and the Kibi operation each one runs. */
+const KIBI_CLI_ROUTES = {
+    check: "kb_check",
+    query: "kb_query",
+    "kb-query": "kb_query",
+    search: "kb_search",
+    status: "kb_status",
+    graph: "kb_graph",
+    coverage: "kb_coverage",
+    "find-gaps": "kb_find_gaps",
+    gaps: "kb_find_gaps",
+    upsert: "kb_upsert",
+    sync: "kb_sync",
+};
+/**
+ * The Kibi operation a shell command runs through the project-local CLI
+ * (`kibi search`, `npx --no-install kibi query --input -`), or undefined.
+ */
+// implements REQ-claude-code-kibi-plugin-v1
+export function kibiCliOperation(command) {
+    if (typeof command !== "string")
+        return undefined;
+    const route = /(?:^|[\s;&|(/])kibi\s+([a-z-]+)/.exec(command)?.[1];
+    return route ? KIBI_CLI_ROUTES[route] : undefined;
+}
+/** Host tool names that run a shell command from `tool_input.command`. */
+const SHELL_TOOL_NAMES = new Set(["Bash", "bash", "Shell", "shell"]);
+/**
+ * The Kibi operation a host tool call ran through either peer surface: a Kibi
+ * MCP tool under any host prefix, or the project-local CLI in a shell tool.
+ */
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1
+export function hostKbOperation(toolName, toolInput) {
+    const mcp = canonicalKbToolName(toolName);
+    if (mcp !== undefined && /^kb_[a-z_]+$/.test(mcp))
+        return mcp;
+    if (!toolName || !SHELL_TOOL_NAMES.has(toolName) || !isRecord(toolInput)) {
+        return undefined;
+    }
+    return kibiCliOperation(toolInput.command);
+}

package/dist/knowledge-index.d.ts

@@ -37,14 +37,25 @@ export declare function buildKnowledgeIndex(records: readonly RawRecord[], coord
  * manifests keep their size and mtime.
  */
 export declare function loadKnowledgeIndex(workspaceRoot: string, cacheDir?: string, options?: KnowledgeIndexOptions): KnowledgeIndex;
+export type EntityLink = {
+    type: string;
+    target: string;
+};
 export type EntitySummary = {
     id: string;
     title?: string;
     status?: string;
+    /**
+     * Frontmatter `links` (plain string entries read as `relates_to`) merged
+     * with canonical relationship-shard records whose `from` is this entity.
+     */
+    links?: EntityLink[];
 };
 /**
- * Read an entity's title and status from its canonical authored document
- * (`.kb/<lane>/<ID>.md`). Only the frontmatter head is read.
+ * Read an entity's title, status and outgoing links. Title and status come
+ * from the frontmatter head of its canonical authored document
+ * (`.kb/<lane>/<ID>.md`); links come from that frontmatter plus the canonical
+ * relationship shard (`.kb/relationships/<shard>.yaml`) holding its records.
  */
 export declare function readEntitySummary(workspaceRoot: string, entityId: string): EntitySummary;
 export {};

package/dist/knowledge-index.js

@@ -1,5 +1,5 @@
 // implements REQ-claude-code-kibi-plugin-v1
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 /**
@@ -62,14 +62,21 @@ function parseScalarOrFlow(raw) {
  * `symbols:` mapping and a bare top-level sequence.
  */
 export function scanSymbolsManifest(text) {
+    return scanRecordSequence(text, "symbols");
+}
+/**
+ * Scan the block sequence under top-level `sectionKey` (or a bare root
+ * sequence) into raw records.
+ */
+function scanRecordSequence(text, sectionKey) {
     const records = [];
     let itemIndent;
     let keyIndent = 0;
     let current;
     let listKey;
     let listItem;
-    // Top-level section: symbols are the `symbols:` sequence or a bare root
-    // sequence; sequences under any other top-level key are ignored.
+    // Top-level section: records are the `<sectionKey>:` sequence or a bare
+    // root sequence; sequences under any other top-level key are ignored.
     let section = "root";
     for (const rawLine of text.split(/\r?\n/)) {
         const content = rawLine.trim();
@@ -80,8 +87,8 @@ export function scanSymbolsManifest(text) {
         if (indent === 0 && !dash) {
             const pair = keyValue.exec(content);
             section =
-                pair?.[1] !== undefined && unquote(pair[1]) === "symbols"
-                    ? "symbols"
+                pair?.[1] !== undefined && unquote(pair[1]) === sectionKey
+                    ? "records"
                     : "other";
             current = undefined;
             itemIndent = undefined;
@@ -348,9 +355,58 @@ const ENTITY_LANES = [
     ["EVT-", "events"],
 ];
 const SAFE_ENTITY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MAX_SUMMARY_LINKS = 24;
+const RELATIONSHIPS_DIR = ".kb/relationships";
+/**
+ * Parsed relationship shards keyed by absolute path and revalidated by size
+ * and mtime, so one process parses each shard once however many summaries it
+ * reads.
+ */
+const shardCache = new Map();
+/** Shard holding a `from` id's records: first two hex chars of SHA-256(id). */
+function shardPathFor(workspaceRoot, entityId) {
+    const shard = createHash("sha256").update(entityId).digest("hex");
+    return path.join(workspaceRoot, RELATIONSHIPS_DIR, `${shard.slice(0, 2)}.yaml`);
+}
+function shardLinksFrom(workspaceRoot, entityId) {
+    const shardPath = shardPathFor(workspaceRoot, entityId);
+    const signature = fileSignature(shardPath);
+    if (signature === "missing") {
+        shardCache.delete(shardPath);
+        return [];
+    }
+    let cached = shardCache.get(shardPath);
+    if (cached?.signature !== signature) {
+        const byFrom = new Map();
+        const records = scanRecordSequence(readText(shardPath) ?? "", "relationships");
+        for (const { type, from, to } of records) {
+            if (typeof type !== "string" ||
+                typeof from !== "string" ||
+                typeof to !== "string") {
+                continue;
+            }
+            const list = byFrom.get(from) ?? [];
+            list.push({ type, target: to });
+            byFrom.set(from, list);
+        }
+        cached = { signature, byFrom };
+        shardCache.set(shardPath, cached);
+    }
+    return cached.byFrom.get(entityId) ?? [];
+}
+function flushLink(links, pending) {
+    if (pending?.target !== undefined) {
+        links.push({ type: pending.type ?? "relates_to", target: pending.target });
+    }
+    else if (pending?.bare !== undefined) {
+        links.push({ type: "relates_to", target: pending.bare });
+    }
+}
 /**
- * Read an entity's title and status from its canonical authored document
- * (`.kb/<lane>/<ID>.md`). Only the frontmatter head is read.
+ * Read an entity's title, status and outgoing links. Title and status come
+ * from the frontmatter head of its canonical authored document
+ * (`.kb/<lane>/<ID>.md`); links come from that frontmatter plus the canonical
+ * relationship shard (`.kb/relationships/<shard>.yaml`) holding its records.
  */
 export function readEntitySummary(workspaceRoot, entityId) {
     const lane = ENTITY_LANES.find(([prefix]) => entityId.startsWith(prefix));
@@ -360,7 +416,7 @@ export function readEntitySummary(workspaceRoot, entityId) {
     try {
         const descriptor = fs.openSync(path.join(workspaceRoot, ".kb", lane[1], `${entityId}.md`), "r");
         try {
-            const buffer = Buffer.alloc(4096);
+            const buffer = Buffer.alloc(8192);
             const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
             head = buffer.subarray(0, bytes).toString("utf8");
         }
@@ -375,6 +431,9 @@ export function readEntitySummary(workspaceRoot, entityId) {
     if (lines[0]?.trim() !== "---")
         return { id: entityId };
     const summary = { id: entityId };
+    const authored = [];
+    let inLinks = false;
+    let pending;
     for (const line of lines.slice(1)) {
         if (line.trim() === "---")
             break;
@@ -383,6 +442,49 @@ export function readEntitySummary(workspaceRoot, entityId) {
             summary.title = unquote(match[2]);
         if (match?.[1] === "status" && match[2])
             summary.status = unquote(match[2]);
+        if (/^\S/.test(line)) {
+            flushLink(authored, pending);
+            pending = undefined;
+            inLinks = /^links:\s*$/.test(line);
+            continue;
+        }
+        if (!inLinks)
+            continue;
+        // Typed entries carry `type: X` and `target: Y` in either order, so an
+        // entry is pushed only when the next entry or section starts; a bare
+        // `- ID` entry is a generic relates_to link.
+        const entry = /^\s*-\s*(.*)$/.exec(line);
+        if (entry) {
+            flushLink(authored, pending);
+            pending = {};
+        }
+        if (!pending)
+            continue;
+        const body = (entry ? (entry[1] ?? "") : line).trim();
+        const field = /^(type|target):\s*(.+)$/.exec(body);
+        if (field?.[1] === "type")
+            pending.type = unquote(field[2] ?? "");
+        else if (field?.[1] === "target")
+            pending.target = unquote(field[2] ?? "");
+        else if (entry && SAFE_ENTITY_ID.test(unquote(body)))
+            pending.bare = unquote(body);
+    }
+    flushLink(authored, pending);
+    const links = [];
+    const seen = new Set();
+    for (const link of [
+        ...authored,
+        ...shardLinksFrom(workspaceRoot, entityId),
+    ]) {
+        const key = `${link.type}\u0000${link.target}`;
+        if (link.target.length === 0 || seen.has(key))
+            continue;
+        seen.add(key);
+        links.push(link);
+        if (links.length >= MAX_SUMMARY_LINKS)
+            break;
     }
+    if (links.length > 0)
+        summary.links = links;
     return summary;
 }

package/dist/path-policy.d.ts

@@ -21,6 +21,16 @@ export type CanonicalWorkspacePath = {
 };
 export declare function normalizeWorkspacePath(candidate: string): string;
 export declare function extractExplicitPathFields(input: unknown): string[];
+/**
+ * Files named by an `apply_patch` envelope (`*** Update File: <path>`,
+ * `*** Add File:`, `*** Delete File:`), in patch order.
+ */
+export declare function extractPatchFilePaths(patch: string): string[];
+/**
+ * Paths an edit tool call targets: explicit path fields plus the files named
+ * in patch text (Codex sends `apply_patch` with the patch in `command`).
+ */
+export declare function extractEditedPaths(toolInput: unknown): string[];
 export declare function canonicalizeWorkspacePath(workspaceRoot: string, options: {
     eventCwd?: string | undefined;
     base?: string | undefined;

package/dist/path-policy.js

@@ -125,6 +125,40 @@ export function extractExplicitPathFields(input) {
     visitExplicitPathFields(input, paths);
     return [...new Set(paths)];
 }
+const patchFileHeader = /^\*\*\* (?:Update|Add|Delete) File: (.+)$/;
+const patchTextKeys = ["command", "patch", "input", "patchText"];
+/**
+ * Files named by an `apply_patch` envelope (`*** Update File: <path>`,
+ * `*** Add File:`, `*** Delete File:`), in patch order.
+ */
+// implements REQ-codex-kibi-plugin-v1
+export function extractPatchFilePaths(patch) {
+    const paths = [];
+    for (const line of patch.split(/\r?\n/)) {
+        const match = patchFileHeader.exec(line.trim());
+        const candidate = match?.[1] ? normalizeWorkspacePath(match[1]) : "";
+        if (candidate.length > 0)
+            paths.push(candidate);
+    }
+    return [...new Set(paths)];
+}
+/**
+ * Paths an edit tool call targets: explicit path fields plus the files named
+ * in patch text (Codex sends `apply_patch` with the patch in `command`).
+ */
+// implements REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+export function extractEditedPaths(toolInput) {
+    const paths = extractExplicitPathFields(toolInput);
+    if (isRecord(toolInput)) {
+        for (const key of patchTextKeys) {
+            const value = toolInput[key];
+            if (typeof value === "string" && value.includes("*** ")) {
+                paths.push(...extractPatchFilePaths(value));
+            }
+        }
+    }
+    return [...new Set(paths)];
+}
 export function canonicalizeWorkspacePath(workspaceRoot, options) {
     const trimmed = normalizeWorkspacePath(options.rawPath);
     if (trimmed.length === 0)

package/dist/snippets.d.ts

@@ -0,0 +1,85 @@
+import { type EntitySummary, type IndexedSymbol } from "./knowledge-index.js";
+export declare const MAX_SNIPPET_CHARS = 1200;
+export type LineRange = {
+    start: number;
+    end: number;
+};
+export type Summarize = (entityId: string) => EntitySummary;
+export type SnippetInput = {
+    relativePath: string;
+    symbols: readonly IndexedSymbol[];
+    surface: "read" | "edit";
+    /** Lines the tool call targets (edit location or read window). */
+    focus?: readonly LineRange[] | undefined;
+    summarize: Summarize;
+    /** Host context budget for this snippet; defaults to MAX_SNIPPET_CHARS. */
+    maxChars?: number | undefined;
+};
+/** Symbols whose coordinates intersect the focus, innermost first. */
+export declare function focusedSymbols(symbols: readonly IndexedSymbol[], focus: readonly LineRange[] | undefined): IndexedSymbol[];
+/**
+ * Lines an edit will replace, located in the current file content from the
+ * edit's `old_string`/`oldString` (single edits and `edits` lists).
+ */
+export declare function editFocus(absolutePath: string, toolInput: unknown): LineRange[] | undefined;
+/** True for a status that marks an entity as no longer current policy. */
+export declare function isRetiredStatus(status: string | undefined): boolean;
+/** `ID (status): title`, with the status shown only when it is retired. */
+export declare function describeEntity(summary: EntitySummary): string;
+/** Link types through which a requirement is grounded in semantic facts. */
+export declare const GROUNDING_LINK_TYPES: readonly string[];
+/**
+ * What a requirement says must stay true (its linked facts) and the decision
+ * behind it (a linked ADR), read from its frontmatter links and
+ * relationship-shard records. A retired requirement is not current policy, so
+ * its grounding is not presented as something to keep true.
+ */
+export declare function requirementGroundingLines(requirementId: string, summarize: Summarize, options?: {
+    maxFacts?: number;
+}): string[];
+/** Requirement IDs a file's symbols implement, in manifest order. */
+export declare function implementedRequirementIds(symbols: readonly IndexedSymbol[]): string[];
+/**
+ * Memoized entity summaries for one hook process: titles, statuses and links
+ * are read from the workspace once per entity however often a snippet asks.
+ */
+export declare function createEntitySummarizer(workspaceRoot: string): Summarize;
+/**
+ * Knowledge snippet for a file with requirement-linked symbols, or undefined
+ * when the manifest links nothing to it.
+ */
+export declare function fileKnowledgeSnippet(input: SnippetInput): string | undefined;
+/**
+ * One-line focus update for a file whose snippet was already shown this
+ * session: only the new fact (which symbol the edit lands in) is repeated.
+ */
+export declare function focusUpdate(relativePath: string, symbols: readonly IndexedSymbol[], focus: readonly LineRange[] | undefined): string | undefined;
+export type EditKnowledgeInput = {
+    /** Workspace-relative paths the edit call targets, in call order. */
+    relativePaths: readonly string[];
+    /** Symbols with relationships for a workspace-relative path. */
+    symbolsFor: (relativePath: string) => readonly IndexedSymbol[];
+    summarize: Summarize;
+    /** Where the once-per-session markers live; undefined shows every time. */
+    stateDir: string | undefined;
+    /** Host session the markers are scoped to. */
+    sessionId: string | undefined;
+    /** Lines the edit targets in a file, when the host input names them. */
+    focusFor?: ((relativePath: string) => LineRange[] | undefined) | undefined;
+    /** Most files described in one call (an `apply_patch` may touch many). */
+    maxFiles?: number | undefined;
+    maxChars?: number | undefined;
+};
+/**
+ * Pre-edit context for hosts without their own snippet memory: the shared
+ * edit snippet for each linked file the call targets, shown once per file per
+ * session, at most `maxFiles` per call.
+ */
+export declare function editKnowledgeContext(input: EditKnowledgeInput): string | undefined;
+/**
+ * Claim the one-time slot for `key` under `stateDir`: true the first time a
+ * key is claimed, false afterwards. The marker is created exclusively, so
+ * hooks for parallel tool calls never both show the same snippet. Without a
+ * state directory every call is a first time.
+ */
+export declare function claimSnippetSlot(stateDir: string | undefined, key: string): boolean;

package/dist/snippets.js

@@ -0,0 +1,327 @@
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { readEntitySummary, } from "./knowledge-index.js";
+/**
+ * Progressive-disclosure snippets shared by every host adapter.
+ *
+ * Each snippet is the first layer only: requirement IDs with titles, the
+ * symbols that link them, what the lead requirement must keep true and the
+ * decision behind it (edits only), and the exact follow-up call that opens the
+ * next layer. Text is phrased as project facts rather than instructions (hosts
+ * may treat imperative out-of-band text as a possible prompt injection) and
+ * stays within a small budget so repeated reads never flood the context.
+ */
+const MAX_REQUIREMENTS = 4;
+const MAX_SYMBOLS_PER_REQUIREMENT = 3;
+const MAX_TESTS = 3;
+const MAX_TITLE = 80;
+const MAX_GROUNDING = 2;
+/** Files larger than this are not scanned to locate an edit. */
+const MAX_FOCUS_SCAN_BYTES = 2 * 1024 * 1024;
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1
+export const MAX_SNIPPET_CHARS = 1200;
+function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+function overlaps(symbol, range) {
+    if (symbol.line === undefined)
+        return false;
+    const end = symbol.endLine ?? symbol.line;
+    return symbol.line <= range.end && end >= range.start;
+}
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1
+/** Symbols whose coordinates intersect the focus, innermost first. */
+export function focusedSymbols(symbols, focus) {
+    if (!focus || focus.length === 0)
+        return [];
+    return symbols
+        .filter((symbol) => focus.some((range) => overlaps(symbol, range)))
+        .sort((left, right) => (left.endLine ?? left.line ?? 0) -
+        (left.line ?? 0) -
+        ((right.endLine ?? right.line ?? 0) - (right.line ?? 0)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/**
+ * Lines an edit will replace, located in the current file content from the
+ * edit's `old_string`/`oldString` (single edits and `edits` lists).
+ */
+export function editFocus(absolutePath, toolInput) {
+    if (!isRecord(toolInput))
+        return undefined;
+    const needles = [];
+    const collect = (record) => {
+        for (const key of ["old_string", "oldString"]) {
+            const value = record[key];
+            if (typeof value === "string")
+                needles.push(value);
+        }
+    };
+    collect(toolInput);
+    if (Array.isArray(toolInput.edits)) {
+        for (const edit of toolInput.edits) {
+            if (isRecord(edit))
+                collect(edit);
+        }
+    }
+    const usable = needles.filter((needle) => needle.length > 0);
+    if (usable.length === 0)
+        return undefined;
+    let content;
+    try {
+        if (fs.statSync(absolutePath).size > MAX_FOCUS_SCAN_BYTES)
+            return undefined;
+        content = fs.readFileSync(absolutePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const ranges = [];
+    for (const needle of usable) {
+        const offset = content.indexOf(needle);
+        if (offset < 0)
+            continue;
+        const start = content.slice(0, offset).split("\n").length;
+        ranges.push({ start, end: start + needle.split("\n").length - 1 });
+    }
+    return ranges.length > 0 ? ranges : undefined;
+}
+function formatList(items, limit) {
+    const shown = items.slice(0, limit).join(", ");
+    return items.length > limit ? `${shown} +${items.length - limit}` : shown;
+}
+const RETIRED_STATUS = /supersed|deprecat|reject|obsolete|retired/i;
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+/** True for a status that marks an entity as no longer current policy. */
+export function isRetiredStatus(status) {
+    return status !== undefined && RETIRED_STATUS.test(status);
+}
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+/** `ID (status): title`, with the status shown only when it is retired. */
+export function describeEntity(summary) {
+    const notable = isRetiredStatus(summary.status) ? ` (${summary.status})` : "";
+    return summary.title
+        ? `${summary.id}${notable}: ${truncate(summary.title, MAX_TITLE)}`
+        : `${summary.id}${notable}`;
+}
+function jsonString(value) {
+    return JSON.stringify(value);
+}
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+/** Link types through which a requirement is grounded in semantic facts. */
+export const GROUNDING_LINK_TYPES = [
+    "constrains",
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+/**
+ * What a requirement says must stay true (its linked facts) and the decision
+ * behind it (a linked ADR), read from its frontmatter links and
+ * relationship-shard records. A retired requirement is not current policy, so
+ * its grounding is not presented as something to keep true.
+ */
+export function requirementGroundingLines(requirementId, summarize, options = {}) {
+    const maxFacts = options.maxFacts ?? MAX_GROUNDING;
+    const requirement = summarize(requirementId);
+    if (isRetiredStatus(requirement.status))
+        return [];
+    const links = requirement.links ?? [];
+    const facts = [
+        ...new Set(links
+            .filter((link) => GROUNDING_LINK_TYPES.includes(link.type))
+            .map((link) => link.target)),
+    ];
+    const adrs = [
+        ...new Set(links
+            .filter((link) => link.target.startsWith("ADR-"))
+            .map((link) => link.target)),
+    ];
+    const lines = [];
+    if (facts.length > 0) {
+        const shown = facts
+            .slice(0, maxFacts)
+            .map((id) => describeEntity(summarize(id)));
+        const more = facts.length > maxFacts ? ` +${facts.length - maxFacts}` : "";
+        lines.push(`${requirementId} must keep true: ${shown.join("; ")}${more}.`);
+    }
+    const adr = adrs[0];
+    if (adr)
+        lines.push(`Decision: ${describeEntity(summarize(adr))}.`);
+    return lines;
+}
+// implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/** Requirement IDs a file's symbols implement, in manifest order. */
+export function implementedRequirementIds(symbols) {
+    return [...new Set(symbols.flatMap((symbol) => symbol.implements))];
+}
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
+/**
+ * Memoized entity summaries for one hook process: titles, statuses and links
+ * are read from the workspace once per entity however often a snippet asks.
+ */
+export function createEntitySummarizer(workspaceRoot) {
+    const summaries = new Map();
+    return (entityId) => {
+        let summary = summaries.get(entityId);
+        if (!summary) {
+            summary = readEntitySummary(workspaceRoot, entityId);
+            summaries.set(entityId, summary);
+        }
+        return summary;
+    };
+}
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/**
+ * Knowledge snippet for a file with requirement-linked symbols, or undefined
+ * when the manifest links nothing to it.
+ */
+export function fileKnowledgeSnippet(input) {
+    const { relativePath, symbols, surface, summarize } = input;
+    const focus = focusedSymbols(symbols, input.focus);
+    // Requirement -> symbol titles, focus symbols first so their owners lead.
+    const owners = new Map();
+    const ordered = [
+        ...focus,
+        ...symbols.filter((symbol) => !focus.includes(symbol)),
+    ];
+    for (const symbol of ordered) {
+        for (const requirement of symbol.implements) {
+            const titles = owners.get(requirement) ?? [];
+            if (!titles.includes(symbol.title))
+                titles.push(symbol.title);
+            owners.set(requirement, titles);
+        }
+    }
+    const tests = [
+        ...new Set(symbols.flatMap((symbol) => symbol.coveredBy)),
+    ].sort();
+    const executes = [
+        ...new Set(symbols.flatMap((symbol) => symbol.executableFor)),
+    ].sort();
+    if (owners.size === 0 && tests.length === 0 && executes.length === 0) {
+        return undefined;
+    }
+    const focusOwners = new Set(focus.flatMap((symbol) => symbol.implements));
+    const requirementIds = [...owners.keys()].sort((left, right) => {
+        const focusOrder = Number(focusOwners.has(right)) - Number(focusOwners.has(left));
+        return focusOrder !== 0
+            ? focusOrder
+            : (owners.get(right)?.length ?? 0) - (owners.get(left)?.length ?? 0);
+    });
+    const lines = [
+        `Kibi knowledge for ${relativePath} (symbol manifest):`,
+    ];
+    for (const requirementId of requirementIds.slice(0, MAX_REQUIREMENTS)) {
+        const symbolTitles = owners.get(requirementId) ?? [];
+        lines.push(`- ${describeEntity(summarize(requirementId))} — ${formatList(symbolTitles, MAX_SYMBOLS_PER_REQUIREMENT)}`);
+    }
+    if (requirementIds.length > MAX_REQUIREMENTS) {
+        lines.push(`- +${requirementIds.length - MAX_REQUIREMENTS} more requirements: kb_query({sourceFile:${jsonString(relativePath)}})`);
+    }
+    const leadId = requirementIds[0];
+    if (surface === "edit" && leadId) {
+        lines.push(...requirementGroundingLines(leadId, summarize));
+    }
+    if (tests.length > 0) {
+        lines.push(`Covered by: ${formatList(tests, MAX_TESTS)}.`);
+    }
+    if (executes.length > 0) {
+        lines.push(`Test code for: ${formatList(executes, MAX_TESTS)}.`);
+    }
+    const primaryFocus = focus[0];
+    if (primaryFocus) {
+        const owner = primaryFocus.implements[0];
+        const verb = surface === "edit" ? "The edit is inside" : "These lines are inside";
+        lines.push(owner
+            ? `${verb} ${primaryFocus.title}, which implements ${owner}.`
+            : `${verb} ${primaryFocus.title}.`);
+    }
+    const location = primaryFocus
+        ? `{path:${jsonString(relativePath)}, symbol:${jsonString(primaryFocus.title)}}`
+        : `{path:${jsonString(relativePath)}}`;
+    const next = [
+        leadId
+            ? `kb_query({id:${jsonString(leadId)}}) returns full requirement text`
+            : undefined,
+        `kb_search({query:"<topic>", sourceLocations:[${location}]}) answers with governing requirements, facts, decisions, and tests`,
+    ].filter((part) => part !== undefined);
+    lines.push(`Next layer: ${next.join("; ")}.`);
+    if (surface === "edit") {
+        lines.push(`Behavior changes here are traced to these requirements; kb_check({sourceFiles:[${jsonString(relativePath)}], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) reports ownership drift after the edit.`);
+    }
+    return truncate(lines.join("\n"), input.maxChars ?? MAX_SNIPPET_CHARS);
+}
+// implements REQ-claude-code-kibi-plugin-v1
+/**
+ * One-line focus update for a file whose snippet was already shown this
+ * session: only the new fact (which symbol the edit lands in) is repeated.
+ */
+export function focusUpdate(relativePath, symbols, focus) {
+    const symbol = focusedSymbols(symbols, focus)[0];
+    if (!symbol)
+        return undefined;
+    const owners = symbol.implements.length > 0
+        ? `, which implements ${formatList(symbol.implements, 2)}`
+        : "";
+    return `Kibi: this edit to ${relativePath} is inside ${symbol.title}${owners}.`;
+}
+// implements REQ-agent-core-edit-snippets, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/**
+ * Pre-edit context for hosts without their own snippet memory: the shared
+ * edit snippet for each linked file the call targets, shown once per file per
+ * session, at most `maxFiles` per call.
+ */
+export function editKnowledgeContext(input) {
+    const snippets = [];
+    for (const relativePath of new Set(input.relativePaths)) {
+        if (snippets.length >= (input.maxFiles ?? 3))
+            break;
+        const symbols = input.symbolsFor(relativePath);
+        if (symbols.length === 0)
+            continue;
+        const snippet = fileKnowledgeSnippet({
+            relativePath,
+            symbols,
+            surface: "edit",
+            focus: input.focusFor?.(relativePath),
+            summarize: input.summarize,
+            maxChars: input.maxChars,
+        });
+        if (!snippet)
+            continue;
+        const key = `${input.sessionId ?? ""}\u0000edit\u0000${relativePath}`;
+        if (!claimSnippetSlot(input.stateDir, key))
+            continue;
+        snippets.push(snippet);
+    }
+    return snippets.length > 0 ? snippets.join("\n\n") : undefined;
+}
+// implements REQ-agent-core-edit-snippets, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/**
+ * Claim the one-time slot for `key` under `stateDir`: true the first time a
+ * key is claimed, false afterwards. The marker is created exclusively, so
+ * hooks for parallel tool calls never both show the same snippet. Without a
+ * state directory every call is a first time.
+ */
+export function claimSnippetSlot(stateDir, key) {
+    if (!stateDir)
+        return true;
+    const marker = path.join(stateDir, "shown-snippets", createHash("sha256").update(key).digest("hex").slice(0, 32));
+    try {
+        fs.mkdirSync(path.dirname(marker), { recursive: true });
+        fs.writeFileSync(marker, "", { flag: "wx" });
+        return true;
+    }
+    catch {
+        // An existing marker means the snippet was already shown; an unwritable
+        // state directory also stays quiet rather than repeating the snippet on
+        // every call.
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./hook-usage-log": {
+      "types": "./dist/hook-usage-log.d.ts",
+      "default": "./dist/hook-usage-log.js"
+    },
     "./kb-mcp-tools": {
       "types": "./dist/kb-mcp-tools.d.ts",
       "default": "./dist/kb-mcp-tools.js"
@@ -21,6 +25,10 @@
     "./path-policy": {
       "types": "./dist/path-policy.d.ts",
       "default": "./dist/path-policy.js"
+    },
+    "./snippets": {
+      "types": "./dist/snippets.d.ts",
+      "default": "./dist/snippets.js"
     }
   },
   "files": ["dist", "CHANGELOG.md"],
@@ -34,9 +42,14 @@
   },
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",
+  "homepage": "https://looted.github.io/kibi/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Looted/kibi.git"
+    "url": "https://github.com/Looted/kibi.git",
+    "directory": "packages/agent-core"
+  },
+  "bugs": {
+    "url": "https://github.com/Looted/kibi/issues"
   },
   "publishConfig": {
     "access": "public"