@justestif/pk 0.2.1 → 0.3.0

package/README.md

@@ -30,10 +30,12 @@ Non-interactive:
 
 ```bash
 pk init my-project --harness claude
-pk init my-project --harness claude,cursor   # multiple harnesses
+pk init my-project --harness claude,codex   # multiple harnesses
 ```
 
-Available harnesses: `claude` (Claude Code & Claude Desktop), `cursor` (Cursor), `gemini` (Gemini CLI), `codex` (Codex), `opencode` (OpenCode).
+**Git integration:** `pk init` creates a git repository in `~/.pk/<name>/.git` and tracks all knowledge operations via commits and git notes.
+
+Available harnesses: `claude` (Claude Code & Claude Desktop), `codex` (Codex), `opencode` (OpenCode).
 
 `pk init` does three things:
 
@@ -43,25 +45,27 @@ Available harnesses: `claude` (Claude Code & Claude Desktop), `cursor` (Cursor),
 
 | Harness | Files written |
 |---|---|
-| `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` |
+| `claude` | `.mcp.json`, `CLAUDE.md`, `.claude/hooks/pk-eval.ts`, `.claude/settings.json` |
 | `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
+## MCP
 
-`pk mcp` runs a stdio MCP server that exposes five tools to any connected agent:
+`pk mcp` starts an MCP server on stdio. It runs in-process — tools call the same lib functions as the CLI, no subprocess overhead.
 
-| Tool | What it does |
-|---|---|
-| `pk_search` | Full-text search over the knowledge base (BM25, porter stemming) |
-| `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 |
+For Claude Desktop, add to `claude_desktop_config.json`:
 
-The agent calls these tools directly — no hooks, no shell extensions, no prompt injection. Agents should never read or write knowledge files directly.
+```json
+{
+  "mcpServers": {
+    "pk": {
+      "command": "pk",
+      "args": ["mcp"],
+      "env": { "PK_KNOWLEDGE_DIR": "/Users/you/.pk/my-project" }
+    }
+  }
+}
+```
 
 ## Commands
 
@@ -70,11 +74,15 @@ pk init [name] [--harness h1,h2,…]   # set up project + MCP config
 pk mcp                                 # start MCP server (stdio)
 
 pk new <type> <title> [--tags t1,t2]
-pk search <query> [--context] [--limit 5] [--type] [--status] [--tag]
+pk edit <path> [--editor <cmd>]      # edit existing note
+pk delete <path> [--yes]               # delete note with confirmation
+pk search <query> [--limit 5] [--type] [--status] [--tag]
 pk synthesize [query] [--all]
+pk history [--limit 20] [--type <type>] [--filter-type <type>] [--filter-tag <tag>] [--filter-operation <op>]
+pk read <path> [--json]
 pk vocab [--json]
 pk rebuild
-pk lint
+pk lint [paths...] [--json]
 pk instructions <command>
 pk config
 ```
@@ -103,7 +111,7 @@ pk synthesize
 ## Knowledge structure
 
 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.
+Agents access them exclusively through MCP tools; humans can read and edit them directly.
 
 ```
 ~/.pk/
@@ -119,8 +127,9 @@ Agents access them exclusively through the MCP tools; humans can read and edit t
 Search is powered by SQLite FTS5 with BM25 ranking and porter stemming.
 Partial word matching works — `pk search migr` matches "migration", "migrate", etc.
 
-`pk vocab` lists all tags by frequency — useful for orienting an agent before
-searching, without loading full note content.
+`pk vocab` lists all tags by frequency — useful for orienting an agent before searching, without loading full note content.
+
+`pk history` shows all knowledge operations (create, update, delete) as git commits and synthesize operations as git notes. Supports filtering by type, tag, and operation.
 
 ## License