@tekmidian/pai 0.64.0 → 0.65.1

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.
 
 ---
 

package/docs/use-cases.md

@@ -0,0 +1,194 @@
+# PAI Knowledge OS - Use Cases
+
+
+## 1. Solo Developer - Building a SaaS Product
+
+### The Person
+
+Alex builds a project management SaaS solo. Alternates between frontend (React), backend (Node.js), infrastructure (AWS), and customer support. Uses Claude Code 8-10 hours a day.
+
+### Before PAI
+
+Every morning, Alex spends 20 minutes re-explaining the project to Claude: "We're building a PM tool, here's the stack, here's where we left off on the notification system, the database schema looks like this..." When context compaction hits mid-afternoon, another 15 minutes gone. Multiply by 250 working days: **145 hours per year re-explaining context**.
+
+### After PAI
+
+Alex says "Go" and Claude reads the TODO.md continuation prompt. It knows the project, the stack, the current sprint, and what broke yesterday. When compaction hits, PAI's relay preserves state automatically. Alex's weekly review ("review my week") generates a narrative of everything accomplished - useful for investor updates.
+
+**Key features used:** Session continuity, context preservation, project registry, plan skill, review skill
+
+---
+
+## 2. Team Lead - Managing Multiple Codebases
+
+### The Person
+
+Jordan manages 5 microservices, 3 frontend apps, and a shared library. Switches between projects 10-15 times per day. Has 3 junior developers asking questions about architecture decisions made months ago.
+
+### Before PAI
+
+Jordan cannot remember which session had the discussion about the event bus architecture. The junior dev asks "why did we choose RabbitMQ over Kafka?" and Jordan has to dig through Slack, Notion, and git commit messages to reconstruct the reasoning.
+
+### After PAI
+
+Jordan searches: "Search your memory for message queue decision." PAI finds the session from 6 weeks ago where the tradeoffs were discussed, including the specific latency requirements that ruled out Kafka. The junior dev gets a complete answer in 30 seconds.
+
+**Key features used:** Memory search, cross-project sessions, session history, project registry, observation capture
+
+---
+
+## 3. Researcher - Academic Paper Writing
+
+### The Person
+
+Dr. Chen writes papers using Claude Code for LaTeX editing, data analysis scripts, and literature review organization. Works on 3 papers simultaneously with different co-authors.
+
+### Before PAI
+
+Each paper requires different context: methodologies, related work, reviewer comments. Switching between papers means a 10-minute context dump each time. Literature connections between papers are tracked manually in a spreadsheet.
+
+### After PAI
+
+Each paper is a PAI project. "Which project am I in?" auto-detects from the directory. Dr. Chen's Obsidian vault is indexed by PAI's Zettelkasten system. "Find surprising connections to this note on attention mechanisms" discovers a relevant paper in the NLP project that applies to the computer vision paper - a connection Dr. Chen missed.
+
+**Key features used:** Project registry, Zettelkasten (surprise, themes), session management, vault intelligence
+
+---
+
+## 4. Consultant - Client Project Rotation
+
+### The Person
+
+Maria is a freelance developer working with 6 clients simultaneously. Each client has different tech stacks, coding standards, deployment processes, and communication preferences.
+
+### Before PAI
+
+Monday: Maria works on Client A's Django project. Tuesday: Client B's React app. By Wednesday, she can't remember Client A's specific deployment process. She keeps a folder of client context documents that she manually pastes into Claude sessions.
+
+### After PAI
+
+Maria's 6 clients are 6 PAI projects. "What's the deployment process for Client A?" - PAI finds it in session notes from last week. Observations capture every deployment command she ran, so the process is reconstructible even if she never wrote it down. Weekly reviews per client make invoicing easy.
+
+**Key features used:** Multi-project management, observation capture, memory search, review skill, session history
+
+---
+
+## 5. Open Source Maintainer - Community Management
+
+### The Person
+
+Sam maintains a popular open source library with 5,000 GitHub stars, 200+ issues, and regular pull request reviews.
+
+### Before PAI
+
+Contributors ask the same architectural questions repeatedly. "Why is this implemented this way?" Sam re-explains the same reasoning in GitHub issues, Discord, and PR reviews. Design decisions from 8 months ago are lost in conversation history.
+
+### After PAI
+
+Sam's design decisions are captured as observations. "Search your memory for the decision about the plugin API" finds the session where the API was designed, including rejected alternatives and the reasoning. Sam uses the Share skill to generate a technical blog post about the architecture for the project's documentation.
+
+**Key features used:** Observation capture (decisions), memory search, share skill, review skill
+
+---
+
+## 6. Job Seeker - Application Management
+
+### The Person
+
+Lisa is a senior engineer looking for her next role. She's applying to 15 companies, each requiring tailored cover letters and application tracking.
+
+### Before PAI
+
+Lisa tracks applications in a spreadsheet. Each cover letter requires manually adapting her experience to the job description. Follow-up timing is tracked with calendar reminders.
+
+### After PAI
+
+With SeriousLetter MCP (companion), Lisa's applications are managed through Claude. PAI remembers each company's context: "What did I tell Acme Corp about my distributed systems experience?" The journal skill tracks her reflections after interviews. The review skill generates weekly job search summaries.
+
+**Key features used:** SeriousLetter integration, journal skill, review skill, project management, memory search
+
+---
+
+## 7. Content Creator - Technical Writing
+
+### The Person
+
+Dev writes a weekly technical newsletter and produces YouTube tutorials. Uses Claude Code to help draft content, write code examples, and edit scripts.
+
+### Before PAI
+
+Dev cannot easily find previous content to avoid repetition. "Did I already write about rate limiting?" requires manually searching through 50+ newsletter editions. Code examples are lost in old Claude sessions.
+
+### After PAI
+
+"Search your memory for rate limiting" instantly shows what Dev has written. The Share skill generates newsletter drafts and social media posts from recent work. Code examples from any session are retrievable. "Review my month" generates a content roundup.
+
+**Key features used:** Memory search, share skill (LinkedIn, X, Bluesky), review skill, session history
+
+---
+
+## 8. Knowledge Worker - Building a Second Brain
+
+### The Person
+
+Pat is a product manager who uses Obsidian to track market research, user interviews, competitive analysis, and product strategy. Has 2,000+ notes accumulated over 3 years.
+
+### Before PAI
+
+Obsidian search is keyword-only. Pat knows there's a connection between the user interview from March and the competitive analysis from June, but can't find it. Notes accumulate but connections between them are manual.
+
+### After PAI
+
+PAI's Zettelkasten module indexes Pat's vault. "What themes are emerging in my vault?" detects clusters of related notes forming around "AI-first workflows." "Suggest connections for this note" proposes 5 links Pat never considered. "How healthy is my vault?" reveals 47 orphaned notes that need integration.
+
+**Key features used:** Zettelkasten (all 6 operations), vault indexing, semantic search, themes, health
+
+---
+
+## 9. Security Auditor - Compliance and Penetration Testing
+
+### The Person
+
+Robin conducts security audits for enterprise clients. Each engagement produces hundreds of findings, code reviews, and remediation recommendations.
+
+### Before PAI
+
+Previous audit findings are buried in PDF reports. When Robin encounters a similar vulnerability pattern at a new client, there's no quick way to reference how it was documented and remediated before.
+
+### After PAI
+
+Each audit is a PAI project. "Search your memory for SQL injection remediation" finds findings from previous audits, including specific remediation code. Observations automatically capture every security-relevant command and finding. Session summaries create audit trails. The research skill structures vulnerability analysis.
+
+**Key features used:** Project registry, observation capture, memory search, session summaries, research skill
+
+---
+
+## 10. AI-First Company - Engineering Team
+
+### The Person
+
+A 12-person startup where every engineer uses Claude Code daily. The CTO wants institutional knowledge to survive employee turnover and ensure architectural decisions are documented.
+
+### Before PAI
+
+When Engineer A leaves, their Claude Code sessions (and all the architectural reasoning) vanish. The replacement spends 2 months reconstructing context. Design decisions are scattered across Slack, Notion, and individual engineers' heads.
+
+### After PAI
+
+Every engineer runs PAI. Architectural decisions are automatically captured as observations. Memory search works across all projects. When Engineer A leaves, their session history, observations, and decision trail remain searchable. New engineers search "why did we choose GraphQL" and get the complete reasoning. The review skill generates team-wide weekly summaries for the CTO.
+
+**Key features used:** Multi-project registry, observation capture (decisions), memory search (cross-project), review skill, session continuity
+
+---
+
+## Common Patterns Across Use Cases
+
+| Pattern | PAI Feature | Time Saved |
+|---------|------------|------------|
+| Re-explaining context every session | Session continuity, context preservation | 15-30 min/session |
+| Finding past decisions | Observation capture, memory search | Hours/week |
+| Tracking work across projects | Project registry, cross-project search | Hours/week |
+| Creating content from work | Share, Review skills | 2-4 hours/week |
+| Maintaining knowledge connections | Zettelkasten operations | Manual impossible |
+| Surviving context compaction | Two-stage relay | 15 min/compaction |
+| Onboarding new team members | Searchable institutional memory | Weeks/hire |

package/docs/what-you-can-ask.md

@@ -0,0 +1,78 @@
+# What You Can Ask Claude
+
+## Searching Your Memory
+
+- "Search your memory for authentication" — finds past sessions about auth, even with different words
+- "What do you know about the Whazaa project?" — retrieves full project context instantly
+- "Find where we discussed the database migration" — semantic search finds it even if you phrase it differently
+- "Search your memory for that Chrome browser issue" — keyword and meaning-based search combined
+
+## Managing Projects
+
+- "Show me all my projects" — lists everything PAI tracks with stats
+- "Which project am I in?" — auto-detects from your current directory
+- "What's the status of the PAI project?" — full project details, sessions, last activity
+- "How many sessions does Whazaa have?" — project-level session history
+
+## Navigating Sessions
+
+- "List my recent sessions" — shows what you've been working on across all projects
+- "What did we do in session 42?" — retrieves any specific session by number
+- "What were we working on last week?" — Claude knows, without you re-explaining
+- "Clean up my session notes" — auto-names unnamed sessions and organizes by date
+
+## Reviewing Your Work
+
+- "Review my week" — synthesizes session notes, git commits, and completed tasks into a themed narrative
+- "What did I do today?" — daily review across all projects
+- "Journal this thought" — capture freeform reflections with timestamps
+- "Plan my week" — forward-looking priorities based on open TODOs and recent activity
+- "What themes are emerging in my work?" — spot patterns across sessions and projects
+
+## Sharing Your Work
+
+- "Share on LinkedIn today" — generates a professional post about what you shipped, with real numbers and technical substance
+- "Tweet about the vault migration" — punchy X/Twitter post or thread, with option to post directly
+- "Share on Bluesky this week" — conversational technical post for the Bluesky audience
+- Platform-aware formatting: LinkedIn gets hashtags and narrative, X gets threads and hooks, Bluesky gets conversational tone
+
+## Tracking Your Activity
+
+- "What changes did I make to the daemon today?" — automatic observation capture tracks every tool call
+- "Show me all decisions from the last session" — observations are classified: decision, bugfix, feature, refactor, discovery, change
+- "What files did I modify in the PAI project this week?" — searchable timeline of every edit, commit, and search
+- "Show observation stats" — totals, breakdowns by type and project, with visual bar charts
+
+## Continuing Where You Left Off
+
+- "Go" — reads your TODO.md continuation prompt and picks up exactly where the last session stopped
+- "What was I working on?" — progressive context injection loads recent observations at session start
+- "Continue the daemon refactor" — session summaries give Claude full context without re-explaining
+- "/reconstruct" — retroactively creates session notes from JSONL transcripts and git history when automatic capture missed a session
+
+## Keeping Things Safe
+
+- "Back up everything" — creates a timestamped backup of all your data
+- "How's the system doing?" — checks daemon health, index stats, embedding coverage
+
+## Obsidian Integration
+
+- "Sync my Obsidian vault" — updates your linked vault with the latest notes
+- "Open my notes in Obsidian" — launches Obsidian with your full knowledge graph
+
+## Zettelkasten Intelligence
+
+- "Explore notes linked to PAI" — follow trains of thought through wikilink chains
+- "Find surprising connections to this note" — discover semantically similar but graph-distant notes
+- "What themes are emerging in my vault?" — detect clusters of related notes forming new ideas
+- "How healthy is my vault?" — structural audit: dead links, orphans, disconnected clusters
+- "Suggest connections for this note" — proactive link suggestions using semantic + graph signals
+- "What does my vault say about knowledge management?" — use the vault as a thinking partner
+
+## Budget Management
+
+- "How much budget do I have left?" — shows current weekly usage and advisor mode
+- "Go easy on the budget" — switches to conservative mode (prefer haiku subagents)
+- "Lock it down" — switches to critical mode (minimize all token usage)
+- "Go full power" — switches to normal mode (no constraints)
+- "Back to auto" — resets to auto mode (derives from weekly budget percentage)

package/docs/worker-providers.md

@@ -0,0 +1,58 @@
+# Worker Providers — Run the Fleet Anywhere
+
+**Read the story: [Provider Independence — how I freed my stack from a single vendor in one day](provider-independence.md).**
+
+Only the outer orchestrator session runs on Anthropic. Every worker PAI spawns — research, drafting, implementation, review, spotchecks — runs on a managed provider you choose. The same provider layer carries the daemon's background calls and the session picker, so the whole stack moves together.
+
+## Why
+
+- **Vendor independence.** Any provider that speaks the Anthropic Messages protocol is a registry entry: models, key file, price tier. OpenAI-protocol providers work through a built-in translating proxy. Switching is configuration, not surgery.
+- **Cost control.** Parallel work is a commodity; it should not burn your premium seat. Workers bill against their own provider, and cheap classes resolve to the provider's fast model automatically.
+- **No lock-in to one orchestrator vendor.** Sessions run on the active provider too — the picker launches through it, and `pai worker fallback` extends that machine-wide.
+- **Survives orchestrator outages.** Workers carry their own provider credentials, so a quota freeze or outage on the vendor seat does not stop delegated work.
+
+## How
+
+- **Managed providers.** `pai worker providers add` registers one, `pai worker providers use <name>` switches the fleet, `pai worker off` disables routing entirely (the Agent tool runs on Anthropic again), `pai worker on` re-enables it. The reserved name `anthropic` needs no `add` step — it's Claude Code's own login; `pai worker providers use anthropic` switches straight to it.
+- **Start the harness itself on any provider.** `pai launch` (numbered picker, or `--provider <name> [--model <model>]`) starts a fresh Claude Code session on any provider/model in `workers.yaml` — a running session can't switch providers (base URL and auth are fixed at start), so this always begins a new one. Claude Code's own `/model` only lists the current endpoint's models; `pai launch --list` (or the `/providers` skill, from inside a session) lists every provider configured here.
+- **Classes route work to the right model.** `--class` picks the provider and model for the job: `draft`, `plan`, `implement`, `review`, `research`, `spotcheck`, `simple`, `complex`, `image`. `pai worker classes` shows and edits the mapping; `--provider` / `--model` override for a single run.
+- **Every worker spawn stands alone.** The orchestrator's API key is stripped and the spawn gets the provider's base URL, token and model ids instead — proven live: a worker answers with the parent's credentials gone. No inherited billing, no fallback to the vendor login.
+- **The route is pinned, not inherited.** Claude Code's user settings outrank the process env, so a machine-wide proxy route (a `caveman` install, a `pai worker fallback`) would otherwise swallow a worker's base URL and send its provider token to the wrong endpoint. Every spawn repeats its route with `--settings`, which outranks user settings; native-Anthropic workers are pinned to `api.anthropic.com`, or launched as `caveman claude` when `workers.caveman: true` is set in `config.yaml`. Details: [docs/worker.md](worker.md), "What a worker is".
+- **One file to configure it.** Providers, per-role model ids and class routing live in one hand-editable `workers.yaml` — adding a provider (Anthropic-compatible, OpenAI-compatible, or local) is a YAML edit, never code. Full reference: [docs/workers-config.md](workers-config.md).
+
+```yaml
+active: anthropic
+providers:
+  anthropic:
+    builtin: true                 # Claude Code's own login
+    models: { default: claude-sonnet-5, fast: claude-haiku-4-5-20251001 }
+  glm:
+    url: https://api.z.ai/api/anthropic
+    key: "<your-api-key>"         # or key_file: <path to a 0600 file>
+    tier: 3
+    models: { default: glm-5.3[1m], fast: glm-5.3-flash }
+classes:
+  implement: anthropic
+  spotcheck: anthropic/fast       # cheap classes default to the fast model
+```
+
+## What
+
+```bash
+pai worker run -p '<task>' --class implement   # one worker on a provider
+pai worker ps                                  # this session's workers (--all: every one)
+pai worker follow <id>                         # live transcript of one worker
+pai worker pane                                # shared follow pane for the session
+pai worker replay <id>                         # transcript of a finished or running worker
+pai worker say <id> <text>                     # message a running worker mid-run
+pai worker handoff '<json>'                    # from inside a worker: report to the parent
+pai worker merge <id>                          # merge the worker's branch back, drop the worktree
+pai worker wait <id>...                        # block until workers finish (never sleep-loop)
+pai worker watch                               # ps refreshed every 2 seconds
+```
+
+The rest of the surface — `discard`, `resume`, `controls`, `proxy`, `mcp`, `model`, `providers`, `classes` — is in `pai help worker` and [docs/commands/worker.md](commands/worker.md).
+
+![Workers in the statusline](images/workers.png)
+
+Get started in three copy-paste steps: **[docs/provider-independence.md](provider-independence.md)**. For the depth — provider registry, statusline instrumentation, seam patches, current limits — see **[docs/provider-abstraction.md](provider-abstraction.md)**.

package/docs/zettelkasten.md

@@ -0,0 +1,37 @@
+# Zettelkasten Intelligence
+
+PAI implements Niklas Luhmann's Zettelkasten principles as six computational operations on your Obsidian vault.
+
+## How it works
+
+PAI indexes your entire vault — following symlinks, deduplicating by inode, parsing every link — and builds a graph database alongside semantic embeddings. Six tools then operate on this dual representation:
+
+| Tool | What it does |
+|------|-------------|
+| `pai zettel explore` | Follow trains of thought through link chains (Folgezettel traversal) |
+| `pai zettel surprise` | Find notes that are semantically close but far apart in the link graph |
+| `pai zettel converse` | Ask questions and let the vault "talk back" with unexpected connections |
+| `pai zettel themes` | Detect emerging clusters of related notes across folders |
+| `pai zettel health` | Structural audit — dead links, orphans, disconnected clusters, health score |
+| `pai zettel suggest` | Proactive connection suggestions combining semantic similarity, tags, and graph proximity |
+
+All tools work as CLI commands (`pai zettel <command>`) and MCP tools (`zettel_*`) accessible through the daemon.
+
+## Vault Indexing
+
+The vault indexer follows symlinks (critical for vaults built on symlinks), deduplicates files by inode to handle multiple paths to the same file, and builds a complete link graph with Obsidian-compatible shortest-match resolution.
+
+All link types are parsed and resolved:
+
+| Syntax | Type | Example |
+|--------|------|---------|
+| `[[Note]]` | Wikilink | `[[Daily Note]]`, `[[Note\|alias]]`, `[[Note#heading]]` |
+| `![[file]]` | Embed | `![[diagram.png]]`, `![[template]]` |
+| `[text](path.md)` | Markdown link | `[see here](notes/idea.md)`, `[ref](note.md#section)` |
+| `![alt](file)` | Markdown embed | `![photo](assets/img.jpg)` |
+
+External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths are treated as vault connections. URL-encoded paths (e.g. `my%20note.md`) are decoded automatically.
+
+- Full index: ~10 seconds for ~1,000 files
+- Incremental: ~2 seconds (hash-based change detection)
+- Runs automatically via the daemon scheduler