@tekmidian/pai 0.65.0 → 0.65.1

package/docs/observations.md

@@ -0,0 +1,58 @@
+# Automatic Observation Capture
+
+PAI automatically classifies and stores every significant tool call during your sessions. When you edit a file, run a command, or make a decision, PAI captures it as a structured observation — building a searchable timeline of everything you've done across all projects.
+
+## How it works
+
+A PostToolUse hook fires after every Claude Code tool call. A rule-based classifier (no AI needed, under 50ms) categorizes each action:
+
+| Type | What triggers it | Examples |
+|------|-----------------|----------|
+| **decision** | Git commits, config changes | `git commit`, writing to config files |
+| **bugfix** | Test runs, error investigation | `npm test`, debugging commands |
+| **feature** | New file creation, feature work | Creating components, adding endpoints |
+| **refactor** | Code restructuring | Renaming, moving files, reorganizing |
+| **discovery** | File reads, searches | Reading code, grep searches, glob patterns |
+| **change** | File edits | Editing source files, updating configs |
+
+Observations are stored with content-hash deduplication (30-second window) to prevent duplicates from rapid tool calls.
+
+## Progressive context injection
+
+At session start, PAI injects recent observations as layered context:
+
+1. **Compact index** (~100 tokens) — observation type counts and active projects
+2. **Timeline** (~500 tokens) — recent observations with timestamps
+3. **On-demand** — full details available via MCP tools
+
+This means Claude starts every session already knowing what you were working on, without you re-explaining anything.
+
+## Searching observations
+
+Ask Claude naturally:
+
+```
+"What changes did I make to the daemon today?"
+"Show me all decisions from the last session"
+"What files did I modify in the PAI project this week?"
+```
+
+Or use the CLI:
+
+```bash
+# List recent observations
+pai observation list
+
+# Filter by type
+pai observation list --type decision
+
+# Filter by project
+pai observation list --project pai
+
+# Show stats
+pai observation stats
+```
+
+## Session summaries
+
+When a session ends, PAI generates a structured summary capturing what was requested, investigated, learned, completed, and what the next steps are. These summaries feed into the progressive context system, giving future sessions a concise picture of past work.

package/docs/release-history.md

@@ -0,0 +1,42 @@
+# Release History
+
+31 releases shipped from v0.7.2 to v0.10.0 (March 19 – May 21, 2026):
+
+| Version | Feature |
+|---------|---------|
+| v0.7.2 | Auto-registration, one-note-per-session, Reconstruct skill |
+| v0.7.3 | Automatic AI-powered session notes via daemon |
+| v0.7.4 | Auto-register on parent match |
+| v0.7.5 | Tiered model selection (opus/sonnet/haiku) |
+| v0.7.6 | Find claude binary in launchd |
+| v0.7.7 | Whisper rules hook |
+| v0.7.8 | Strip API key from daemon (prevent billing) |
+| v0.8.0 | Topic-based note splitting |
+| v0.8.1 | /whisper skill, remove hardcoded defaults |
+| v0.8.2 | Reduce topic split sensitivity |
+| v0.8.3 | /consolidate skill |
+| v0.8.4 | Store TOPIC in HTML comment |
+| v0.8.5 | God-note detection, confidence tagging, Louvain communities, query feedback |
+| v0.9.0 | 4-layer wake-up, temporal KG, taxonomy, tunnels, mid-session auto-save |
+| v0.9.1 | KG backfill CLI, shared kg-extraction module |
+| v0.9.2 | Stop-hook first-run safeguard |
+| v0.9.3 | Silence stop-hook diagnostics |
+| v0.9.4 | Remove exit(2) noise |
+| v0.9.5 | Budget-aware advisor mode |
+| v0.9.6 | Statusline auto-writes budget to advisor |
+| v0.9.7 | Advisor mode label in statusline, natural language mode switching |
+| v0.9.8 | Privacy tags, compact search format, npx install |
+| v0.9.9 | Fix advisor mode to delegate to haiku instead of hoarding in opus |
+| v0.9.10 | Cognee-inspired three-tier memory: entity deduplication, graph-completion search, feedback EMA |
+| v0.9.11 | Session-commands hook for truncation resilience |
+| v0.9.12 | Dispatcher uses openFederation directly for kg_search/feedback |
+| v0.9.13 | Emit chunk IDs in memory_search output |
+| v0.9.14 | AIBroker live-session integration: `pai sessions` shows live iTerm2 panes |
+| v0.9.15 | `pai pause all`: pause every live Claude session at once via AIBroker |
+| v0.9.16 | createHash import fix, registry scan clc fallback map |
+| v0.9.17 | Switch live-session listing to `sessions` IPC (metadata-only, faster); `--all-tabs` flag |
+| v0.9.18 | `pai projects`: moved-project auto-detect, rebind command, active-only default listing |
+| v0.10.0 | Topic-first redesign: `pai <topic>` universal resolver, history search, sticky tab titles |
+| v0.10.1 | `pai sessions clear-names` recovery command |
+| v0.11.0 | Deduped session listing + universal `pai <name>` (switch / resume / fresh) |
+| v0.12.0 | Interactive picker: `pai` opens a modal search-and-act selector over projects + sessions (g go · n new · c cd · f finder · d remove); note-keyword filtering; quoted exit-dir path |

package/docs/rules-and-privacy.md

@@ -0,0 +1,37 @@
+# Whisper Rules and Privacy Tags
+
+## Whisper Rules
+
+PAI provides a hook that injects user-defined rules into every prompt via `UserPromptSubmit`. Rules survive compaction, `/clear`, and session restarts — they fire on every single turn, making them the most reliable way to enforce behavioral constraints.
+
+**PAI ships the mechanism. You provide the rules.** The file `~/.claude/pai/whisper-rules.md` does not exist by default. Use the `/whisper` skill to manage your rules:
+
+```
+/whisper                          — show current rules
+/whisper add "NEVER send emails"  — add a rule
+/whisper remove 3                 — remove rule #3
+/whisper list                     — list with line numbers
+```
+
+Or edit `~/.claude/pai/whisper-rules.md` directly — one rule per line, plain text.
+
+**Keep rules focused.** Every rule is injected on every prompt. Too many rules dilute effectiveness and waste tokens. Reserve whisper rules for truly critical constraints that keep getting violated despite being in CLAUDE.md.
+
+The pattern is inspired by [Letta's claude-subconscious](https://github.com/letta-ai/claude-subconscious) approach to persistent context injection.
+
+## Privacy Tags
+
+Wrap any content in `<private>...</private>` tags to exclude it from PAI's memory index. Private content is stripped before chunking — it's never stored, never searched, never surfaced.
+
+```markdown
+## API Keys
+<private>
+STRIPE_KEY=sk_live_abc123
+DATABASE_URL=postgres://user:pass@host/db
+</private>
+
+## Architecture Notes
+The payment system uses Stripe webhooks...
+```
+
+The architecture notes get indexed. The API keys don't. Works in session notes, memory files, and any markdown PAI indexes.

package/docs/search.md

@@ -0,0 +1,169 @@
+# Search
+
+## Token-Efficient Search (3-Layer Pattern)
+
+For budget-conscious usage, PAI supports a compact search format that returns ~10x fewer tokens per result. Instead of fetching full snippets upfront, get a compact index first, then drill into interesting results.
+
+### The workflow
+
+```
+1. Search with format="compact"  →  IDs + paths + scores (~50 tokens/result)
+2. Review the index, pick interesting results
+3. Use memory_get to read full content for those specific files
+```
+
+### Example
+
+```
+"Search for authentication with compact format"
+  → Claude passes format: "compact" to memory_search
+  → Gets a tight index: [1] pai — src/auth.ts L10-45 score=0.892
+  → Then reads only the files that matter
+```
+
+Via MCP, pass `format: "compact"` to the `memory_search` tool. Default is `"full"` (current behavior with snippets).
+
+### Section-aware retrieval
+
+Long notes are chunked at their headings, and every chunk carries its heading path as a first line, for example `[Decisions > Worker routing > Provider choice]`. A search for "routing" therefore finds the paragraph under that sub-section even when the paragraph never uses the word. Headings inside code fences are ignored.
+
+For long files, read by section instead of whole:
+
+```
+1. memory_outline(project, path)  →  heading tree with line ranges and token estimates
+      ## Previous handovers  L45-195 ~2361t
+        ### Shipped (2026-09-29)  L60-66 ~251t
+2. memory_get(project, path, from=60, lines=7)  →  just that section
+```
+
+`memory_outline` returns structure only, never text, and takes an optional `max_depth`.
+
+When the chunking logic changes, `CHUNKER_VERSION` in `src/memory/chunker.ts` is bumped. It is part of each file's change-detection hash, so the first index pass after an upgrade re-chunks and re-embeds every file once; later passes skip unchanged files as before. On a large index that pass takes hours of local CPU for embeddings, and semantic search misses files until they are re-embedded, so restart the daemon onto a new version at a quiet time.
+
+## Search Intelligence
+
+PAI doesn't just store your notes — it understands them. Three search modes work together, with reranking and recency boost on by default. All search settings are configurable.
+
+### Search Modes
+
+| Mode | How it works | Best for |
+|------|-------------|----------|
+| **Keyword** | Full-text search (BM25 via SQLite FTS5) | Exact terms, function names, error messages |
+| **Semantic** | Vector similarity (Snowflake Arctic embeddings) | Finding things by meaning, even with different words |
+| **Hybrid** | Keyword + semantic combined, scores normalized and blended | General use — the default |
+
+### Cross-Encoder Reranking
+
+Every search automatically runs a second pass: a cross-encoder model reads each (query, result) pair together and re-scores them for relevance. This catches results that keyword or vector search ranked too low.
+
+```bash
+# Search with reranking (default)
+pai memory search "how does session routing work"
+
+# Skip reranking for faster results
+pai memory search "how does session routing work" --no-rerank
+```
+
+The reranker uses a small local model (~23 MB) that runs entirely on your machine. First use downloads it automatically. No API keys, no cloud calls.
+
+### Recency Boost
+
+Recent content scores higher than older content — on by default with a 90-day half-life. A 3-month-old result retains 50% of its score, a 6-month-old retains 25%, and a year-old retains ~6%.
+
+```bash
+# Search uses recency boost automatically (90-day half-life from config)
+pai memory search "notification system"
+
+# Override the half-life for this search
+pai memory search "notification system" --recency 30
+
+# Disable recency boost for this search
+pai memory search "notification system" --recency 0
+```
+
+Via MCP, pass `recency_boost: 90` to the `memory_search` tool, or `recency_boost: 0` to disable.
+
+Recency boost is applied after cross-encoder reranking, so relevance is scored first, then time-weighted. Scores are normalized before decay so the math works correctly regardless of the underlying score scale.
+
+### Search Settings
+
+All search defaults are configurable via `~/.claude/pai/config.json` and can be viewed or changed from the command line.
+
+```bash
+# View all search settings
+pai memory settings
+
+# View a single setting
+pai memory settings recencyBoostDays
+
+# Change a setting
+pai memory settings recencyBoostDays 60
+pai memory settings mode hybrid
+pai memory settings rerank false
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `mode` | `keyword` | Default search mode: `keyword`, `semantic`, or `hybrid` |
+| `rerank` | `true` | Cross-encoder reranking on by default |
+| `recencyBoostDays` | `90` | Recency half-life in days. `0` = off |
+| `defaultLimit` | `10` | Default number of results |
+| `snippetLength` | `200` | Max characters per snippet in MCP results |
+
+Settings live in the `search` section of `~/.claude/pai/config.json`. Per-call parameters (CLI flags or MCP tool arguments) always override config defaults.
+
+### Using Search from Within Claude
+
+When PAI is configured as an MCP server, Claude uses the `memory_search` tool automatically. You don't need to call it yourself — just ask Claude naturally and it searches your memory behind the scenes.
+
+**Example prompts you can give Claude:**
+
+```
+"Search your memory for authentication"
+"What do you know about the database migration?"
+"Find where we discussed the notification system"
+```
+
+Claude calls `memory_search` with the right parameters based on your config defaults. Reranking and recency boost are both active by default — you don't need to configure anything for good results.
+
+**Overriding defaults for a specific search:**
+
+You can ask Claude to adjust search behavior per-query:
+
+```
+"Search for authentication using semantic mode"
+  → Claude passes mode: "semantic"
+
+"Search for the old logging discussion without recency boost"
+  → Claude passes recency_boost: 0
+
+"Search for database schema across all projects with no reranking"
+  → Claude passes all_projects: true, rerank: false
+```
+
+**The `memory_search` MCP tool accepts these parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Free-text search query (required) |
+| `project` | string | Scope to one project by slug |
+| `all_projects` | boolean | Explicitly search all projects |
+| `sources` | array | Restrict to `"memory"` or `"notes"` |
+| `limit` | integer | Max results (1–100, default from config) |
+| `mode` | string | `"keyword"`, `"semantic"`, or `"hybrid"` |
+| `rerank` | boolean | Cross-encoder reranking (default: true from config) |
+| `recency_boost` | integer | Recency half-life in days (0 = off, default from config) |
+
+All parameters except `query` are optional. Omitted values fall back to your `~/.claude/pai/config.json` defaults.
+
+**Changing defaults permanently:**
+
+Tell Claude to change your search settings:
+
+```
+"Set my default search mode to hybrid"
+"Turn off reranking by default"
+"Change the recency boost to 60 days"
+```
+
+Claude runs `pai memory settings <key> <value>` to update `~/.claude/pai/config.json`. Changes take effect on the next search — no restart needed.

package/docs/session-management.md

@@ -0,0 +1,153 @@
+# Session Management
+
+PAI gives you a complete picture of every Claude Code session running on your machine — live tabs in iTerm2, paused snapshots on disk, and everything in between.
+
+## The Core Idea: One Entry Point
+
+Two ways in, both forgiving:
+
+- **`pai`** (no args) — opens the **interactive picker**: type to search across projects *and* sessions, then act on the highlighted row with a single key.
+- **`pai <name>`** — the universal session command when you already know the name. It does the right thing based on session state:
+  - **Live session** — switches the iTerm2 tab to front (no new Claude launched)
+  - **Otherwise** — starts a fresh Claude in the project directory, on the configured route. If a resumable transcript exists it asks `Resume it? [y/N]` first (Enter keeps fresh); `--resume` or `pai resume <name>` resume without asking; `-y` skips the question.
+  - **No match** — searches `~/.claude/history.jsonl`, shows a candidate picker
+
+```bash
+pai                 # Interactive picker — search, then go / new / cd / finder / remove
+pai aibroker        # Switch to the live AIBroker tab (iTerm comes to front)
+pai youdrill        # Fresh youdrill session; offers to resume the last transcript
+pai mdf             # Free-text search across your prompt history
+pai 0856d40b        # Resume by UUID prefix
+pai --list          # Static deduped table (the old no-args behaviour)
+```
+
+## Daily Commands
+
+```bash
+pai                   # Interactive picker (projects + sessions; search then act)
+pai --list            # Static deduped listing (one row per name)
+pai <name>            # Switch / resume / fresh — universal
+pai pause             # Save state checkpoint (write ## Continue to TODO.md)
+pai pause all         # Pause every live Claude session at once
+pai end               # Finalize: save state + mark session note Completed
+```
+
+And inside Claude Code, the two slash commands that matter:
+
+```
+/pause    →  write checkpoint to TODO.md, print handoff block, then type /exit
+/end      →  same as /pause, plus marks the session note Completed
+```
+
+## The Interactive Picker
+
+Run `pai` with no arguments to open a self-contained terminal selector (no `fzf` or other dependency) over a **unified, deduped list of both projects and sessions** — tagged so the two stay distinct. It's the one place to answer "where did I work on X, and take me there."
+
+```
+  pai  —  find a project or session
+  search > samba
+
+  live      Chenarlier   now   …/Raspi/Chenarlier   samba setup monster reverse proxy
+  project   Glidr        2d    …/apps/glidr          claude pai research
+
+  ────────────────────────────────────────
+  Chenarlier   ~/…/Raspi/Chenarlier
+  recent notes:
+    10 - Samba Setup/01 - Samba Server Setup.md   1mo
+    00 - Monster/00 - Monster.md                  3mo
+  ────────────────────────────────────────
+  g go to tab · n new · c cd · f finder · d remove · s search · ↑↓ move · q quit
+```
+
+**Two modes.** You start in *command mode* (single keys are actions). Press `s` (or `/`) to enter *search mode* (type a topic — it filters by name, path, **and folded-in note file/folder names**, so `samba` finds a project literally named "Chenarlier"); `Enter` or `esc` returns to command mode.
+
+**Command keys** act immediately on the highlighted row:
+
+| Key | Action |
+|-----|--------|
+| `g` | **Go to** the running iTerm2 tab (for live rows) |
+| `n` | **New** Claude session in that directory (current terminal) |
+| `c` | **cd** into the folder only — no Claude (your shell stays there) |
+| `f` | Open the folder in **Finder** / Explorer / `xdg-open` (keeps the picker open) |
+| `d` | **Remove** from PAI's list — archives the project (reversible, files untouched); asks `y/N` first |
+| `s` `/` | Enter **search** mode |
+| `↑↓` `j` `k` | Move the highlight |
+| `q` `esc` | Quit |
+
+`Enter` on a row takes the smart default: a live row → go to its tab, otherwise → new session.
+
+The `c` (cd) action needs PAI's shell integration to change your shell's directory — see [Finding the Claude Binary](#finding-the-claude-binary) / `pai shell-init`. On a non-interactive terminal (piped output), `pai` falls back to the static listing automatically.
+
+## Static Listing
+
+`pai --list` shows a single deduped table — one row per session name, regardless of how many snapshots exist on disk:
+
+```
+Sessions:
+
+  #   name        status      age       project                       last prompt
+  --  ----------  ----------  --------  ----------------------------  --------------------------
+  1   AIBroker    live        now       —                             —
+  2   PAI         resumable   2m ago    /…dev/ai/PAI                  "refactor session listing…"
+  3   MDF         transcript  3d ago    /…MDF/Infrastruktur/Webseiten "ok so we recently had…"
+```
+
+Status values: `live` (active iTerm tab), `resumable` (clean snapshot on disk), `transcript` (history available, not resumable), `stub` (empty or minimal).
+
+## Finding Sessions by Topic
+
+`pai <topic>` first checks session names, then falls back to searching your prompt history:
+
+```
+Sessions matching "mdf":
+
+  #  id        when              project                              last matching prompt
+  -  --------  ----------------  -----------------------------------  -------------------------
+  1  6269cf64  2026-05-21 08:20  /…MDF/Infrastruktur/20 - Webseiten  "ok so we recently had an order…"
+  2  abe2d977  2026-02-23 08:40  /…MDF/Infrastruktur/20 - Webseiten  "yes the session notes for Whazaa…"
+
+  Enter # to launch (1-2), or press Enter to cancel:
+```
+
+Use `pai <topic> --auto` (or `-y`) to auto-pick #1. Use `pai <topic> 2` to pick directly.
+
+## Power User Access
+
+The full session management namespace is still available:
+
+```bash
+pai sessions              # Live + disk listing (with more columns)
+pai sessions --all        # Include unnamed orphan sessions
+pai sessions --all-tabs   # Include shell tabs in the live section
+pai sessions goto <name>  # Named-session resolver (same as pai <name>)
+pai sessions list         # Explicit listing (same as pai sessions)
+```
+
+## Pausing All Sessions at Once
+
+When you're done for the day and have multiple Claude windows open:
+
+```bash
+pai pause all             # send "pause session" to every live Claude pane
+pai pause all --dry-run   # preview what would be sent
+pai pause all --exit      # also send /exit after each session saves state
+```
+
+AIBroker must be running for this to work. Shell tabs (bare zsh, SSH panes) are automatically skipped — only Claude Code panes receive the pause command. The count of skipped tabs is printed to stderr.
+
+## /pause and /end Inside Claude Code
+
+Type `/pause` or `/end` from inside an active Claude Code session (not from a shell — these are Claude Code slash commands, not CLI commands):
+
+- `/pause` — Claude writes a `## Continue` block to the project's `TODO.md`, prints a handoff summary with the session ID, then tells you to type `/exit`. The next session starts by reading that TODO.md block and picking up exactly where you left off.
+- `/end` — Same as `/pause`, plus Claude marks the session note as Completed and writes a final summary. Use this when you're genuinely done with a topic, not just pausing mid-task.
+
+After either command, type `/exit` to exit Claude Code cleanly.
+
+## Why /exit and Not Ctrl+C
+
+Ctrl+C or closing the terminal kills the Claude Code process abruptly. The session note generation hook never fires, the checkpoint is not written, and the session cannot be resumed with `claude --resume`.
+
+`/exit` sends a clean shutdown signal. Claude Code runs its Stop and Session End hooks, which trigger PAI to write the session note, push the final summary to the daemon, and save a resumable snapshot. The difference in recovery quality between a clean `/exit` and a Ctrl+C is significant for long sessions.
+
+If you do accidentally close a terminal, use `pai sessions --all` to find the orphaned transcript. The `/reconstruct` skill can retroactively generate a session note from it.

package/docs/session-notes.md

@@ -0,0 +1,64 @@
+# Automatic Session Notes
+
+## Automatic Session Notes — by Topic
+
+PAI's headline feature: **every session is automatically documented.** No manual note-taking, no "pause session" commands, no forgetting to save what you did.
+
+When you work, a background daemon watches your session **continuously**. Every time Claude's context compacts — which happens automatically as the conversation grows — the daemon reads the JSONL transcript, combines it with your git history, and spawns a headless Claude process to write a structured session note. Not just at session end. Midway through your work, while you're still coding. The notes build up in real time as you go — what was built, what decisions were made, what problems were hit, what's left to do.
+
+**When you change topics mid-session, PAI creates a new note.** If you start the day debugging audio, then pivot to a Flutter rewrite, you get two notes — not one giant file mixing unrelated work:
+
+```
+Notes/2026/03/
+  0001 - 2026-03-23 - Phase 1 Research and Architecture.md
+  0002 - 2026-03-24 - Background Audio and iOS Conflicts.md
+  0003 - 2026-03-24 - Flutter Rewrite with Whisper.md     ← auto-split, same day
+```
+
+Topic detection uses Jaccard word similarity between the new summary's topic and the existing note's title. Below 30% overlap = new note.
+
+**Model tiering:** Opus for final session summaries (best quality, runs once). Sonnet for mid-session checkpoints (good quality, runs on compaction). All using your Max plan — no API charges.
+
+This is not a template or a skeleton. These are real notes with build error chronologies, architectural decisions with rationale, code snippets, and "what was tried and failed" sections. The kind of notes you'd write yourself if you had time.
+
+## Automatic Session Notes
+
+PAI automatically writes structured session notes after every session ends — no manual journaling required. The daemon spawns a headless Claude CLI process (using your Max plan, not the API) to summarize the JSONL conversation transcript combined with recent git history.
+
+### What Gets Generated
+
+Each session note contains:
+
+- **Work Done** — concrete description of what was accomplished
+- **Key Decisions** — choices made and their rationale
+- **Known Issues** — bugs found, blockers, or open questions
+- **Next Steps** — where to pick up in the next session
+
+The summarizer uses tiered model selection based on the trigger:
+
+| Trigger | Model | Timeout | JSONL Limit |
+|---------|-------|---------|-------------|
+| Session end (Stop hook) | Opus | 5 minutes | 500K bytes |
+| Auto-compaction (PreCompact hook) | Sonnet | 2 minutes | 200K bytes |
+
+### Topic-Based Note Splitting
+
+When a session covers multiple distinct topics, PAI creates separate notes rather than one long note for the whole session. The summarizer outputs a `TOPIC:` line describing the subject of the current work. PAI compares this against the existing note title using Jaccard word similarity — when similarity falls below 30%, a new note is created automatically.
+
+Notes within the same day are numbered sequentially: `0042 - 2026-03-24 - Session Name.md`, `0043 - 2026-03-24 - Different Topic.md`, and so on.
+
+### One Note Per Session
+
+Each compaction within a session updates the existing note rather than creating a new one. The 30-minute cooldown between summaries prevents redundant updates. Stop hook triggers bypass the cooldown with a force flag to ensure the final state is always captured.
+
+### Garbage Title Filter
+
+Session note titles are validated before creation. Over 20 patterns are rejected, including: task notification strings, `[object Object]`, hex hashes, bare numbers, and other non-descriptive artifacts that can appear in session transcripts. Titles must describe actual work done and are capped at 60 characters.
+
+### Finding the Claude Binary
+
+The daemon runs under launchd with a minimal PATH that does not include `~/.local/bin/`. PAI resolves the Claude CLI binary by checking `~/.local/bin/claude` first, then falling back to PATH lookup, before spawning headless summarization processes.
+
+### Stripping the API Key
+
+When spawning headless Claude CLI processes for summarization, the daemon strips `ANTHROPIC_API_KEY` from the subprocess environment. This forces the spawned process to authenticate via your Max plan (free) rather than using the API key (billable). Without this, every automatic session note would incur API charges.

package/docs/skills.md

@@ -0,0 +1,45 @@
+# Skills
+
+PAI ships 22 skills — slash commands that activate specialized workflows. Each responds to natural language triggers as well as the `/command` syntax.
+
+## Productivity
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/advisor` | "budget mode", "save budget", "go easy on the budget" | Manage budget-aware model tiering for subagents |
+| `/plan` | "plan my week", "what should I focus on", "priorities" | Plan tomorrow/week/month based on open tasks and calendar |
+| `/review` | "review my week", "what did I do", "recap" | Daily/weekly/monthly review of work accomplished |
+| `/journal` | "journal", "note to self", "capture this thought" | Create, read, or search personal journal entries |
+| `/share` | "share on LinkedIn", "tweet about", "post to Bluesky" | Generate social media posts about completed work |
+
+## Session Management
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/sessions` | "list sessions", "where was I working" | Navigate sessions, projects, switch working context |
+| `/route` | "what project is this", "tag this session" | Detect which PAI project the current session belongs to |
+| `/name` | "name this session", "rename session" | Name or rename the current session |
+| `/search-history` | "search history", "find past", "what did we do" | Search past sessions and previous work by keyword |
+| `/consolidate` | "consolidate notes", "clean up notes", "merge duplicates" | Merge duplicate session notes, fix titles, renumber |
+| `/reconstruct` | "reconstruct sessions", "backfill session notes" | Retroactively create notes from JSONL transcripts and git history |
+
+## Obsidian Vault
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/vault-context` | "morning briefing", "load vault context" | Load Obsidian vault context for a briefing |
+| `/vault-connect` | "connect X and Y", "how does X relate to Y" | Find connections between two topics in the vault |
+| `/vault-emerge` | "what's emerging", "find patterns", "themes in vault" | Surface emerging themes and clusters |
+| `/vault-orphans` | "find orphans", "unlinked notes" | Find and reconnect orphaned notes with zero inbound links |
+| `/vault-trace` | "trace idea", "how did X evolve", "idea history" | Trace the evolution of an idea across vault notes over time |
+
+## Tools & System
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/whisper` | "add whisper rule", "show whisper rules" | Manage persistent behavioral constraints injected on every prompt |
+| `/research` | "do research", "extract wisdom", "analyze content" | Web research, content extraction, and analysis via parallel agents |
+| `/art` | "create diagram", "flowchart", "visualize" | Create visual content, diagrams, flowcharts, and AI-generated images |
+| `/story` | "explain this as a story", "create story explanation" | Create numbered narrative story explanations of any content |
+| `/observability` | "start observability", "monitor agents" | Start, stop, or check the multi-agent observability dashboard |
+| `/createskill` | "create skill", "validate skill" | Create, validate, update, or canonicalize a PAI skill |

package/docs/task-bus.md

@@ -2,8 +2,7 @@
 
 File a task from your phone. A session picks it up, does the work, and ticks it off.
 
-This document is the setup guide. For why the design splits the way it does, see
-`Notes/docs/task-bus.md`.
+This document is the setup guide.
 
 ---