@tekmidian/pai 0.65.0 → 0.65.1

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.65.0",
+  "version": "0.65.1",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/plugins/productivity/skills/Tasks/SKILL.md

@@ -123,4 +123,4 @@ An explicit label that matches nothing does **not** fall through to the containe
 
 - `pai task done <id>` closes a task on the tracker. Dispatched tasks tell the receiving session to do this, so work is not dispatched twice.
 - The bus never reads the tracker back into PAI state. It is one-way: PAI and its sessions write, a routine reads.
-- Full architecture and the verified API constraints: `Notes/docs/task-bus.md`.
+- Full architecture and the verified API constraints: `docs/task-bus.md`.

package/src/hooks/ts/pre-tool-use/security-validator.test.ts

@@ -60,6 +60,29 @@ describe("security-validator", () => {
     expect(status).toBe(2);
   });
 
+  it.each([
+    "git push --force-with-lease origin main",
+    "git push --force-with-lease=main:abc123 origin main",
+    "git -C repo.git push --force-with-lease URL main refs/tags/v1",
+    "git push --force-with-lease --force-if-includes origin main",
+    "git push --follow-tags origin main",
+  ])("allows %s", (command) => {
+    const { status, stderr } = runHook(command);
+    expect(status).toBe(0);
+    expect(stderr).toBe("");
+  });
+
+  it.each([
+    "git push --force origin main",
+    "git push -f origin main",
+    "git push --force --force-with-lease origin main",
+    "git push --force-with-lease origin main --force",
+    "git push origin main -f",
+  ])("denies %s", (command) => {
+    const { status } = runHook(command);
+    expect(status).toBe(2);
+  });
+
   it("allows an ordinary command", () => {
     const { status, stderr } = runHook("ls -la");
     expect(status).toBe(0);

package/src/hooks/ts/pre-tool-use/security-validator.ts

@@ -65,7 +65,7 @@ const DANGEROUS_FILE_OPS_PATTERNS: RegExp[] = [
 
 // OPTIONAL: Operations that require confirmation instead of blocking
 const DANGEROUS_GIT_PATTERNS: RegExp[] = [
-  /\bgit\s+push\s+.*(-f\b|--force)/i,               // git push --force
+  /\bgit\b.*\spush\b.*(\s-f\b|\s--force(\s|$))/i,  // git push -f / --force; --force-with-lease and --follow-tags pass
   /\bgit\s+reset\s+--hard/i,                        // git reset --hard
   // Add your own git safety patterns here
 ];

package/src/hooks/ts/session-start/load-project-context.ts

@@ -266,7 +266,7 @@ async function main() {
   // in its own archived handovers as `claude --resume <uuid>`, so the instruction
   // we ship in every checkpoint could not work.
   //
-  // It also completes the incident of that morning: `pai Paperfull` failed to
+  // It also completes the incident of that morning: `pai Northwind` failed to
   // resume b3462801 because of a probe bug, started a fresh session instead, and
   // THIS hook then moved b3462801 — 867 KB of real work — out of reach. The
   // failed resume destroyed what it had failed to open.