@justestif/pk 0.1.14 → 0.2.1

package/README.md

@@ -30,25 +30,24 @@ 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,cursor   # multiple harnesses
 ```
 
-Available harnesses: `claude`, `claude-desktop`, `omp`, `cursor`, `opencode`, `codex`.
+Available harnesses: `claude` (Claude Code & Claude Desktop), `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` | (also works for Claude Desktop) |
+| `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
 

package/dist/index.js

@@ -17713,7 +17713,7 @@ var {
 var package_default = {
   name: "@justestif/pk",
   type: "module",
-  version: "0.1.14",
+  version: "0.2.1",
   description: "Project knowledge \u2014 structured intake, search, and recall",
   bin: {
     pk: "dist/index.js"
@@ -34112,28 +34112,26 @@ ${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: ".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}`);
@@ -34179,13 +34177,81 @@ async function writeClaudeConfig(projectRoot, _name, knowledgeDir) {
   cfg.mcpServers = servers;
   await writeJson(cfgPath, cfg);
 }
-async function writeClaudeDesktopConfig(homeDir, name, knowledgeDir) {
-  const cfgPath = path7.join(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  const cfg = await readJson(cfgPath);
-  const servers = cfg.mcpServers ?? {};
-  servers[`pk-${name}`] = pkMcpEntry(knowledgeDir);
-  cfg.mcpServers = servers;
-  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}`;
+  const wrappedHook = {
+    matcher: "",
+    hooks: [
+      {
+        type: "command",
+        command: hookCmd
+      }
+    ]
+  };
+  const hasPkEval = (entry) => typeof entry === "object" && entry !== null && ("hooks" in entry) && Array.isArray(entry.hooks) && entry.hooks.some((hook) => typeof hook === "object" && hook !== null && ("type" in hook) && hook.type === "command" && ("command" in hook) && hook.command === hookCmd);
+  if (!ups.some(hasPkEval)) {
+    ups.push(wrappedHook);
+  }
+  hooks.UserPromptSubmit = ups;
+  settings.hooks = hooks;
+  await writeJson(settingsPath, settings);
 }
 async function writeCursorConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, ".cursor", "mcp.json");
@@ -34195,62 +34261,170 @@ async function writeCursorConfig(projectRoot, _name, knowledgeDir) {
   cfg.mcpServers = servers;
   await writeJson(cfgPath, cfg);
 }
-async function writeOmpConfig(projectRoot, _name, knowledgeDir) {
-  const cfgPath = path7.join(projectRoot, ".omp", "mcp.json");
+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;
   await writeJson(cfgPath, cfg);
 }
+async function writeGeminiMd(projectRoot) {
+  await writeInstructionSection(path7.join(projectRoot, "GEMINI.md"), PK_INSTRUCTION);
+}
+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 = 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;
   await writeJson(cfgPath, cfg);
 }
-async 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(`
-`);
-  mkdirSync4(path7.dirname(cfgPath), { recursive: true });
-  if (existsSync3(cfgPath)) {
-    const existing = await Bun.file(cfgPath).text();
-    if (existing.includes("[mcp_servers.pk]")) {
-      return;
-    }
-    await Bun.write(cfgPath, existing.trimEnd() + `
-
-` + toml);
-  } else {
-    await Bun.write(cfgPath, toml);
-  }
+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)});
+   },
+};
+`;
+}
+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 "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");
     }
   }
 }
@@ -34286,30 +34460,37 @@ async function ensureProject(name) {
   return { created: !alreadyExists, knowledgeDir: kDir };
 }
 async function applyHarness(harness, ctx) {
-  const { name, knowledgeDir, projectRoot, home } = ctx;
+  const { name, knowledgeDir, projectRoot } = ctx;
   switch (harness) {
     case "claude": {
       await writeClaudeConfig(projectRoot, name, knowledgeDir);
-      break;
-    }
-    case "claude-desktop": {
-      await writeClaudeDesktopConfig(home, name, knowledgeDir);
-      break;
-    }
-    case "codex": {
-      await writeCodexConfig(projectRoot, name, knowledgeDir);
+      await writeClaudeMd(projectRoot);
+      await writeClaudeHook(projectRoot);
       break;
     }
     case "cursor": {
       await writeCursorConfig(projectRoot, name, knowledgeDir);
+      await writeCursorRules(projectRoot);
+      await writeCursorHook(projectRoot);
       break;
     }
-    case "omp": {
-      await writeOmpConfig(projectRoot, name, knowledgeDir);
+    case "gemini": {
+      await writeGeminiConfig(projectRoot, name, knowledgeDir);
+      await writeGeminiMd(projectRoot);
+      await writeGeminiHook(projectRoot);
+      break;
+    }
+    case "codex": {
+      await writeCodexConfig(projectRoot, name, knowledgeDir);
+      await writeAgentsMd(projectRoot);
+      await writeCodexHook(projectRoot);
       break;
     }
     case "opencode": {
       await writeOpenCodeConfig(projectRoot, name, knowledgeDir);
+      await writeAgentsMd(projectRoot);
+      await writeClaudeMd(projectRoot);
+      await writeOpenCodePlugin(projectRoot);
       break;
     }
   }
@@ -42963,6 +43144,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);
@@ -42975,4 +43168,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.14",
+   "version": "0.2.1",
    "description": "Project knowledge — structured intake, search, and recall",
    "bin": {
       "pk": "dist/index.js"

package/skill/SKILL.md

@@ -72,8 +72,6 @@ No MCP tool for status changes. Use your file Edit tool directly on the frontmat
 
 **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.)
 
-**MANDATORY READ `references/git-workflow.md`** when: committing knowledge changes or unsure whether to auto-commit. (Same — standard file Read tool.)
-
 ## NEVER
 
 - **NEVER skip `pk_search` before `pk_new`**

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/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.