pi-para 0.5.2

package/CHANGELOG.md

@@ -0,0 +1,214 @@
+# Changelog
+
+## [0.5.2] — 2026-05-02
+
+### Added
+- **Configurable teacher/student/judge models** for GEPA optimization
+  - `gepa.studentModel`: runs proxy (default: `claude-sonnet-4`) — fast, cheap, ~460 calls/target
+  - `gepa.teacherModel`: proposes mutations (default: `claude-opus-4-6`) — smart, creative, ~30 calls/target
+  - `gepa.judgeModel`: scores output (default: same as student) — fast, cheap
+- CLI flags: `--student-model`, `--teacher-model`, `--judge-model` (+ `--model`/`--reflection-model` shorthands)
+- All GEPA settings persisted in `config.json` and overridable via CLI
+- `run-all.sh` helper script for sequential target optimization with proper token refresh
+- OAuth token auto-refresh in `AnthropicOAuthLM` (prevents 401 on long runs)
+
+## [0.5.1] — 2026-05-01
+
+### Added
+- **Bundled GEPA-optimized prompts** — ship pre-optimized `capture-prompt` with the package (32.4% improvement over baseline: 0.582 → 0.770)
+- `getPrompt()` resolution order: user-generated → bundled optimized → original constant
+- `gepa.useOptimized` defaults to `true` so users get optimized prompts out of the box
+- Build copies `src/gepa/optimized/*.txt` into `dist/gepa/optimized/` automatically
+
+## [0.5.0] — 2026-05-01
+
+### Added
+- **GEPA prompt optimizer** — automatically optimize all pi-para prompts, tool instructions, and skill guidelines using DSPy GEPA (Genetic-Pareto optimizer)
+  - 22 optimization targets: 12 prompt templates, 8 tool instructions, 2 skills
+  - Runs via `uv` with custom `dspy.BaseLM` subclasses — no litellm dependency
+  - Custom `AnthropicOAuthLM` with Claude Code billing headers and user-agent for free OAuth usage
+  - Custom `MiniMaxLM` (Anthropic-compatible API) and `OpenRouterLM` (OpenAI-compatible API)
+  - LLM-as-judge metric scoring on 6 dimensions: structure, PARA compliance, cross-references, security, completeness, actionability
+  - Trainset built from real wiki pages (no synthetic data)
+  - Side-by-side deployment: optimized prompts saved to `~/.pi/wiki/gepa/optimized/`, toggled via `config.gepa.useOptimized`
+  - API keys extracted from `~/.pi/agent/auth.json` and passed as env vars to `uv` subprocess
+  - `PromptProxy` DSPy Module: 1 LLM call per eval instead of full agent loop (10-50 calls)
+  - Version history per target in `~/.pi/wiki/gepa/history/`
+- **CLI commands**: `pi-para-daemon gepa optimize|list|targets|compare`
+- **`getPrompt(name)`** function in `src/templates/prompts.ts` — loads GEPA-optimized version at runtime when `config.gepa.useOptimized` is true
+- **`gepa` config section** in `ParaConfig` with `useOptimized` toggle
+
+## [0.4.5] — 2026-04-30
+
+### Fixed
+- **Daemon model change now auto-restarts daemon** — changing the daemon model via `/wiki-settings` → `[Daemon]` now automatically runs `systemctl --user restart pi-para-daemon` so the new model takes effect immediately
+- **qmd FK constraint fix (v2.3.2)** — `deleteInactiveDocuments` now cleans up `document_links` and `document_metadata` before deleting inactive docs, fixing the second FK violation that blocked store opening
+
+## [0.4.4] — 2026-04-29
+
+### Fixed
+- **Lazy store retry** — if qmd store fails to open at session start (db locked, transient error), retries automatically on first tool use instead of staying disabled for the entire session
+  - Store proxy intercepts calls when `storeDisabled` is true and attempts `openStore()` before throwing
+  - On successful retry, marks context dirty so wiki context is rebuilt
+  - Prevents guard against concurrent retry attempts
+
+## [0.4.3] — 2026-04-29
+
+### Added
+- **Mid-session capture on compaction** — registers session for daemon capture when auto/manual compaction fires
+  - Hooks into `session_compact` event — fires after context compaction
+  - Compaction signals the session has accumulated enough content that details are about to be compressed
+  - Perfect capture trigger: knowledge is captured before details are lost in the summary
+  - Shows status line feedback: "wiki: capture queued (compaction)"
+  - Works alongside existing `session_shutdown` capture — sessions now captured at both compaction and quit
+
+### Fixed
+- Skill name mismatch: `skills/setup/SKILL.md` name field changed from `pi-para-setup` to `setup` to match directory
+
+## [0.4.2] — 2026-04-29
+
+### Added
+- **Configurable graph-boosted search** — `searchGraphBoost` setting in `config.json`
+  - Previously hardcoded to `true` in `store.ts`
+  - Now controllable via `/wiki-settings` → `[Search]` → `Graph boost: true/false`
+  - Threads through the full pipeline: `config` → `registerTools` → `createQueryExecute` → `queryWiki` → `searchWiki` → `store.searchLex`
+  - `WikiSearchOptions.graphBoost` and `QueryOptions.graphBoost` added to public interfaces
+  - Default remains `true` (1-hop wikilink expansion after BM25 search)
+- `/wiki-settings` `[Search]` now opens a submenu with `Limit` and `Graph boost` options
+
+### Changed
+- README updated: 8 tools (added `wiki_migrate`), 11 commands (added `/wiki-migrate`, `/wiki-project`), `searchGraphBoost` in config example, 301 tests
+
+## [0.4.1] — 2026-04-29
+
+### Added
+- Web UI graph: scope filter dropdown + max nodes slider
+
+## [0.4.0] — 2026-04-29
+
+### Added
+- **Schema versioning & migration** — future-proof wiki format evolution
+  - `schemaVersion` integer field in frontmatter (defaults to 1 for existing pages)
+  - Migration registry in `frontmatter.ts` — chain of `from→to` transforms
+  - `migrateToLatest()` applies all pending migrations sequentially
+  - `wiki_migrate` tool (LLM-callable) for batch migration
+  - `/wiki-migrate` command — migrates all pages, reports count
+  - Lint check #15: `schema-version` — flags pages below current version, auto-fixes
+- **qmd graph-boosted search** (requires @picassio/qmd 2.3.0)
+  - `document_links` edge table tracks `[[wikilinks]]` between pages
+  - 1-hop graph expansion after BM25 search — surfaces wikilink-connected pages
+  - `graphBoost: true` in `searchWiki()` — related pages appear in results even without text match
+  - `extractWikilinks()` exported from qmd for reuse
+- **Scale resilience** — tested for 500+ page wikis
+  - Code-generated `index.md` via `rebuildIndex()` — deterministic, no LLM generation needed
+  - Tiered context injection — max 40 scope-filtered pages in system prompt, rest via `wiki_query`
+  - Page summary cache in SQLite — `buildContext()` reads cache instead of N disk reads
+  - Web UI pagination — `?page=N&limit=50` on `/api/pages`, `?maxNodes=100` on graph endpoint
+- **PARA project lifecycle**
+  - `/wiki-project <name> <goal>` — creates structured project page with goal, status checklist, end condition
+  - `/wiki-project done <name>` — archives completed project
+  - Maintenance agent reviews projects for completion signals, suggests archiving
+  - Maintenance agent updates areas with latest health metrics
+- **PARA active skill** (`skills/para/SKILL.md`)
+  - Behavioral guidelines for actively using wiki during work (not just passive capture)
+  - Covers: consult before planning, write during work, search when debugging, check conventions when reviewing
+  - PARA category decision guide — when to use projects/ vs areas/ vs resources/
+
+### Changed
+- `wiki_write` no longer accepts `indexContent` — index is auto-rebuilt from disk after every write
+- `wiki_move` auto-rebuilds index after moving pages
+- Capture and ingest prompts no longer instruct LLM to generate index
+- Context injection sorts pages by recency, caps at 40 pages with overflow note
+
+### Dependencies
+- Requires @picassio/qmd ≥2.3.0 (graph boost support)
+
+## [0.3.2] — 2026-04-29
+
+### Added
+- **Wiki freshness verification system** — prevents LLM from blindly trusting stale wiki content
+  - `formatFreshness()` in `query.ts` computes age-based freshness tiers for every page
+  - 5 tiers: ✅ FRESH (<7d), ✅ Recent (7-14d), ⚠️ AGING (14-30d), ⚠️ STALE (30-90d), 🚨 VERY STALE (>90d)
+  - `wiki_query` results now include `Updated: ... | ⚠️ STALE — 45 days old` per result
+  - `wiki_read` output includes freshness indicator in header line
+  - `QUERY_PROMPT` gains "FRESHNESS VERIFICATION (critical)" section with 5 verification rules
+  - `wiki_query` and `wiki_read` `promptGuidelines` instruct LLM to verify AGING/STALE pages
+  - Context injection adds system prompt reminder about the self-healing loop
+  - Maintenance agent gains task #6: staleness review for pages >30 days old making code/config claims
+  - `INGEST_PROMPT` gains rule #9: check existing Key Facts accuracy when updating pages
+- **Self-healing loop** — when LLM discovers wiki content is wrong during verification, it fixes the page immediately with `wiki_write(mode: 'edit')`, so future queries get correct answers
+
+## [0.3.0] — 2026-04-28
+
+### Added
+- **Web Wiki UI** — React SPA served by daemon at configurable port
+  - Design system: Inter font, 4px grid, semantic color tokens, dark/light toggle
+  - Full accessibility: ARIA labels, focus rings, keyboard nav, skip links, reduced motion
+  - 18 Lucide-style SVG icons (replaced all emojis)
+  - Scope filter dropdown, debounced search, loading states, toast notifications
+  - D3 force graph with legend (full-width), breadcrumbs, card-based layouts
+  - Graph view: `main-wide` class for full-width display
+- **Secret redaction** (`redact.ts`) — strips API keys, tokens, passwords from all wiki writes
+  - 14 pattern types (OpenRouter, OpenAI, Anthropic, MiniMax, GitHub, AWS, Jina, Bearer, YAML, env vars)
+  - Runs on every write path: tools.ts, processor.ts, webui server, lint auto-fix
+- **Shared link utilities** (`link-utils.ts`) — centralized `extractWikilinks`, `autoLinkSlugs`, `syncFrontmatterLinks`
+  - Replaces 4 duplicate implementations across codebase
+  - Protected regions: fenced code, inline code, URLs, headings
+  - Longest-slug-first matching, first-occurrence-only linking
+- **Tag registry** (`tag-registry.ts`) — canonical tag normalization + scope validation
+  - Alias mapping (capture→session-capture, para→pi-para, etc.)
+  - Removes scope-tag duplicates, enforces kebab-case
+  - Scope normalization: project-agnostic, extracts kebab prefix from multi-word scopes
+- **LLM maintenance agent** (`maintainer.ts`) — replaces code-based maintenance
+  - Runs every 30 min via daemon with wiki_list, wiki_read, wiki_query, wiki_write, wiki_merge, wiki_lint tools
+  - Intelligent duplicate detection & merging, link discovery, category review, tag cleanup
+- **Git auto-commit** (`wiki.ts`) — every wiki mutation committed with descriptive message
+  - Auto-initializes git repo in wiki directory
+  - Commit points: wiki_write, wiki_move, daemon capture, maintenance, webui PUT
+- **Edit mode** for `wiki_write` — surgical `oldText→newText` replacements (like pi's edit tool)
+- **Lint checks 11-14**: link-sync, tag-health, secrets, category-misuse
+- **Scope filter** in web UI — dropdown to filter pages by project scope
+- **`/wiki-daemon status`** — reads state DB directly (instant, no subprocess)
+- **`/wiki-settings`** — provider/model picker from pi's auth storage
+
+### Changed
+- **Web server moved to daemon** — eliminates port conflicts between pi sessions
+  - Extension just checks if daemon server is running, shows URL in status bar
+- **`/wiki-capture`** — queues to daemon for background processing (non-blocking)
+- **Daemon uses pi's auth.json** — OAuth token refresh for Anthropic, configurable model via `/wiki-settings`
+- **Daemon scope detection** — reads session header first, falls back to `projects-` prefix extraction (fixes `agent-board` → `board` bug)
+- **Capture prompts** — stronger dedup guidance ("search wiki_query FIRST, update existing pages")
+- **PARA category prompts** — "resources/ for almost everything" across all prompt layers
+- **Schema.md** — expanded with category decision rules, scope/tag format rules, ✅/❌ examples, secrets policy
+- **systemd service** — `bash -lc` login shell (works with mise, nvm, fnm, volta, system node)
+
+### Fixed
+- 2 wiki pages contained live API keys — redacted
+- 38 pages had empty `links: []` — bulk fix added wikilinks
+- 9 tags had spaces — normalized to kebab-case
+- 26 scope-tag duplicates — removed
+- 14 multi-word scope values — cleaned (LLM wrote topic descriptions as scope)
+- 11 pages in projects/ were reference docs — moved to resources/
+- Duplicate pages merged (pi-para-web-wiki-ui, pi-para-extension-architecture, etc.)
+- Graph view confined to 860px — now full-width
+- Scroll container nesting — separated `.main-scroll` from `.main`
+
+## [0.2.0] — 2026-04-27
+
+### Added
+- Web wiki UI — server + React SPA client
+- Daemon (`pi-para-daemon`) for background session capture
+- Interactive `/wiki-settings` with nested menus
+- Configurable via `~/.pi/wiki/config.json`
+
+## [0.1.0] — 2026-04-06
+
+### Added
+- PARA-structured wiki at `~/.pi/wiki/`
+- 7 LLM tools: `wiki_ingest`, `wiki_query`, `wiki_write`, `wiki_read`, `wiki_move`, `wiki_lint`, `wiki_summarize`
+- 7 slash commands: `/wiki`, `/wiki-ingest`, `/wiki-lint`, `/wiki-capture`, `/wiki-scope`, `/wiki-search`, `/wiki-summarize`
+- Auto-capture on session shutdown
+- Project scope detection
+- Context injection with caching
+- 10 lint checks with auto-fix
+- Hybrid search via `@picassio/qmd`

package/README.md

@@ -0,0 +1,305 @@
+# pi-para
+
+A [pi](https://github.com/badlogic/pi-mono) extension that maintains a persistent, LLM-curated personal knowledge base structured by the [PARA method](https://fortelabs.com/blog/para/) (Projects, Areas, Resources, Archives). Inspired by [Karpathy's LLM wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
+
+The LLM writes and maintains the wiki autonomously. You provide sources and ask questions. Search powered by [@picassio/qmd](https://github.com/picassio/qmd-1).
+
+## Install
+
+```bash
+pi install @picassio/pi-para
+```
+
+Start pi — the extension loads automatically. Wiki directory is created on first session.
+
+## Features
+
+### Wiki Tools (8)
+
+| Tool | Description |
+|------|-------------|
+| `wiki_ingest` | Ingest a URL, file, or text into the wiki |
+| `wiki_query` | Search the wiki with scope filtering, graph boost, freshness indicators |
+| `wiki_write` | Create or update wiki pages |
+| `wiki_read` | Read a specific wiki page + freshness indicator |
+| `wiki_move` | Move pages between PARA categories |
+| `wiki_lint` | Run health checks and auto-fix |
+| `wiki_summarize` | Summarize pages, categories, or entire wiki |
+| `wiki_migrate` | Batch-migrate all pages to current schema version |
+
+### Commands (11)
+
+| Command | Description |
+|---------|-------------|
+| `/wiki` | Status overview (scope, pages, log) |
+| `/wiki-search <query>` | Search the wiki |
+| `/wiki-ingest <url>` | Quick ingest |
+| `/wiki-capture [topic]` | Ask LLM to save knowledge via wiki_write |
+| `/wiki-scope` | Show or override project scope |
+| `/wiki-lint` | Run health checks |
+| `/wiki-summarize [target]` | Summarize wiki content |
+| `/wiki-settings` | Interactive settings (search, context, daemon, web UI, providers) |
+| `/wiki-daemon <cmd>` | Manage background capture daemon |
+| `/wiki-migrate` | Migrate all pages to current schema version |
+| `/wiki-project <name> <goal>` | Create or archive (`done`) a project page |
+
+### Web Wiki UI
+
+Browser-based wiki viewer, editor, and graph visualization.
+
+```
+/wiki-settings → [WebWiki] → Enabled: true
+```
+
+Access at `http://<LAN-IP>:10973`. Features:
+- Page tree by PARA category (sidebar)
+- Markdown viewer with clickable `[[wikilinks]]`
+- Inline page editor
+- D3 force-directed graph view (page relationships)
+- Search
+- Move pages between categories
+- Activity log and session digests
+- Mobile-first responsive design, dark/light theme
+
+### GEPA Prompt Optimizer
+
+Automatically optimize all pi-para prompts, tool instructions, and skill guidelines using [DSPy GEPA](https://arxiv.org/abs/2507.19457) (Genetic-Pareto optimizer). Runs via `uv` with custom LLM providers — no litellm.
+
+```bash
+# List all 22 optimization targets
+pi-para-daemon gepa targets
+
+# Optimize a single target (uses config defaults: sonnet student + opus teacher)
+pi-para-daemon gepa optimize --target capture-prompt
+
+# Optimize all targets sequentially
+bash scripts/gepa/run-all.sh
+
+# Override models via CLI
+pi-para-daemon gepa optimize --target skill-para \
+  --student-model anthropic/claude-sonnet-4-20250514 \
+  --teacher-model anthropic/claude-opus-4-6 \
+  --judge-model anthropic/claude-sonnet-4-20250514
+
+# Shorthand (--model = student, --reflection-model = teacher)
+pi-para-daemon gepa optimize --model anthropic/claude-sonnet-4-20250514 --reflection-model anthropic/claude-opus-4-6
+
+# See results
+pi-para-daemon gepa list
+
+# Compare original vs optimized
+pi-para-daemon gepa compare --target capture-prompt
+```
+
+**How it works:**
+
+1. TypeScript extracts all prompt/tool/skill texts from source files
+2. Calls `uv run scripts/gepa/optimize.py` with API keys from `~/.pi/agent/auth.json`
+3. Python builds a trainset from real wiki pages (93 pages → 30 train / 20 val)
+4. DSPy GEPA evolves each instruction using a lightweight proxy module (1 LLM call per eval, not 10-50)
+5. **Teacher** (Opus) proposes instruction mutations based on metric feedback
+6. **Student** (Sonnet) runs the proxy to generate output from the instruction
+7. **Judge** (Sonnet) scores on 6 dimensions: structure, PARA compliance, cross-references, security, completeness, actionability
+8. Optimized prompts saved to `~/.pi/wiki/gepa/optimized/`
+
+**Teacher/Student/Judge pattern** (DSPy GEPA):
+
+| Role | Default Model | What It Does | Calls/target |
+|------|---------------|--------------|--------|
+| **Student** | `claude-sonnet-4` | Runs proxy (generates wiki output) | ~460 |
+| **Teacher** | `claude-opus-4-6` | Proposes mutations via reflection | ~30 |
+| **Judge** | `claude-sonnet-4` | Scores output (LLM-as-judge metric) | ~460 |
+
+**22 optimization targets:**
+
+| Category | Targets |
+|----------|--------|
+| Prompt templates (12) | System, ingest, query, capture (×3), maintenance, processor, summarize, iterative, overview, lint |
+| Tool instructions (8) | wiki_ingest, wiki_query, wiki_write, wiki_read, wiki_move, wiki_lint, wiki_migrate, wiki_summarize |
+| Skills (2) | para (active PARA workflow), setup (installation guide) |
+
+**LLM providers** (custom `dspy.BaseLM` subclasses, no litellm):
+
+| Provider | Auth | Notes |
+|----------|------|-------|
+| Anthropic | OAuth token from `auth.json` | Claude Code billing headers + user-agent, auto token refresh |
+| MiniMax | API key | Via Anthropic-compatible API |
+| OpenRouter | API key | Via OpenAI-compatible API |
+
+**Configuration** (`~/.pi/wiki/config.json`):
+
+```json
+{
+  "gepa": {
+    "useOptimized": true,
+    "studentModel": "anthropic/claude-sonnet-4-20250514",
+    "teacherModel": "anthropic/claude-opus-4-6",
+    "judgeModel": null,
+    "auto": "light",
+    "threads": 2,
+    "seed": 42
+  }
+}
+```
+
+- `useOptimized: true` — load optimized prompts at runtime (enabled by default)
+- `studentModel` — fast model for running proxy + judging (Sonnet recommended)
+- `teacherModel` — smart model for proposing mutations (Opus recommended)
+- `judgeModel` — model for scoring output (defaults to studentModel if null)
+- All settings overridable via CLI flags
+
+When `useOptimized` is enabled, `getPrompt(name)` checks: user-generated → bundled optimized → original. Originals are always preserved.
+
+**Budget presets:**
+
+| Preset | Rollouts | Time estimate | When to use |
+|--------|----------|---------------|-------------|
+| `light` | ~460 | 1-2 hours | Quick sanity check |
+| `medium` | ~1500 | 4-6 hours | Everyday optimization |
+| `heavy` | ~5000 | 12-24 hours | Final tuning |
+
+**Prerequisites:** `uv` (Python package manager). DSPy + anthropic SDK installed automatically on first run.
+
+### Background Capture Daemon
+
+Processes session files in the background after you quit pi:
+
+```bash
+# Via extension command
+/wiki-daemon start
+/wiki-daemon status
+
+# Via CLI
+pi-para-daemon start
+pi-para-daemon process-recent --hours 24
+```
+
+The daemon uses an Agent with session exploration tools (session_slice, session_search, session_stats) to iteratively explore sessions of any size and extract knowledge.
+
+Auto-starts via systemd on Linux — run `./setup.sh` once for daemon service setup.
+
+## Architecture
+
+```
+~/.pi/wiki/
+├── config.json        # all settings (context, search, daemon, web UI, gepa)
+├── schema.md          # PARA conventions
+├── index.md           # page catalog (auto-rebuilt)
+├── log.md             # activity log
+├── sessions.md        # session digest log
+├── .completed-sessions # daemon registry
+├── .daemon.sqlite     # daemon state
+├── .qmd.sqlite        # search index
+├── projects/          # active, goal-defined work
+├── areas/             # ongoing responsibilities
+├── resources/         # reference material
+├── archives/          # completed/deprecated
+├── raw/               # immutable source material
+└── gepa/              # GEPA optimizer state
+    ├── input/         # targets.json (generated per run)
+    ├── output/        # results.json (GEPA output)
+    ├── optimized/     # deployed optimized prompts (*.txt)
+    └── history/       # version history per target
+```
+
+**Python scripts (GEPA optimizer):**
+
+```
+scripts/gepa/
+├── pyproject.toml     # uv project (dspy, anthropic, openai deps)
+├── optimize.py        # Main entry — runs DSPy GEPA
+├── lm_providers.py    # Custom BaseLM: AnthropicOAuthLM, MiniMaxLM, OpenRouterLM
+├── program.py         # PromptProxy DSPy Module (1 LLM call per eval)
+├── metric.py          # LLM-as-judge metric (6 dimensions)
+├── dataset.py         # Build train/val from real wiki pages
+└── wiki_reader.py     # Read wiki pages from disk
+```
+
+### How it works
+
+1. **During a session** — LLM uses wiki tools (query, write, ingest). Context injection provides wiki knowledge on every turn.
+2. **On /quit** — session registered in `.completed-sessions` (instant, <10ms)
+3. **Background** — daemon picks up session, Agent explores with tools, writes wiki pages
+4. **Next session** — new wiki pages appear in context injection
+
+### Freshness Verification
+
+Every `wiki_query` and `wiki_read` result includes a freshness indicator based on the page's last-updated date:
+
+| Age | Indicator | LLM Behavior |
+|-----|-----------|---------------|
+| < 7 days | ✅ FRESH | Trust normally |
+| 7-14 days | ✅ Recent | Trust normally |
+| 14-30 days | ⚠️ AGING | Verify claims about code/configs before trusting |
+| 30-90 days | ⚠️ STALE | Verify before trusting |
+| > 90 days | 🚨 VERY STALE | Likely outdated, verify everything |
+
+The LLM is instructed to:
+- **Verify** stale claims by checking actual code, configs, or files
+- **Self-heal** — fix incorrect wiki pages via `wiki_write(mode: 'edit')` when it discovers they're wrong
+- **Flag uncertainty** — tell the user when a claim can't be verified (e.g. external services)
+
+### Configuration
+
+All settings via `/wiki-settings` interactive menu, or edit `~/.pi/wiki/config.json`:
+
+```json
+{
+  "contextMaxTokens": 4000,
+  "searchLimit": 10,
+  "searchGraphBoost": true,
+  "lintAutoFix": true,
+  "lintStaleDays": 90,
+  "daemonModel": null,
+  "webWiki": { "enabled": true, "host": "0.0.0.0", "port": 10973 },
+  "gepa": { "useOptimized": false }
+}
+```
+
+Search providers in `~/.config/qmd/index.yml`:
+
+```yaml
+providers:
+  embed:
+    url: https://openrouter.ai/api/v1
+    key: sk-or-...
+    model: openai/text-embedding-3-small
+  chat:
+    url: https://api.minimaxi.com/anthropic
+    key: sk-cp-...
+    model: MiniMax-M2.7-highspeed
+    api: anthropic
+```
+
+### Optional: Enhanced search
+
+```bash
+npm install -g @picassio/qmd
+```
+
+Without qmd: BM25 keyword search. With qmd + providers: hybrid BM25 + vector + rerank.
+
+## Obsidian Compatibility
+
+The wiki is a directory of markdown files with YAML frontmatter and `[[wikilinks]]`. Open `~/.pi/wiki/` as an Obsidian vault for graph view, Dataview queries, and manual editing.
+
+## Development
+
+```bash
+git clone https://github.com/picassio/pi-para.git
+cd pi-para
+npm install
+npm run check    # TypeScript check
+npm test         # Run tests (301 tests)
+npm run build    # Compile to dist/
+
+# Dev mode: symlink extension
+ln -sf $(pwd) ~/.pi/agent/extensions/pi-para
+
+# Run daemon locally
+npx tsx src/cli.ts start
+```
+
+## License
+
+MIT

package/SETUP.md

@@ -0,0 +1,171 @@
+# pi-para Setup Instructions
+
+> This file is designed to be read by pi (the AI agent). Ask pi: "read SETUP.md and set up pi-para"
+
+## Prerequisites
+
+- pi (coding agent) installed and working
+- Node.js available (`node --version`)
+- Internet access for npm
+
+## Step 1: Install the extension
+
+```bash
+pi install @picassio/pi-para
+```
+
+Verify it loaded — restart pi and check extensions list. You should see `pi-para` in the `[Extensions]` section.
+
+## Step 2: Install qmd search engine (recommended)
+
+qmd provides hybrid search (BM25 + vector + rerank). Without it, wiki search uses BM25 keyword matching only.
+
+```bash
+npm install -g @picassio/qmd
+```
+
+Verify: `qmd --version` should print a version number.
+
+## Step 3: Configure search providers
+
+Create `~/.config/qmd/index.yml` with your API providers. Choose based on what keys you have:
+
+### Option A: OpenRouter (embedding) + MiniMax CN (chat)
+
+```yaml
+providers:
+  embed:
+    url: https://openrouter.ai/api/v1
+    key: YOUR_OPENROUTER_KEY
+    model: openai/text-embedding-3-small
+    dims: 768
+  chat:
+    url: https://api.minimaxi.com/anthropic
+    key: YOUR_MINIMAX_CN_KEY
+    model: MiniMax-M2.7-highspeed
+    api: anthropic
+```
+
+### Option B: OpenAI only
+
+```yaml
+providers:
+  embed:
+    url: https://api.openai.com/v1
+    key: YOUR_OPENAI_KEY
+    model: text-embedding-3-small
+    dims: 1536
+  chat:
+    url: https://api.openai.com/v1
+    key: YOUR_OPENAI_KEY
+    model: gpt-4o-mini
+```
+
+### Option C: No providers (BM25 only)
+
+Skip this step. Wiki search works with keyword matching. No API keys needed.
+
+## Step 4: Configure daemon LLM (optional)
+
+Edit `~/.pi/wiki/config.json` (created after first pi session) and set `daemonModel`:
+
+```json
+{
+  "daemonModel": "anthropic/claude-sonnet-4"
+}
+```
+
+If null, the daemon auto-detects from:
+1. Pi's API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+2. qmd chat provider from Step 3
+
+## Step 5: Start the background capture daemon
+
+### Linux (systemd — recommended)
+
+Run the setup script from the pi-para install directory:
+
+```bash
+# Find the install path
+PARA_DIR="$(npm root -g)/@picassio/pi-para"
+# Or if installed via pi:
+# PARA_DIR="$HOME/.pi/agent/packages/npm/@picassio/pi-para"
+
+cd "$PARA_DIR"
+
+# Install tsx if not present
+npm install tsx 2>/dev/null
+
+# Create systemd user service
+mkdir -p ~/.config/systemd/user
+NODE_BIN="$(dirname "$(which node)")"
+
+cat > ~/.config/systemd/user/pi-para-daemon.service << EOF
+[Unit]
+Description=pi-para knowledge capture daemon
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=$PARA_DIR
+ExecStart=$PARA_DIR/node_modules/.bin/tsx src/cli.ts start
+Restart=on-failure
+RestartSec=10
+Environment=HOME=$HOME
+Environment=PATH=$NODE_BIN:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
+
+[Install]
+WantedBy=default.target
+EOF
+
+# Enable, start, and survive SSH logout
+systemctl --user daemon-reload
+systemctl --user enable pi-para-daemon
+systemctl --user start pi-para-daemon
+sudo loginctl enable-linger $USER
+```
+
+Verify: `systemctl --user status pi-para-daemon`
+
+### macOS / Manual
+
+```bash
+cd "$PARA_DIR" && npx tsx src/cli.ts start
+```
+
+Keep the terminal open, or use a process manager like pm2.
+
+## Step 6: Verify everything works
+
+In pi, run these commands:
+
+1. `/wiki-settings` — should show config, search engine status, providers, daemon status
+2. `/wiki` — should show "Pages: 0 total" (empty wiki)
+3. Say: "save to wiki: this is a test page" — should create a page
+4. `/wiki` — should show "Pages: 1 total"
+5. Say: "search the wiki for test" — should find the test page
+
+## Troubleshooting
+
+### Extension not loading
+- Check: `pi list` should show `@picassio/pi-para`
+- Try: `pi -e npm:@picassio/pi-para` for a quick test
+
+### qmd not found
+- Check: `which qmd` and `qmd --version`
+- Install: `npm install -g @picassio/qmd`
+
+### Search not working (no results)
+- BM25 works immediately after `wiki_write`
+- Vector search needs providers configured in `~/.config/qmd/index.yml`
+- Check: `/wiki-settings` shows providers
+
+### Daemon not running
+- Check: `systemctl --user status pi-para-daemon`
+- Logs: `journalctl --user -u pi-para-daemon -n 20`
+- Manual start: `cd <pi-para-dir> && npx tsx src/cli.ts start`
+
+### Vulkan/CMake errors in logs
+- These are from qmd's node-llama-cpp dependency (safe to ignore)
+- They only appear if no API providers configured
+- Fix: configure providers in `~/.config/qmd/index.yml`