@tekmidian/pai 0.11.0 → 0.12.0

package/docs/commands/zettel.md

@@ -0,0 +1,151 @@
+<!-- GENERATED by scripts/build-docs.mjs from the live Commander tree (src/cli/program.ts). Do not edit by hand. -->
+
+# pai zettel
+
+> Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest
+
+## Synopsis
+
+```
+pai zettel <subcommand> [options]
+```
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [`pai zettel explore <note>`](#pai-zettel-explore-note) | Follow link chains from a starting note |
+| [`pai zettel health`](#pai-zettel-health) | Vault structural health audit: dead links, orphans, connectivity |
+| [`pai zettel surprise <note>`](#pai-zettel-surprise-note) | Find semantically similar but graph-distant notes (surprising connections) |
+| [`pai zettel suggest <note>`](#pai-zettel-suggest-note) | Suggest new wikilink connections for a note |
+| [`pai zettel converse <question>`](#pai-zettel-converse-question) | Ask the vault a question and get a synthesis prompt with relevant notes |
+| [`pai zettel themes`](#pai-zettel-themes) | Detect emerging theme clusters in recently edited notes |
+
+### pai zettel explore <note>
+
+Follow link chains from a starting note
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<note>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--depth <n>` | Maximum traversal depth (1-10) | `3` |
+| `--direction <d>` | Link direction: forward \| backward \| both | `both` |
+| `--mode <m>` | Edge mode: sequential \| associative \| all | `all` |
+
+
+### pai zettel health
+
+Vault structural health audit: dead links, orphans, connectivity
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scope <s>` | Scope: full \| recent \| project | `full` |
+| `--project <path>` | Project path prefix (requires --scope project) |  |
+| `--days <n>` | Look-back window in days (requires --scope recent) | `30` |
+| `--include <types>` | Comma-separated subset: dead_links,orphans,disconnected,low_connectivity |  |
+
+
+### pai zettel surprise <note>
+
+Find semantically similar but graph-distant notes (surprising connections)
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<note>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
+| `--limit <n>` | Maximum results | `10` |
+| `--min-similarity <f>` | Minimum cosine similarity (0–1) | `0.3` |
+| `--min-distance <n>` | Minimum graph distance | `3` |
+
+
+### pai zettel suggest <note>
+
+Suggest new wikilink connections for a note
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<note>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
+| `--limit <n>` | Maximum suggestions | `5` |
+| `--no-exclude-linked` | Include notes already linked from this one |  |
+
+
+### pai zettel converse <question>
+
+Ask the vault a question and get a synthesis prompt with relevant notes
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<question>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
+| `--depth <n>` | Graph expansion depth around matched notes | `2` |
+| `--limit <n>` | Maximum relevant notes to include | `15` |
+
+
+### pai zettel themes
+
+Detect emerging theme clusters in recently edited notes
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--vault-project-id <n>` | Project ID for the vault in the federation DB |  |
+| `--days <n>` | Look-back window in days | `30` |
+| `--min-size <n>` | Minimum notes per cluster | `3` |
+| `--max-themes <n>` | Maximum themes to return | `10` |
+| `--threshold <f>` | Similarity threshold for clustering (0–1) | `0.65` |
+
+
+## Examples
+
+```bash
+# Explore the neighbourhood of a note
+pai zettel explore "token factory"
+
+# Surface an unexpected connection
+pai zettel surprise
+
+# Emergent themes across the vault
+pai zettel themes
+
+# Vault connectivity health (orphans, dead links)
+pai zettel health
+```
+
+## See also
+
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai topic`](topic.md) · [`pai update`](update.md)
+
+Run `pai help <area>` to read any of these in the terminal.
+

package/docs/mcp-skill-guide.md

@@ -0,0 +1,292 @@
+# MCP Skill Delivery Guide
+
+How to structure MCP server instructions, prompts, and resources for optimal context efficiency.
+
+## The Three-Tier Architecture
+
+MCP provides three mechanisms for delivering content to Claude. Each tier has a specific purpose. Mixing them up is the most common source of context bloat and skill drift.
+
+### Tier 1: instructions (Always Loaded)
+
+The `instructions` field is loaded into EVERY message's context for the lifetime of the MCP connection. Keep it thin.
+
+**What belongs here:**
+- Brief description of the MCP server (1-2 sentences)
+- Routing table: "When user says X, fetch prompt Y"
+- Core behavioral rules that apply to every interaction
+- Resource directory: "Fetch pai://name for full guide on X"
+
+**What does NOT belong here:**
+- Full skill descriptions and workflow steps
+- Reference documentation (aesthetic guides, API docs)
+- Examples and tutorials
+- Anything that changes rarely and is only needed sometimes
+
+**Target size:** Under 2KB. If it exceeds this, you are stuffing the wrong tier.
+
+### Tier 2: prompts (On-Demand Workflows)
+
+Prompts are fetched by Claude when a specific skill is triggered via `prompts/get`. The user does not see these directly — they are instructions for Claude.
+
+**What belongs here:**
+- Complete skill workflow instructions
+- USE WHEN trigger conditions
+- Step-by-step workflow routing tables
+- Platform-specific rules (LinkedIn vs X vs Bluesky)
+- Command tables and data source lists
+
+**Registration:**
+
+```typescript
+server.prompt(
+  "review",
+  "Weekly/daily/monthly review of work accomplished",
+  () => ({
+    messages: [{
+      role: "user" as const,
+      content: {
+        type: "text" as const,
+        text: reviewSkillContent,
+      },
+    }],
+  })
+);
+```
+
+**Naming convention:** lowercase-kebab. Examples: `review`, `share`, `vault-context`.
+
+### Tier 3: resources (Reference Documentation)
+
+Resources are reference documents that Claude reads when it needs detailed information. Unlike prompts, they are not workflow instructions — they are reference material fetched via `resources/read`.
+
+**What belongs here:**
+- Style guides (aesthetic, voice, prosody)
+- Constitutional documents (philosophy, architecture)
+- API reference documentation
+- Configuration schemas
+- Technical specifications
+
+**Registration:**
+
+```typescript
+server.resource(
+  "aesthetic",
+  "pai://aesthetic",
+  { mimeType: "text/markdown" },
+  async () => ({
+    contents: [{
+      uri: "pai://aesthetic",
+      mimeType: "text/markdown",
+      text: aestheticGuideContent,
+    }],
+  })
+);
+```
+
+**URI convention:** Use a consistent scheme like `pai://name` or `mcp://server-name/resource`.
+
+---
+
+## Decision Matrix
+
+| Content Type | Tier | Reasoning |
+|--------------|------|-----------|
+| "When user says X, fetch prompt Y" | instructions | Routes to the right skill |
+| Full skill workflow (20+ lines) | prompt | Only needed when skill triggers |
+| Aesthetic style guide | resource | Reference, not workflow |
+| Core operating rules (git, security, format) | instructions | Applies to every interaction |
+| Platform-specific post formatting | prompt | Part of share skill workflow |
+| Voice prosody guide | resource | Reference, rarely needed |
+| Session lifecycle commands | instructions | Always applicable |
+| API endpoint documentation | resource | Reference, read on demand |
+
+---
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Stuffing everything into instructions
+
+```typescript
+// WRONG — 20 full skill descriptions in instructions
+const PAI_INSTRUCTIONS = `
+## Review Skill
+USE WHEN user says 'review'...
+[200 lines of workflow details]
+
+## Journal Skill
+USE WHEN user says 'journal'...
+[150 lines of workflow details]
+
+[18 more skills...]
+`;
+```
+
+**Problem:** Consumes 8-15KB of context on every message. Most content is irrelevant 95% of the time.
+
+**Fix:** One-line routing table in instructions. Full content in prompts.
+
+### Anti-Pattern 2: File path references in instructions
+
+```
+// WRONG — hardcoded personal paths
+"Read ~/.claude/Skills/Share/SKILL.md for social media instructions"
+```
+
+**Problem:** Paths are personal, not portable. The file may not exist. Reading a file wastes a tool call.
+
+**Fix:** Embed content directly in prompts/resources. No file path reads needed.
+
+### Anti-Pattern 3: Personal data in instructions
+
+```
+// WRONG — personal identifiers in shipped code
+"You are assisting John Smith at Acme Corp. His timezone is PST..."
+```
+
+**Problem:** Instructions ship with the MCP server. If the server is open-source, personal data leaks.
+
+**Fix:** Use placeholders (`${USER_NAME}`) or omit personal data from instructions entirely.
+
+### Anti-Pattern 4: Duplicating content across tiers
+
+```
+// WRONG — routing table AND full skill in instructions
+instructions: `
+When user says 'share', use Share skill.
+
+Share skill rules:
+- LinkedIn: 1000-2000 chars, first-person builder voice...
+[100 more lines]
+`
+```
+
+**Fix:** Routing table in instructions, full skill in prompt. Never both.
+
+---
+
+## How to Add a New Skill
+
+1. Write the full skill content (workflow steps, trigger conditions, examples)
+2. Add a one-line entry to the routing table in instructions
+3. Register as a prompt with `server.prompt()`
+4. Test that the routing table correctly identifies trigger phrases
+
+```typescript
+// Step 2: Add to routing table in instructions
+`| When user says 'deploy' or 'push to production' | Fetch prompt: deploy |`
+
+// Step 3: Register the prompt
+server.prompt(
+  "deploy",
+  "Deploy to staging or production environments",
+  () => ({
+    messages: [{
+      role: "user" as const,
+      content: {
+        type: "text" as const,
+        text: deploySkillContent,  // Full workflow here
+      },
+    }],
+  })
+);
+```
+
+---
+
+## How to Add a New Resource
+
+1. Write the reference content (guide, spec, configuration schema)
+2. Add an entry to the resource directory in instructions
+3. Register with `server.resource()`
+
+```typescript
+// Step 2: Add to resource directory in instructions
+`| API reference | pai://api-reference |`
+
+// Step 3: Register the resource
+server.resource(
+  "api-reference",
+  "pai://api-reference",
+  { mimeType: "text/markdown" },
+  async () => ({
+    contents: [{
+      uri: "pai://api-reference",
+      mimeType: "text/markdown",
+      text: apiReferenceContent,
+    }],
+  })
+);
+```
+
+---
+
+## Testing Checklist
+
+Before shipping a refactored MCP server:
+
+- [ ] `instructions` field is under 2KB
+- [ ] `instructions` contains ONLY routing table + core rules
+- [ ] Each skill has a registered prompt (`server.prompt`)
+- [ ] Each reference doc has a registered resource (`server.resource`)
+- [ ] No full skill descriptions in `instructions`
+- [ ] No hardcoded personal paths in `instructions`
+- [ ] No personal data (names, emails, timezones) in `instructions`
+- [ ] Prompts are fetchable: `prompts/list` returns all expected prompts
+- [ ] Resources are readable: `resources/list` returns all expected resources
+- [ ] All tools are unchanged (only instructions/prompts/resources changed)
+- [ ] Build succeeds
+
+---
+
+## Context Size Impact Example
+
+PAI MCP before and after applying this guide:
+
+| Metric | Before | After |
+|--------|--------|-------|
+| `instructions` size | ~8KB (20 skills) | ~1.5KB (routing table) |
+| Context loaded per message | ~8KB | ~1.5KB |
+| Full skill content when triggered | ~8KB (all skills) | ~0.5KB (one skill) |
+| Context savings (typical session) | — | ~6.5KB per message |
+
+At 200 messages per session, that is 1.3MB of context saved — equivalent to several extra tool calls worth of working memory.
+
+---
+
+## Using `@modelcontextprotocol/sdk`
+
+The high-level `McpServer` class handles protocol details. Use it unless you need low-level control.
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = new McpServer(
+  { name: "my-server", version: "1.0.0" },
+  { instructions: thinRoutingTable }
+);
+
+// Register a prompt
+server.prompt("skill-name", "One-line description", () => ({
+  messages: [{ role: "user", content: { type: "text", text: fullContent } }],
+}));
+
+// Register a resource
+server.resource("doc-name", "scheme://uri", { mimeType: "text/markdown" }, async () => ({
+  contents: [{ uri: "scheme://uri", mimeType: "text/markdown", text: docContent }],
+}));
+
+// Register a tool (unchanged by refactor)
+server.tool("tool-name", "Tool description", { param: z.string() }, async (args) => ({
+  content: [{ type: "text", text: "result" }],
+}));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+---
+
+## Summary
+
+The three-tier rule in one sentence: put routing metadata in instructions, put workflow execution steps in prompts, and put reference documentation in resources. Everything else is implementation detail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",
@@ -23,7 +23,9 @@
     "tab-color-command.sh",
     "scripts/build-hooks.mjs",
     "scripts/build-skill-stubs.mjs",
+    "scripts/build-docs.mjs",
     "src/hooks",
+    "docs",
     "README.md",
     "LICENSE",
     "ARCHITECTURE.md",
@@ -54,7 +56,7 @@
     "pai-daemon-mcp": "dist/daemon-mcp/index.mjs"
   },
   "scripts": {
-    "build": "tsdown && node scripts/build-hooks.mjs --sync && node scripts/build-skill-stubs.mjs --sync",
+    "build": "tsdown && node scripts/build-hooks.mjs --sync && node scripts/build-skill-stubs.mjs --sync && node scripts/build-docs.mjs",
     "dev": "tsdown --watch",
     "test": "vitest",
     "lint": "tsc --noEmit",