@justestif/pk 0.1.13 → 0.1.14

package/README.md

@@ -52,16 +52,17 @@ Available harnesses: `claude`, `claude-desktop`, `omp`, `cursor`, `opencode`, `c
 
 ## 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.1.14",
   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";
 
@@ -34172,62 +34159,59 @@ 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) {
+async function writeClaudeDesktopConfig(homeDir, name, knowledgeDir) {
   const cfgPath = path7.join(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  const cfg = readJson(cfgPath);
+  const cfg = await readJson(cfgPath);
   const servers = cfg.mcpServers ?? {};
   servers[`pk-${name}`] = pkMcpEntry(knowledgeDir);
   cfg.mcpServers = servers;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
 }
-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) {
+async function writeOmpConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, ".omp", "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 writeOpenCodeConfig(projectRoot, _name, knowledgeDir) {
+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);
   cfg.mcp = mcp;
-  writeJson(cfgPath, cfg);
+  await writeJson(cfgPath, cfg);
 }
-function writeCodexConfig(projectRoot, _name, knowledgeDir) {
+async function writeCodexConfig(projectRoot, _name, knowledgeDir) {
   const cfgPath = path7.join(projectRoot, ".codex", "config.toml");
   const toml = [
     "[mcp_servers.pk]",
@@ -34239,18 +34223,17 @@ function writeCodexConfig(projectRoot, _name, knowledgeDir) {
     ""
   ].join(`
 `);
-  if (existsSync4(cfgPath)) {
-    const existing = readFileSync2(cfgPath, "utf8");
+  mkdirSync4(path7.dirname(cfgPath), { recursive: true });
+  if (existsSync3(cfgPath)) {
+    const existing = await Bun.file(cfgPath).text();
     if (existing.includes("[mcp_servers.pk]")) {
       return;
     }
-    mkdirSync4(path7.dirname(cfgPath), { recursive: true });
-    writeFileSync2(cfgPath, existing.trimEnd() + `
+    await Bun.write(cfgPath, existing.trimEnd() + `
 
 ` + toml);
   } else {
-    mkdirSync4(path7.dirname(cfgPath), { recursive: true });
-    writeFileSync2(cfgPath, toml);
+    await Bun.write(cfgPath, toml);
   }
 }
 function skillTargetDir(harness, projectRoot) {
@@ -34280,61 +34263,59 @@ 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) {
+async function applyHarness(harness, ctx) {
   const { name, knowledgeDir, projectRoot, home } = ctx;
   switch (harness) {
     case "claude": {
-      writeClaudeConfig(projectRoot, name, knowledgeDir);
+      await writeClaudeConfig(projectRoot, name, knowledgeDir);
       break;
     }
     case "claude-desktop": {
-      writeClaudeDesktopConfig(home, name, knowledgeDir);
+      await writeClaudeDesktopConfig(home, name, knowledgeDir);
       break;
     }
     case "codex": {
-      writeCodexConfig(projectRoot, name, knowledgeDir);
+      await writeCodexConfig(projectRoot, name, knowledgeDir);
       break;
     }
     case "cursor": {
-      writeCursorConfig(projectRoot, name, knowledgeDir);
+      await writeCursorConfig(projectRoot, name, knowledgeDir);
       break;
     }
     case "omp": {
-      writeOmpConfig(projectRoot, name, knowledgeDir);
+      await writeOmpConfig(projectRoot, name, knowledgeDir);
       break;
     }
     case "opencode": {
-      writeOpenCodeConfig(projectRoot, name, knowledgeDir);
+      await writeOpenCodeConfig(projectRoot, name, knowledgeDir);
       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 +34342,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 +34405,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 +42900,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 +42909,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: {}

package/package.json

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

package/skill/SKILL.md

@@ -5,43 +5,89 @@ 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
+
+```
+pk_lint({})
+```
 
-## Intake
+**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.
 
-**Search before creating** — always call `pk_search` first.
+### Status transitions
 
-- 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.
+No MCP tool for status changes. Use your file Edit tool directly on the frontmatter, fill in the resolution section, then lint.
 
-## Asking
+**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.)
 
-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/git-workflow.md`** when: committing knowledge changes or unsure whether to auto-commit. (Same — standard file Read tool.)
 
 ## 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/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.