@tekmidian/pai 0.65.0 → 0.65.2

package/docs/install-linux.md

@@ -0,0 +1,32 @@
+# Linux, from zero (Ubuntu)
+
+Both paths below were run end to end on a fresh Ubuntu 26.04 (arm64) install: setup, daemon, statusline in Claude Code, and a real `pai worker run`.
+
+Prerequisite: Claude Code installed.
+
+Common start:
+
+```bash
+sudo apt install -y nodejs npm tmux
+npm config set prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"   # global npm installs without sudo
+npm i -g @tekmidian/pai
+```
+
+**Keyword search only (SQLite, no Docker):**
+
+```bash
+pai setup --yes --storage sqlite
+```
+
+**Keyword and semantic search (PostgreSQL + pgvector in Docker):**
+
+```bash
+sudo apt install -y docker.io docker-compose-v2
+sudo usermod -aG docker "$USER"                  # then log out and in, or prefix the next command with: sg docker -c "…"
+export PAI_PG_SHARED_BUFFERS=256MB               # only on small machines; the default 1GB must fit in RAM
+pai setup --yes --storage postgres
+```
+
+Setup starts the `pai-pgvector` container itself (`pgvector/pgvector:pg17`, bound to 127.0.0.1:5432, data in `~/.pai/pgdata`). The daemon waits for the database, so the first start of the container can take its time.
+
+Either way, setup skips macOS-only steps, installs the daemon as a systemd user unit, and turns workers on with the built-in `anthropic` provider. Inside tmux, `pai worker run` opens its follow pane as a tmux split; elsewhere use `pai worker follow <id>`. Setup also enables systemd linger itself so the daemon survives logout, and prints the `sudo loginctl enable-linger` command if the system does not allow it. Where systemd is absent (containers), run the daemon with `pai daemon serve`.

package/docs/install.md

@@ -0,0 +1,56 @@
+# Install
+
+## Quick Start
+
+Tell Claude Code:
+
+> Clone https://github.com/mnott/PAI and set it up for me
+
+Or install with a single command:
+
+```bash
+npx @tekmidian/pai install
+```
+
+Or manually:
+
+### 1. Install
+
+```bash
+git clone https://github.com/mnott/PAI
+cd PAI
+bun install
+bun run build
+```
+
+### 2. Run the setup wizard
+
+```bash
+pai setup            # interactive
+pai setup --yes      # unattended: every prompt takes its default
+```
+
+The wizard walks you through: storage mode (SQLite or PostgreSQL), project directories, Obsidian vault path, MCP server registration, CLAUDE.md template, and daemon configuration. It's idempotent — safe to re-run anytime.
+
+On Linux, follow [Linux, from zero (Ubuntu)](install-linux.md): it covers the native Claude installer, both storage paths (SQLite, PostgreSQL + pgvector in Docker) and the systemd daemon.
+
+### 3. The daemon
+
+Setup installs and starts it. To manage it:
+
+```bash
+pai daemon status      # running? which storage?
+pai daemon restart
+pai daemon install     # re-create the launchd (macOS) or systemd (Linux) service
+```
+
+The daemon runs in the background via launchd (macOS) or a systemd user unit (Linux), indexing your sessions and serving the MCP tools. It starts automatically on login.
+
+### 4. Verify
+
+```bash
+pai daemon status    # should show "running"
+pai memory search "test"   # should return results after indexing
+```
+
+That's it. Claude Code now has persistent memory across all sessions.

package/docs/memory.md

@@ -0,0 +1,96 @@
+# Memory
+
+## Progressive Memory Loading
+
+PAI loads context in layers at session start rather than all at once. This keeps early-session latency low while giving Claude everything it needs to be useful immediately.
+
+### The Four Layers
+
+| Layer | What it loads | When |
+|-------|---------------|------|
+| **L0 — Identity** | Your identity file (`~/.pai/identity.txt`) — who you are, your working style, key preferences | Always, at every session start |
+| **L1 — Essential story** | Summaries from the most recent session notes — what you were doing, what decisions were made, where things stand | Always, at session start |
+| **L2 — Topic queries** | On-demand retrieval for the current topic — fetched when a specific question or task is identified | On demand, during the session |
+| **L3 — Deep search** | Full `memory_search` across all indexed content — for when L2 is not enough | On demand, when explicitly needed |
+
+L0 and L1 fire automatically via the `memory_wakeup` MCP tool, which is called by the `SessionStart` hook. L2 and L3 are invoked as needed — the model decides when to go deeper based on the question at hand.
+
+### Configuring Your Identity File
+
+Create `~/.pai/identity.txt` with a short description of yourself and your working style. Claude will see this at every session start. Example:
+
+```
+Principal engineer. Work across TypeScript, Dart, and shell scripting.
+Projects: PAI (AI infrastructure), RingsADay (Flutter app), Scribe (MCP server).
+Prefer concise explanations, hate unnecessary hedging.
+```
+
+## Advanced Memory Tools
+
+### Temporal Knowledge Graph
+
+Facts change over time. The `kg_triples` table stores knowledge as subject-predicate-object triples with `valid_from` and `valid_to` timestamps, so facts can expire and contradict each other rather than accumulating in an undated blob.
+
+Four MCP tools cover the full lifecycle:
+
+- `kg_add` — Add a fact with a start date (and optional end date)
+- `kg_query` — Query the graph, filtered to facts valid at a given point in time
+- `kg_invalidate` — Mark a fact as no longer true (sets `valid_to`)
+- `kg_contradictions` — Surface facts that directly contradict each other, using predicate inversion rules
+
+Example: "the user prefers PostgreSQL" added in March; "the user prefers SQLite" added in April with the March fact invalidated. `kg_query` in April sees only the current fact; `kg_query` for March sees the historical one.
+
+### Memory Taxonomy
+
+`memory_taxonomy` gives a shape-of-memory overview: projects, session counts, chunk counts, embedding coverage, and recent activity. Think of it as a dashboard for your knowledge base — useful both for the model (to understand what it knows) and for you (to audit what is indexed).
+
+### Cross-Project Tunnels
+
+`memory_tunnels` detects concepts that appear across multiple projects. It works by comparing FTS vocabulary in SQLite mode or `ts_stat` output in PostgreSQL mode. When a concept — a library name, a design pattern, a person's name — shows up in three separate projects, PAI surfaces that connection as a tunnel.
+
+This reveals unexpected intellectual bridges: the same concurrency pattern used in PAI's daemon showing up in your Flutter app's state management, or a vendor name appearing in both your notes and your job applications.
+
+## Memory Architecture
+
+PAI's memory system uses a three-tier hybrid store inspired by Cognee's approach to knowledge graphs and retrieval. Each tier has a distinct role, and they work together to answer queries that no single store could handle alone.
+
+### Three-Tier Hybrid Store
+
+| Tier | Backend | What it stores |
+|------|---------|----------------|
+| **Chunks + entities** | SQLite (simple mode) or PostgreSQL (full mode) | Text chunks with embeddings; named entity records with content-address hashes |
+| **Knowledge graph** | PostgreSQL (`kg_triples`) | Subject-predicate-object triples with `valid_from`/`valid_to` timestamps |
+| **Vector embeddings** | pgvector (full mode) | 768-dimensional Snowflake Arctic embeddings on chunks and vault notes |
+
+### Entity Deduplication via Content-Address Hashing
+
+Named entities (people, projects, libraries, concepts) extracted during indexing are stored in a `kg_entities` table and deduplicated using a content-address hash derived from the entity's canonical name. Two mentions of "PostgreSQL" in different session notes resolve to a single entity row — the hash acts as a stable identity, so the graph stays normalized even as new content is indexed.
+
+### Graph-Completion Search Pipeline
+
+Standard vector search finds semantically similar chunks. Graph-completion search goes further:
+
+1. **Vector seeds** — a semantic search returns the top-K most relevant chunks.
+2. **Graph traversal** — the entities mentioned in those chunks are looked up in `kg_triples`; their immediate neighbors are fetched (one hop).
+3. **Candidate expansion** — the neighbor entities' associated chunks are added to the result set.
+4. **Re-rank** — the expanded candidate set is re-scored by the cross-encoder, which reads each (query, result) pair together. Results are sorted by this final relevance score.
+
+This means a query about "the PAI daemon" can surface a session note that mentions the daemon only indirectly — because a connected entity (the Unix socket, the launchd service) appears in both the graph and the note.
+
+### Feedback Loop with Relevance Scoring
+
+Every search result that is subsequently retrieved via `memory_get` (i.e., actually read by the model) generates a positive feedback signal. These signals are stored and used to adjust future search weights using an exponential moving average (EMA):
+
+```
+new_weight = alpha * signal + (1 - alpha) * old_weight
+```
+
+The default alpha is 0.1, so recent positive signals gradually raise a chunk's effective score without overriding the semantic baseline. This creates a personalization loop: content you actually use rises in future rankings; content you skip does not.
+
+### Access Timestamp Tracking
+
+Every chunk row carries a `last_accessed_at` timestamp updated on each `memory_get` call. This supports recency boost (content accessed recently scores higher) and enables future eviction policies for very large knowledge bases.
+
+### Multi-Tenant Support
+
+PAI isolates memory by project. Every chunk, entity, and observation row carries a `project_id` foreign key. Searches default to the current project; the `all_projects: true` flag (or `--all` CLI option) lifts the filter. Knowledge-graph triples carry a `project_id` as well, so cross-project tunnels (`memory_tunnels`) are detected explicitly rather than accidentally.

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.