@justestif/pk 0.2.2 → 0.3.2

package/README.md

@@ -30,55 +30,47 @@ 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), `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. Installs a harness adapter that calls `pk prime` at session start to inject the skill into context
-
-| 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` |
-| `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` |
+2. Installs a hook or plugin that calls `pk prime` at session start to inject context into your agent
+3. Installs the pk skill so your agent knows how to use the CLI
 
-## How it works
-
-`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` | 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. Agents should never read or write knowledge files directly.
+| Harness | Files written | Mechanism |
+|---|---|---|
+| `claude` | `.claude/hooks/pk-eval.ts`, `.claude/settings.json` | Hook spawns `pk prime` on every prompt |
+| `codex` | `AGENTS.md` | Codex reads AGENTS.md natively |
+| `opencode` | `.opencode/plugins/pk-eval.ts` | Plugin spawns `pk prime` at session start |
 
 ## Commands
 
 ```bash
-pk init [name] [--harness h1,h2,…]   # set up project + MCP config
-pk mcp                                 # start MCP server (stdio)
+pk init [name] [--harness h1,h2,…]   # set up project + hooks
 
 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 prime                               # output priming context for hooks
 pk instructions <command>
 pk config
 ```
 
+Every command supports `--json` for machine-readable output.
+
 ### Note types
 
 | Type | Purpose |
@@ -103,7 +95,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 the CLI; humans can read and edit them directly.
 
 ```
 ~/.pk/
@@ -119,8 +111,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 before searching.
+
+`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