@justestif/pk 0.1.13 → 0.2.0

package/README.md

@@ -30,38 +30,39 @@ Non-interactive:
 
 ```bash
 pk init my-project --harness claude
-pk init my-project --harness claude,omp,cursor   # multiple harnesses
+pk init my-project --harness claude,omp   # multiple harnesses
 ```
 
-Available harnesses: `claude`, `claude-desktop`, `omp`, `cursor`, `opencode`, `codex`.
+Available harnesses: `claude` (Claude Code), `omp` (Oh My Pi), `cursor` (Cursor), `gemini` (Gemini CLI), `codex` (Codex), `opencode` (OpenCode).
 
 `pk init` does three things:
 
 1. Creates `~/.pk/<name>/` as the knowledge home for this project
 2. Writes an MCP server config so your harness discovers `pk mcp`
-3. Copies the `pk` skill to the harness skill directory (where supported)
+3. Installs a harness adapter that calls `pk prime` at session start to inject the skill into context
 
-| Harness | Config file written |
+| Harness | Files written |
 |---|---|
-| `claude` | `.mcp.json` (project root) |
-| `claude-desktop` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| `cursor` | `.cursor/mcp.json` |
-| `omp` | `.omp/mcp.json` |
-| `opencode` | `opencode.json` |
-| `codex` | `.codex/config.toml` |
+| `claude` | `.mcp.json`, `CLAUDE.md`, `.claude/hooks/pk-eval.ts`, `.claude/settings.json` |
+| `omp` | `.omp/mcp.json`, `AGENTS.md`, `.omp/extensions/pk-eval.ts` |
+| `cursor` | `.cursor/mcp.json`, `.cursor/rules/pk.mdc`, `.cursor/hooks/pk-eval.sh`, `.cursor/hooks.json` |
+| `gemini` | `.gemini/settings.json`, `GEMINI.md`, `.gemini/hooks/pk-eval.sh` |
+| `codex` | `.codex/config.toml`, `AGENTS.md`, `.codex/hooks/pk-eval.sh`, `.codex/hooks.json` |
+| `opencode` | `opencode.json`, `AGENTS.md`, `CLAUDE.md`, `.opencode/plugins/pk-eval.ts` |
 
 ## How it works
 
-`pk mcp` runs a stdio MCP server that exposes four tools to any connected agent:
+`pk mcp` runs a stdio MCP server that exposes five tools to any connected agent:
 
 | Tool | What it does |
 |---|---|
 | `pk_search` | Full-text search over the knowledge base (BM25, porter stemming) |
-| `pk_synthesize` | Summarise notes matching a query or the whole base |
-| `pk_new` | Create a new note (type, title, tags, body) |
+| `pk_synthesize` | Ranked context dump — by query, session start, or all notes |
+| `pk_read` | Read the full content of a note by path |
+| `pk_new` | Create a new typed note skeleton, returns path to fill in |
 | `pk_lint` | Validate all notes for schema and quality rules |
 
-The agent calls these tools directly — no hooks, no shell extensions, no prompt injection.
+The agent calls these tools directly — no hooks, no shell extensions, no prompt injection. Agents should never read or write knowledge files directly.
 
 ## Commands
 
@@ -102,8 +103,8 @@ pk synthesize
 
 ## Knowledge structure
 
-Notes live in `~/.pk/<name>/` as plain markdown files — human-editable,
-git-diffable, readable without any tool.
+Notes live in `~/.pk/<name>/` as plain markdown files — human-editable and git-diffable.
+Agents access them exclusively through the MCP tools; humans can read and edit them directly.
 
 ```
 ~/.pk/

package/dist/index.js

@@ -17713,7 +17713,7 @@ var {
 var package_default = {
   name: "@justestif/pk",
   type: "module",
-  version: "0.1.13",
+  version: "0.2.0",
   description: "Project knowledge \u2014 structured intake, search, and recall",
   bin: {
     pk: "dist/index.js"
@@ -32791,60 +32791,47 @@ function registerLint(program2) {
 }
 
 // src/lib/config.ts
-import {
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync3,
-  readFileSync,
-  writeFileSync
-} from "fs";
+import { mkdirSync as mkdirSync3 } from "fs";
 import path6 from "path";
 import os2 from "os";
 var DEFAULT = { auto_commit: true, embedding: "" };
 function configPath() {
   return path6.join(os2.homedir(), ".pk", "config.json");
 }
-function loadConfig() {
+async function loadConfig() {
   const p = configPath();
-  if (!existsSync3(p)) {
-    return { ...DEFAULT };
-  }
   try {
-    const merged = { ...DEFAULT, ...JSON.parse(readFileSync(p, "utf8")) };
+    const text = await Bun.file(p).text();
+    const merged = { ...DEFAULT, ...JSON.parse(text) };
     return merged;
   } catch {
     return { ...DEFAULT };
   }
 }
-function saveConfig(config2) {
+async function saveConfig(config2) {
   const p = configPath();
   mkdirSync3(path6.dirname(p), { recursive: true });
-  writeFileSync(p, JSON.stringify(config2, null, 2) + `
+  await Bun.write(p, JSON.stringify(config2, null, 2) + `
 `);
 }
 
 // src/commands/config-cmd.ts
 function registerConfig(program2) {
-  program2.command("config").description("Show or update pk configuration (~/.pk/config.json)").option("--auto-commit <bool>", "Auto-commit knowledge operations (true/false)").option("--embedding <model>", "Embedding model (empty to disable)").action((opts) => {
-    const config2 = loadConfig();
+  program2.command("config").description("Show or update pk configuration (~/.pk/config.json)").option("--auto-commit <bool>", "Auto-commit knowledge operations (true/false)").option("--embedding <model>", "Embedding model (empty to disable)").action(async (opts) => {
+    const config2 = await loadConfig();
     if (opts.autoCommit !== undefined) {
       config2.auto_commit = opts.autoCommit === "true";
     }
     if (opts.embedding !== undefined) {
       config2.embedding = opts.embedding;
     }
-    saveConfig(config2);
+    await saveConfig(config2);
     console.log(JSON.stringify(config2, null, 2));
   });
 }
 
 // src/commands/init.ts
-import {
-  cpSync,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync2,
-  writeFileSync as writeFileSync2
-} from "fs";
+import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync4 } from "fs";
 import os3 from "os";
 import path7 from "path";
 
@@ -34125,28 +34112,28 @@ ${c2}
 
 // src/commands/init.ts
 var HARNESSES = [
-  { hint: ".mcp.json in project root", label: "Claude Code", value: "claude" },
-  { hint: "~/Library/\u2026/claude_desktop_config.json", label: "Claude Desktop", value: "claude-desktop" },
-  { hint: ".cursor/mcp.json in project root", label: "Cursor", value: "cursor" },
-  { hint: ".omp/mcp.json in project root", label: "Oh My Pi", value: "omp" },
-  { hint: "opencode.json in project root", label: "OpenCode", value: "opencode" },
-  { hint: ".codex/config.toml in project root", label: "Codex CLI", value: "codex" }
+  { hint: ".mcp.json + CLAUDE.md + forced-eval hook", label: "Claude Code", value: "claude" },
+  { hint: ".omp/mcp.json + AGENTS.md + forced-eval hook", label: "Oh My Pi", value: "omp" },
+  { hint: ".cursor/mcp.json + .cursor/rules/pk.mdc + hook", label: "Cursor", value: "cursor" },
+  { hint: ".gemini/settings.json + GEMINI.md + hook", label: "Gemini CLI", value: "gemini" },
+  { hint: ".codex/config.toml + AGENTS.md + hook", label: "Codex", value: "codex" },
+  { hint: "opencode.json + plugin (reads AGENTS.md/CLAUDE.md)", label: "OpenCode", value: "opencode" }
 ];
 var HARNESS_VALUES = new Set(HARNESSES.map((h2) => h2.value));
 var HARNESS_ACTIVATION = {
   claude: "start a new Claude Code session in this project",
-  "claude-desktop": "quit and restart Claude Desktop",
-  codex: "restart the Codex CLI",
-  cursor: "reload the Cursor window (Cmd+Shift+P \u2192 Reload Window)",
   omp: "restart your Oh My Pi session",
-  opencode: "restart opencode"
+  cursor: "restart Cursor for changes to take effect",
+  gemini: "restart your Gemini CLI session",
+  codex: "restart Codex for MCP to connect",
+  opencode: "reload OpenCode or restart the app"
 };
 function buildOutro(created, knowledgeDir, harnesses, skillPaths) {
   const lines = [
     created ? `Created project: ${knowledgeDir}` : `Connected to existing project: ${knowledgeDir}`
   ];
   for (const h2 of harnesses) {
-    lines.push(`  ${h2}: MCP config written \u2192 ${HARNESS_ACTIVATION[h2]}`);
+    lines.push(`  ${h2}: configured \u2192 ${HARNESS_ACTIVATION[h2]}`);
   }
   for (const sp of skillPaths) {
     lines.push(`  skill installed to ${sp}`);
@@ -34172,102 +34159,289 @@ function pkMcpEntry(knowledgeDir) {
     env: { PK_KNOWLEDGE_DIR: knowledgeDir }
   };
 }
-function readJson(filePath) {
-  if (!existsSync4(filePath)) {
-    return {};
-  }
+async function readJson(filePath) {
   try {
-    return JSON.parse(readFileSync2(filePath, "utf8"));
+    return JSON.parse(await Bun.file(filePath).text());
   } catch {
     return {};
   }
 }
-function writeJson(filePath, data) {
+async function writeJson(filePath, data) {
   mkdirSync4(path7.dirname(filePath), { recursive: true });
-  writeFileSync2(filePath, JSON.stringify(data, null, 2) + `
+  await Bun.write(filePath, JSON.stringify(data, null, 2) + `
 `);
 }
-function writeClaudeConfig(projectRoot, _name, knowledgeDir) {
+async function writeClaudeConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, ".mcp.json");
-  const cfg = readJson(cfgPath);
+  const cfg = await readJson(cfgPath);
   const servers = cfg.mcpServers ?? {};
   servers.pk = pkMcpEntry(knowledgeDir);
   cfg.mcpServers = servers;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
 }
-function writeClaudeDesktopConfig(homeDir, name, knowledgeDir) {
-  const cfgPath = path7.join(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  const cfg = readJson(cfgPath);
+async function writeOmpConfig(projectRoot, _name, knowledgeDir) {
+  const cfgPath = path7.join(projectRoot, ".omp", "mcp.json");
+  const cfg = await readJson(cfgPath);
   const servers = cfg.mcpServers ?? {};
-  servers[`pk-${name}`] = pkMcpEntry(knowledgeDir);
+  servers.pk = pkMcpEntry(knowledgeDir);
   cfg.mcpServers = servers;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
+}
+var PK_SECTION_START = "<!-- pk:start -->";
+var PK_SECTION_END = "<!-- pk:end -->";
+var PK_INSTRUCTION = `## pk \u2014 project knowledge
+
+Use the pk skill and its MCP tools (pk_synthesize, pk_search, pk_read, pk_new, pk_lint) to manage project knowledge for this project. Run pk_synthesize({ sessionStart: true }) at the start of every session.`;
+async function writeInstructionSection(filePath, content) {
+  const section = `${PK_SECTION_START}
+${content}
+${PK_SECTION_END}
+`;
+  let existing = "";
+  try {
+    existing = await Bun.file(filePath).text();
+  } catch {}
+  const startIdx = existing.indexOf(PK_SECTION_START);
+  const endIdx = existing.indexOf(PK_SECTION_END);
+  let updated;
+  if (startIdx !== -1 && endIdx !== -1) {
+    updated = existing.slice(0, startIdx) + section + existing.slice(endIdx + PK_SECTION_END.length + 1);
+  } else {
+    updated = existing ? existing.trimEnd() + `
+
+` + section : section;
+  }
+  mkdirSync4(path7.dirname(filePath), { recursive: true });
+  await Bun.write(filePath, updated);
+}
+async function writeClaudeMd(projectRoot) {
+  await writeInstructionSection(path7.join(projectRoot, "CLAUDE.md"), PK_INSTRUCTION);
+}
+async function writeAgentsMd(projectRoot) {
+  await writeInstructionSection(path7.join(projectRoot, "AGENTS.md"), PK_INSTRUCTION);
+}
+var FORCED_EVAL_PROMPT = "SKILL EVALUATION REQUIRED: Before responding, explicitly decide YES or NO" + " \u2014 does this request involve project work, investigation, decisions, or knowledge capture" + " where the pk skill applies? If YES, activate the pk skill, then proceed.";
+function claudeHookScript() {
+  return `// pk forced-eval hook \u2014 auto-generated by pk init
+async function handleUserPromptSubmit() {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: ${JSON.stringify(FORCED_EVAL_PROMPT)},
+    },
+    suppressOutput: true,
+  }));
+}
+
+handleUserPromptSubmit().catch(() => process.exit(0));
+`;
+}
+async function writeClaudeHook(projectRoot) {
+  const hookDir = path7.join(projectRoot, ".claude", "hooks");
+  const hookPath = path7.join(hookDir, "pk-eval.ts");
+  mkdirSync4(hookDir, { recursive: true });
+  await Bun.write(hookPath, claudeHookScript());
+  const settingsPath = path7.join(projectRoot, ".claude", "settings.json");
+  const settings = await readJson(settingsPath);
+  const hooks = settings.hooks ?? {};
+  const ups = hooks.UserPromptSubmit ?? [];
+  const hookCmd = `bun run ${hookPath}`;
+  if (!ups.some((h2) => h2.command === hookCmd)) {
+    ups.push({ command: hookCmd });
+  }
+  hooks.UserPromptSubmit = ups;
+  settings.hooks = hooks;
+  await writeJson(settingsPath, settings);
+}
+function ompHookScript() {
+  return `// pk forced-eval hook \u2014 auto-generated by pk init
+import type {HookAPI} from '@oh-my-pi/pi-coding-agent/extensibility/hooks';
+
+export default function (pi: HookAPI) {
+  pi.on('before_agent_start', (event: {systemPrompt?: string}) => ({
+    systemPrompt: ${JSON.stringify(FORCED_EVAL_PROMPT)} + '\\n\\n' + (event.systemPrompt ?? ''),
+  }));
+}
+`;
+}
+async function writeOmpHook(projectRoot) {
+  const hookPath = path7.join(projectRoot, ".omp", "extensions", "pk-eval.ts");
+  mkdirSync4(path7.dirname(hookPath), { recursive: true });
+  await Bun.write(hookPath, ompHookScript());
 }
-function writeCursorConfig(projectRoot, _name, knowledgeDir) {
+async function writeCursorConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, ".cursor", "mcp.json");
-  const cfg = readJson(cfgPath);
+  const cfg = await readJson(cfgPath);
   const servers = cfg.mcpServers ?? {};
   servers.pk = pkMcpEntry(knowledgeDir);
   cfg.mcpServers = servers;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
 }
-function writeOmpConfig(projectRoot, _name, knowledgeDir) {
-  const cfgPath = path7.join(projectRoot, ".omp", "mcp.json");
-  const cfg = readJson(cfgPath);
+async function writeCursorRules(projectRoot) {
+  const rulesPath = path7.join(projectRoot, ".cursor", "rules", "pk.mdc");
+  const content = `---
+description: "pk knowledge base integration"
+alwaysApply: true
+---
+
+${PK_INSTRUCTION}
+`;
+  mkdirSync4(path7.dirname(rulesPath), { recursive: true });
+  await Bun.write(rulesPath, content);
+}
+function cursorHookScript() {
+  return `#!/bin/bash
+# pk forced-eval hook \u2014 auto-generated by pk init
+# Exit 0 to allow, exit 2 to block
+
+# Return the forced-eval prompt as additional context
+cat <<EOF
+{
+  "continue": true,
+  "additionalContext": ${JSON.stringify(FORCED_EVAL_PROMPT)}
+}
+EOF
+`;
+}
+async function writeCursorHook(projectRoot) {
+  const hookPath = path7.join(projectRoot, ".cursor", "hooks", "pk-eval.sh");
+  mkdirSync4(path7.dirname(hookPath), { recursive: true });
+  await Bun.write(hookPath, cursorHookScript());
+  const hooksPath = path7.join(projectRoot, ".cursor", "hooks.json");
+  const hooks = await readJson(hooksPath);
+  const hooksObj = hooks.hooks ?? {};
+  const bsp = hooksObj.beforeSubmitPrompt ?? [];
+  if (!bsp.some((h2) => h2.command === hookPath)) {
+    bsp.push({ command: hookPath });
+  }
+  hooksObj.beforeSubmitPrompt = bsp;
+  hooks.hooks = hooksObj;
+  await writeJson(hooksPath, hooks);
+}
+async function writeGeminiConfig(projectRoot, _name, knowledgeDir) {
+  const cfgPath = path7.join(projectRoot, ".gemini", "settings.json");
+  const cfg = await readJson(cfgPath);
   const servers = cfg.mcpServers ?? {};
   servers.pk = pkMcpEntry(knowledgeDir);
   cfg.mcpServers = servers;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
+}
+async function writeGeminiMd(projectRoot) {
+  await writeInstructionSection(path7.join(projectRoot, "GEMINI.md"), PK_INSTRUCTION);
 }
-function writeOpenCodeConfig(projectRoot, _name, knowledgeDir) {
+function geminiHookScript() {
+  return `#!/bin/bash
+# pk forced-eval hook \u2014 auto-generated by pk init
+# Output JSON to stdout with the forced-eval prompt
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "BeforeAgent",
+    "additionalContext": ${JSON.stringify(FORCED_EVAL_PROMPT)}
+  }
+}
+EOF
+`;
+}
+async function writeGeminiHook(projectRoot) {
+  const hookPath = path7.join(projectRoot, ".gemini", "hooks", "pk-eval.sh");
+  mkdirSync4(path7.dirname(hookPath), { recursive: true });
+  await Bun.write(hookPath, geminiHookScript());
+  const cfgPath = path7.join(projectRoot, ".gemini", "settings.json");
+  const cfg = await readJson(cfgPath);
+  const hooks = cfg.hooks ?? {};
+  const beforeAgent = hooks.BeforeAgent ?? [];
+  if (!beforeAgent.some((h2) => h2.command === hookPath)) {
+    beforeAgent.push({ command: hookPath });
+  }
+  hooks.BeforeAgent = beforeAgent;
+  cfg.hooks = hooks;
+  await writeJson(cfgPath, cfg);
+}
+async function writeToml(filePath, content) {
+  mkdirSync4(path7.dirname(filePath), { recursive: true });
+  await Bun.write(filePath, content);
+}
+async function writeCodexConfig(projectRoot, _name, knowledgeDir) {
+  const cfgPath = path7.join(projectRoot, ".codex", "config.toml");
+  const pkCmd = resolvePkCommand();
+  const toml = `[mcp_servers.pk]
+command = "${pkCmd}"
+args = ["mcp"]
+env = { PK_KNOWLEDGE_DIR = "${knowledgeDir}" }
+`;
+  await writeToml(cfgPath, toml);
+}
+function codexHookScript() {
+  return `#!/bin/bash
+# pk forced-eval hook \u2014 auto-generated by pk init
+# Output JSON to stdout
+
+cat <<EOF
+{
+  "continue": true,
+  "suppressOutput": false
+}
+EOF
+`;
+}
+async function writeCodexHook(projectRoot) {
+  const hookPath = path7.join(projectRoot, ".codex", "hooks", "pk-eval.sh");
+  mkdirSync4(path7.dirname(hookPath), { recursive: true });
+  await Bun.write(hookPath, codexHookScript());
+  const hooksPath = path7.join(projectRoot, ".codex", "hooks.json");
+  const hooks = await readJson(hooksPath);
+  const hooksObj = hooks.hooks ?? {};
+  const ups = hooksObj.UserPromptSubmit ?? [];
+  if (!ups.some((h2) => typeof h2 === "object" && h2 !== null && ("command" in h2) && typeof h2.command === "string" && h2.command.includes("pk-eval"))) {
+    ups.push({ command: hookPath });
+  }
+  hooksObj.UserPromptSubmit = ups;
+  hooks.hooks = hooksObj;
+  await writeJson(hooksPath, hooks);
+}
+async function writeOpenCodeConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, "opencode.json");
-  const cfg = readJson(cfgPath);
+  const cfg = await readJson(cfgPath);
   const mcp = cfg.mcp ?? {};
-  mcp.pk = pkMcpEntry(knowledgeDir);
+  const pkCmd = resolvePkCommand();
+  mcp.pk = {
+    type: "local",
+    enabled: true,
+    command: [pkCmd, "mcp"],
+    environment: { PK_KNOWLEDGE_DIR: knowledgeDir }
+  };
   cfg.mcp = mcp;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
+}
+function openCodePluginScript() {
+  return `// pk forced-eval plugin \u2014 auto-generated by pk init
+export const experimental = {
+   async 'chat.system.transform'({ system }: { system: string[] }): Promise<void> {
+      system.unshift(${JSON.stringify(FORCED_EVAL_PROMPT)});
+   },
+};
+`;
 }
-function writeCodexConfig(projectRoot, _name, knowledgeDir) {
-  const cfgPath = path7.join(projectRoot, ".codex", "config.toml");
-  const toml = [
-    "[mcp_servers.pk]",
-    `command = "${resolvePkCommand()}"`,
-    'args = ["mcp"]',
-    "",
-    "[mcp_servers.pk.env]",
-    `PK_KNOWLEDGE_DIR = "${knowledgeDir}"`,
-    ""
-  ].join(`
-`);
-  if (existsSync4(cfgPath)) {
-    const existing = readFileSync2(cfgPath, "utf8");
-    if (existing.includes("[mcp_servers.pk]")) {
-      return;
-    }
-    mkdirSync4(path7.dirname(cfgPath), { recursive: true });
-    writeFileSync2(cfgPath, existing.trimEnd() + `
-
-` + toml);
-  } else {
-    mkdirSync4(path7.dirname(cfgPath), { recursive: true });
-    writeFileSync2(cfgPath, toml);
-  }
+async function writeOpenCodePlugin(projectRoot) {
+  const pluginPath = path7.join(projectRoot, ".opencode", "plugins", "pk-eval.ts");
+  mkdirSync4(path7.dirname(pluginPath), { recursive: true });
+  await Bun.write(pluginPath, openCodePluginScript());
 }
 function skillTargetDir(harness, projectRoot) {
   switch (harness) {
-    case "claude":
-    case "claude-desktop": {
+    case "claude": {
       return path7.join(os3.homedir(), ".claude", "skills", "pk");
     }
-    case "omp": {
+    case "omp":
+    case "cursor":
+    case "gemini":
+    case "opencode": {
       return path7.join(projectRoot, ".agents", "skills", "pk");
     }
-    case "cursor": {
-      return path7.join(projectRoot, ".cursor", "skills", "pk");
-    }
-    case "opencode":
     case "codex": {
-      return "";
+      return path7.join(os3.homedir(), ".codex", "skills", "pk");
     }
   }
 }
@@ -34280,61 +34454,72 @@ function installSkill(harness, projectRoot) {
     return "";
   }
   const src = skillSourceDir();
-  if (!existsSync4(src)) {
+  if (!existsSync3(src)) {
     return "";
   }
-  if (existsSync4(target)) {
+  if (existsSync3(target)) {
     return target;
   }
   cpSync(src, target, { recursive: true });
   return target;
 }
-function ensureProject(name) {
+async function ensureProject(name) {
   const kDir = projectDir(name);
-  const alreadyExists = existsSync4(kDir);
+  const alreadyExists = existsSync3(kDir);
   for (const dir of Object.values(TYPE_DIRS)) {
     mkdirSync4(path7.join(kDir, dir), { recursive: true });
   }
   const gi = path7.join(kDir, ".gitignore");
-  if (!existsSync4(gi)) {
-    writeFileSync2(gi, `.index.db
+  if (!existsSync3(gi)) {
+    await Bun.write(gi, `.index.db
 `);
   }
   return { created: !alreadyExists, knowledgeDir: kDir };
 }
-function applyHarness(harness, ctx) {
-  const { name, knowledgeDir, projectRoot, home } = ctx;
+async function applyHarness(harness, ctx) {
+  const { name, knowledgeDir, projectRoot } = ctx;
   switch (harness) {
     case "claude": {
-      writeClaudeConfig(projectRoot, name, knowledgeDir);
+      await writeClaudeConfig(projectRoot, name, knowledgeDir);
+      await writeClaudeMd(projectRoot);
+      await writeClaudeHook(projectRoot);
       break;
     }
-    case "claude-desktop": {
-      writeClaudeDesktopConfig(home, name, knowledgeDir);
+    case "omp": {
+      await writeOmpConfig(projectRoot, name, knowledgeDir);
+      await writeAgentsMd(projectRoot);
+      await writeOmpHook(projectRoot);
       break;
     }
-    case "codex": {
-      writeCodexConfig(projectRoot, name, knowledgeDir);
+    case "cursor": {
+      await writeCursorConfig(projectRoot, name, knowledgeDir);
+      await writeCursorRules(projectRoot);
+      await writeCursorHook(projectRoot);
       break;
     }
-    case "cursor": {
-      writeCursorConfig(projectRoot, name, knowledgeDir);
+    case "gemini": {
+      await writeGeminiConfig(projectRoot, name, knowledgeDir);
+      await writeGeminiMd(projectRoot);
+      await writeGeminiHook(projectRoot);
       break;
     }
-    case "omp": {
-      writeOmpConfig(projectRoot, name, knowledgeDir);
+    case "codex": {
+      await writeCodexConfig(projectRoot, name, knowledgeDir);
+      await writeAgentsMd(projectRoot);
+      await writeCodexHook(projectRoot);
       break;
     }
     case "opencode": {
-      writeOpenCodeConfig(projectRoot, name, knowledgeDir);
+      await writeOpenCodeConfig(projectRoot, name, knowledgeDir);
+      await writeAgentsMd(projectRoot);
+      await writeClaudeMd(projectRoot);
+      await writeOpenCodePlugin(projectRoot);
       break;
     }
   }
 }
-function applyHarnesses(harnesses, ctx) {
-  for (const h2 of harnesses) {
-    applyHarness(h2, ctx);
-  }
+async function applyHarnesses(harnesses, ctx) {
+  await Promise.all(harnesses.map(async (h2) => applyHarness(h2, ctx)));
   const seen = new Set;
   const installed = [];
   for (const h2 of harnesses) {
@@ -34361,14 +34546,14 @@ function registerInit(program2) {
       flagHarnesses = result;
     }
     if (nameArg && flagHarnesses) {
-      const { created: created2, knowledgeDir: knowledgeDir2 } = ensureProject(nameArg);
+      const { created: created2, knowledgeDir: knowledgeDir2 } = await ensureProject(nameArg);
       const ctx2 = {
         home,
         knowledgeDir: knowledgeDir2,
         name: nameArg,
         projectRoot
       };
-      const skillPaths2 = applyHarnesses(flagHarnesses, ctx2);
+      const skillPaths2 = await applyHarnesses(flagHarnesses, ctx2);
       console.log(buildOutro(created2, knowledgeDir2, flagHarnesses, skillPaths2).join(`
 `));
       return;
@@ -34424,14 +34609,14 @@ function registerInit(program2) {
       }
       harnesses = picked;
     }
-    const { created, knowledgeDir } = ensureProject(name);
+    const { created, knowledgeDir } = await ensureProject(name);
     const ctx = {
       home,
       knowledgeDir,
       name,
       projectRoot
     };
-    const skillPaths = applyHarnesses(harnesses, ctx);
+    const skillPaths = await applyHarnesses(harnesses, ctx);
     ye(buildOutro(created, knowledgeDir, harnesses, skillPaths).join(`
 `));
   });
@@ -42919,6 +43104,7 @@ function createPkMcpServer() {
     const dir = requireKnowledgeDir();
     try {
       const outPath = await createNote(dir, type, title, tags ?? "");
+      await rebuild(dir);
       return { content: [{ type: "text", text: outPath }] };
     } catch (error51) {
       return {
@@ -42927,6 +43113,29 @@ function createPkMcpServer() {
       };
     }
   });
+  server.registerTool("pk_read", {
+    description: "Read the full content of a knowledge note by its path. Use paths returned by pk_search or pk_synthesize.",
+    inputSchema: {
+      path: exports_external.string().describe("Absolute path to the note file, as returned by pk_search or pk_synthesize")
+    }
+  }, async ({ path: notePath }) => {
+    const dir = requireKnowledgeDir();
+    if (!notePath.startsWith(dir)) {
+      return {
+        content: [{ type: "text", text: `Path must be inside the knowledge directory: ${dir}` }],
+        isError: true
+      };
+    }
+    try {
+      const text = await Bun.file(notePath).text();
+      return { content: [{ type: "text", text }] };
+    } catch {
+      return {
+        content: [{ type: "text", text: `File not found: ${notePath}` }],
+        isError: true
+      };
+    }
+  });
   server.registerTool("pk_lint", {
     description: "Validate knowledge note structure and frontmatter. Returns lint issues grouped by severity.",
     inputSchema: {}
@@ -42958,6 +43167,18 @@ function registerMcp(program2) {
   });
 }
 
+// src/commands/prime.ts
+import path8 from "path";
+function skillPath() {
+  return path8.resolve(import.meta.dir, "..", "skill", "SKILL.md");
+}
+function registerPrime(program2) {
+  program2.command("prime").description("Print the pk skill to stdout \u2014 used by harness adapters to inject into system prompt at session start").action(async () => {
+    const text = await Bun.file(skillPath()).text();
+    process.stdout.write(text.replace(/^---[\s\S]*?---\n/v, ""));
+  });
+}
+
 // src/index.ts
 var program2 = new Command().name("pk").description("Project knowledge \u2014 structured intake, search, and recall").version(package_default.version);
 registerNew(program2);
@@ -42970,4 +43191,5 @@ registerInit(program2);
 registerInstructions(program2);
 registerVocab(program2);
 registerMcp(program2);
+registerPrime(program2);
 program2.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@justestif/pk",
    "type": "module",
-   "version": "0.1.13",
+   "version": "0.2.0",
    "description": "Project knowledge — structured intake, search, and recall",
    "bin": {
       "pk": "dist/index.js"

package/skill/SKILL.md

@@ -5,43 +5,87 @@ description: "Load when maintaining project knowledge, capturing decisions or qu
 
 # pk
 
-Structured project knowledge — intake, search, recall, and audit over `knowledge/`.
+Structured project knowledge — intake, search, recall, and audit.
+
+**Search, synthesis, creation, and validation go through MCP tools. Writing note body content uses your standard file Edit tool — but only on paths returned by `pk_new` or `pk_search`, never by navigating the filesystem yourself.**
 
 ## Tools
 
-| Task | Tool |
-|---|---|
-| Search notes | `pk_search` |
-| Context dump / session start | `pk_synthesize` |
-| Create a note | `pk_new` |
-| Validate structure | `pk_lint` |
+### `pk_synthesize` — orient before any investigation
+
+```
+pk_synthesize({ sessionStart: true })                          # open questions + accepted decisions + active notes
+pk_synthesize({ query: "auth flow" })                         # ranked context for a topic
+pk_synthesize({ query: "auth", type: "decision", limit: 5 })
+```
+
+Returns formatted markdown with title, type, status, tags, and an excerpt per note. Use `sessionStart: true` at the start of every session.
+
+### `pk_search` — locate notes by content
+
+```
+pk_search({ query: "database schema" })
+pk_search({ query: "api", type: "question", status: "open" })
+pk_search({ query: "deploy", tag: "infra", limit: 5 })
+```
+
+Returns `[{ path, type, status, title, tags, snippet }]`. Always call before `pk_new` — duplicates erode trust faster than gaps do.
+
+### `pk_read` — full note body
+
+```
+pk_read({ path: "/abs/path/returned/by/pk_search" })
+```
+
+Returns complete file contents including frontmatter. Use paths from `pk_search` or `pk_synthesize` output.
+
+### `pk_new` — create a typed note skeleton
+
+```
+pk_new({ type: "note", title: "Auth token expiry behaviour", tags: "auth,security" })
+pk_new({ type: "decision", title: "Use JWT over sessions" })
+pk_new({ type: "question", title: "Should we rate-limit the search endpoint?" })
+pk_new({ type: "source", title: "Meeting notes 2024-06-01" })
+```
+
+Returns the absolute path. Frontmatter (id, dates, status, tags as YAML array) is generated automatically from your inputs — you don't edit frontmatter after creation. After receiving the path: call `pk_read` to see the skeleton, then use your standard file Edit tool to fill in the required sections.
+
+**Required sections by type:**
+- `note` → `## Summary`, `## Details`, `## Evidence`, `## Related`
+- `decision` → `## Decision`, `## Context`, `## Rationale`, `## Consequences`, `## Related`
+- `question` → `## Question`, `## Why It Matters`, `## Current Understanding`, `## Resolution`
+- `source` → `## Source`, `## Raw Material`, `## Extracted Items`
+
+**`source` vs `note`:** `source` = raw/provenance-heavy input (meeting notes, transcripts, external docs, unprocessed data). `note` = stable synthesised fact or constraint you've derived. When synthesising across multiple sources into one insight: create a `note` and put source paths in `## Evidence`.
+
+### `pk_lint` — validate before committing
 
-## Intake
+```
+pk_lint({})
+```
 
-**Search before creating** — always call `pk_search` first.
+**Errors block commits** (missing frontmatter, duplicate id, wrong folder, missing required sections, broken links). **Warnings are advisory** (empty tags, note too long, source marked processed with no extracted items) — fix when practical, not required to commit.
 
-- Substantial messy input → `source`. Extract `note`, `decision`, `question` only when durable beyond this session.
-- Update existing when the match is obvious; otherwise create and link in body.
-- Call `pk_lint` before committing. Auto-commit coherent operations only when lint passes and no unrelated files are staged.
+### Status transitions
 
-## Asking
+No MCP tool for status changes. Use your file Edit tool directly on the frontmatter, fill in the resolution section, then lint.
 
-1. `pk_search` with the relevant query
-2. Read top results directly
-3. Answer with citations to note paths/IDs
-4. If silent or ambiguous, offer to create a `question` note
+**MANDATORY READ `references/knowledge-model.md`** when: creating a note type you haven't used before, unsure which folder a type belongs in, validating frontmatter fields, or unsure which status values are valid for a given type. (Read with your standard file Read tool — these are local skill files, not MCP-accessible.)
 
 ## NEVER
 
-- **Skip `pk_search` before creating** — duplicates erode trust in the knowledge base
-- **Dump raw input into durable notes** — preserve in `source`, extract selectively
-- **Silently merge related-but-different claims** — create and link instead
-- **Auto-commit when lint fails or unrelated files are staged**
+- **NEVER skip `pk_search` before `pk_new`**
+  **Why:** Duplicates silently fragment knowledge — two notes on the same topic never get reconciled, and future searches return noise.
+  **Instead:** Search first; update the existing note if found, or create and link if genuinely different.
 
-## References
+- **NEVER dump raw input into a `note` or `decision`**
+  **Why:** Durable note types are for stable, verified claims. Raw input contains noise, ambiguity, and provenance that decays poorly.
+  **Instead:** Create a `source` note, then extract `note`/`decision`/`question` entries from it selectively.
 
-Load only when the task requires it:
+- **NEVER silently overwrite a conflicting claim**
+  **Why:** Silent overwrites destroy the rationale trail — you lose why the old claim existed.
+  **Instead:** Create a new note explaining the conflict, link both, and use `status: superseded` on the old one.
 
-- `references/knowledge-model.md` — types, folders, frontmatter schema, required sections
-- `references/git-workflow.md` — commit policy, safety stops
-- `references/source-principles.md` — documentation governance
+- **NEVER commit when `pk_lint` returns errors or unrelated files are staged**
+  **Why:** Lint errors mean required structure is broken; mixed commits make knowledge changes unauditable.
+  **Instead:** Fix errors, unstage unrelated files, then commit.

package/skill/references/knowledge-model.md

@@ -4,17 +4,17 @@
 
 This system is project-specific. It is not a personal second brain, a full wiki platform, or a semantic memory database.
 
-The canonical store is plain markdown under `knowledge/`. Beans/issues remain for trackable work; the knowledge base is for durable context and future answers.
+The canonical store is plain markdown files managed via `pk` MCP tools. The root directory is set by `PK_KNOWLEDGE_DIR`. The knowledge base is for durable context and future answers — not for task tracking.
 
 ## Folder and Type Rules
 
-| Type | Folder | Purpose | Status values |
+| Type | Subfolder | Purpose | Status values |
 | --- | --- | --- | --- |
-| `source` | `knowledge/sources/` | Provenance and raw/lightly cleaned input | `unprocessed`, `processed`, `archived` |
-| `note` | `knowledge/notes/` | Durable project knowledge | `active`, `superseded`, `archived` |
-| `decision` | `knowledge/decisions/` | Chosen direction and rationale | `proposed`, `accepted`, `superseded` |
-| `question` | `knowledge/questions/` | Unresolved or resolved uncertainty | `open`, `answered`, `obsolete` |
-| `index` | `knowledge/indexes/` | Navigation/MOC pages | `active`, `archived` |
+| `source` | `sources/` | Provenance and raw/lightly cleaned input | `unprocessed`, `processed`, `archived` |
+| `note` | `notes/` | Durable project knowledge | `active`, `superseded`, `archived` |
+| `decision` | `decisions/` | Chosen direction and rationale | `proposed`, `accepted`, `superseded` |
+| `question` | `questions/` | Unresolved or resolved uncertainty | `open`, `answered`, `obsolete` |
+| `index` | `indexes/` | Navigation/MOC pages | `active`, `archived` |
 
 ## Frontmatter
 
@@ -34,7 +34,7 @@ tags: [tag-one, tag-two]
 
 Rules:
 
-- `id` must be unique across `knowledge/**/*.md`.
+- `id` must be unique across all notes in the knowledge directory.
 - `type` must match both status set and folder.
 - `tags` must be a flat list of lowercase slugs.
 - Do not use nested YAML, multiline YAML, or relationship arrays.
@@ -85,7 +85,7 @@ Classify extracted material this way:
 - Chosen path with rationale/consequences → `decision`
 - Unknown that blocks or informs work → `question`
 - Navigation over a topic/type/tag → `index`
-- Action item/task → issue tracker, not a knowledge note
+- Action item/task → not a knowledge note; track elsewhere
 - Low-signal commentary → ignore or keep only in `source`
 
 ## Update Policy

package/skill/assets/templates/decision.md

@@ -1,29 +0,0 @@
----
-id: decision-{{date}}-{{slug}}
-type: decision
-title: {{title}}
-created: {{date}}
-updated: {{date}}
-status: accepted
-tags: [{{tags}}]
----
-
-## Decision
-
-What was decided.
-
-## Context
-
-Why this decision came up.
-
-## Rationale
-
-Why this option won.
-
-## Consequences
-
-What this changes or constrains.
-
-## Related
-
-Links to source, questions, notes, or superseded decisions.

package/skill/assets/templates/index.md

@@ -1,25 +0,0 @@
----
-id: index-{{slug}}
-type: index
-title: {{title}}
-created: {{date}}
-updated: {{date}}
-status: active
-tags: [{{tags}}]
----
-
-## Purpose
-
-What this index helps navigate.
-
-## Key Links
-
-Curated links.
-
-## Open Questions
-
-Relevant unresolved questions.
-
-## Recent Changes
-
-Notable updates.

package/skill/assets/templates/note.md

@@ -1,25 +0,0 @@
----
-id: note-{{date}}-{{slug}}
-type: note
-title: {{title}}
-created: {{date}}
-updated: {{date}}
-status: active
-tags: [{{tags}}]
----
-
-## Summary
-
-One short paragraph.
-
-## Details
-
-Durable project knowledge.
-
-## Evidence
-
-Source links, files, quotes, or observations.
-
-## Related
-
-Links to related notes, decisions, or questions.

package/skill/assets/templates/question.md

@@ -1,25 +0,0 @@
----
-id: question-{{date}}-{{slug}}
-type: question
-title: {{title}}
-created: {{date}}
-updated: {{date}}
-status: open
-tags: [{{tags}}]
----
-
-## Question
-
-The unresolved question.
-
-## Why It Matters
-
-What decision or work this blocks or informs.
-
-## Current Understanding
-
-Known facts and candidate answers.
-
-## Resolution
-
-Answer once resolved.

package/skill/assets/templates/source.md

@@ -1,21 +0,0 @@
----
-id: source-{{date}}-{{slug}}
-type: source
-title: {{title}}
-created: {{date}}
-updated: {{date}}
-status: unprocessed
-tags: [{{tags}}]
----
-
-## Source
-
-Where this came from.
-
-## Raw Material
-
-Original or lightly cleaned content.
-
-## Extracted Items
-
-Links to notes, decisions, or questions created from this source.

package/skill/references/git-workflow.md

@@ -1,77 +0,0 @@
-# Git Workflow for Project Knowledge
-
-Git is the audit, safety, and review layer for `knowledge/`.
-
-## Before Modifying Knowledge
-
-Check repository state:
-
-```bash
-git status --short
-```
-
-Stop before editing if unrelated user changes would be mixed into the same commit. If changes are clearly knowledge-system work in scope, continue.
-
-## After Modifying Knowledge
-
-Run mechanical maintenance:
-
-```bash
-scripts/knowledge-index
-scripts/knowledge-lint
-```
-
-Review what changed:
-
-```bash
-git diff -- knowledge scripts/knowledge-* assets/templates hk.pkl
-```
-
-Summarize:
-
-- files created
-- files updated
-- generated indexes
-- lint result
-- any ignored/deferred material
-
-## Auto-Commit Policy
-
-Auto-commit coherent completed knowledge operations unless a safety stop applies.
-
-Normal intake commits stage only:
-
-```bash
-git add knowledge/
-```
-
-Knowledge-system implementation commits may stage:
-
-```bash
-git add knowledge/ scripts/knowledge-* assets/templates/ hk.pkl
-```
-
-Use concise commit messages:
-
-```txt
-knowledge: intake <topic>
-knowledge: update <topic>
-knowledge: answer <topic>
-knowledge-system: update <topic>
-```
-
-## Safety Stops
-
-Do not auto-commit when:
-
-- unrelated project files are modified
-- lint fails
-- the edit deletes or rewrites existing knowledge ambiguously
-- the working tree contains user changes outside the allowed commit boundary
-- the user says not to commit
-
-When stopped, report the exact reason and show the staged/unstaged state.
-
-## Hooks
-
-If hk is used, run `knowledge-lint` on pre-commit only when `knowledge/**/*.md` changes. Avoid every-N-commit scheduling; it is arbitrary and less transparent than change-triggered checks.