@justestif/pk 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # pk
 
-Project knowledge CLI — structured intake, search, and recall over `knowledge/`.
+Project knowledge CLI — structured intake, search, and recall.
 
 ## Install
 
@@ -13,37 +13,62 @@ Requires [Bun](https://bun.sh).
 ## Setup
 
 ```bash
-cd your-project
-pk init                        # Claude Code (default)
-pk init --harness pi           # Pi
-pk init --harness omp          # Oh My Pi
-pk init --harness opencode     # OpenCode
-pk init --harness cursor       # Cursor
-pk init --harness codex        # Codex CLI
+pk init
 ```
 
-Creates `knowledge/`, copies the skill to `.agents/skills/pk/`, and installs
-the harness adapter. Each harness injects current project context (open questions,
-recent decisions, active notes) automatically into every session.
+Interactive: picks a project name and one or more harnesses (space to toggle, enter to confirm).
 
-| Harness | Mechanism | Files generated |
-|---|---|---|
-| `claude` | `UserPromptSubmit` hook | `.claude/hooks/pk-*.ts` + `settings.json` |
-| `pi` | `before_agent_start` extension | `.pi/extensions/pk.ts` |
-| `omp` | `before_agent_start` hook | `.omp/extensions/pk.ts` |
-| `opencode` | `experimental.chat.system.transform` | `.opencode/plugins/pk.ts` |
-| `cursor` | Agent rule | `.cursor/rules/pk.mdc` |
-| `codex` | `AGENTS.md` block | `AGENTS.md` |
+Non-interactive:
+
+```bash
+pk init my-project --harness claude
+pk init my-project --harness claude,omp,cursor   # multiple harnesses
+```
+
+Available harnesses: `claude`, `claude-desktop`, `omp`, `cursor`, `opencode`, `codex`.
+
+`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)
+
+| Harness | Config file 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` |
+
+## How it works
+
+`pk mcp` runs a stdio MCP server that exposes four 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_lint` | Validate all notes for schema and quality rules |
+
+The agent calls these tools directly — no hooks, no shell extensions, no prompt injection.
 
 ## Commands
 
 ```bash
-pk new <type> <title> [--tags tag1,tag2]
-pk search <query> [--context] [--limit 5]
-pk synthesize [query] [--all] [--session-start]
-pk index
+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 synthesize [query] [--all]
+pk vocab [--json]
+pk rebuild
 pk lint
 pk instructions <command>
+pk config
 ```
 
 ### Note types
@@ -54,42 +79,40 @@ pk instructions <command>
 | `decision` | Chosen direction with rationale and consequences |
 | `question` | Unresolved uncertainty that blocks or informs work |
 | `source` | Raw input preserved for provenance |
+| `index` | Navigation/map-of-content over a topic or tag |
 
 ### Example
 
 ```bash
+pk init acme --harness claude
 pk new decision "Use SQLite for search index" --tags search,architecture
 pk new question "Should we support multi-project mode?" --tags scope
-pk index
+pk rebuild
 pk search "sqlite"
-pk synthesize --session-start
+pk synthesize
 ```
 
 ## Knowledge structure
 
-Notes live in `knowledge/` as plain markdown files — human-editable,
+Notes live in `~/.pk/<name>/` as plain markdown files — human-editable,
 git-diffable, readable without any tool.
 
 ```
-knowledge/
-  notes/
-  decisions/
-  questions/
-  sources/
-  indexes/        ← generated by pk index
-  .index.db       ← FTS5 search index, gitignored
+~/.pk/
+  <project-name>/
+    notes/
+    decisions/
+    questions/
+    sources/
+    indexes/        ← generated by pk rebuild
+    .index.db       ← FTS5 search index, gitignored
 ```
 
 Search is powered by SQLite FTS5 with BM25 ranking and porter stemming.
-The index is a derived artifact — delete it and run `pk index` to rebuild.
-
-## Agent hook
-
-`pk init` installs `.claude/hooks/pk-user-prompt-submit.ts` and registers it
-in `.claude/settings.json`. The hook calls `pk synthesize --session-start`
-on every prompt and injects the result as additional context.
+Partial word matching works — `pk search migr` matches "migration", "migrate", etc.
 
-To install for other harnesses, contributions welcome.
+`pk vocab` lists all tags by frequency — useful for orienting an agent before
+searching, without loading full note content.
 
 ## License