portable-agent-layer 0.2.0 → 0.3.0

package/README.md

@@ -26,6 +26,116 @@ With PAL, you can:
 
 ---
 
+## Install
+
+### Prerequisites
+
+> **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
+
+- [Bun](https://bun.sh) >= 1.3.0
+- At least one of: [Claude Code](https://claude.ai/code) or [opencode](https://opencode.ai)
+
+### Package mode (recommended)
+
+```bash
+bun add -g portable-agent-layer
+pal cli init
+```
+
+### Repo mode (for development / contributors)
+
+```bash
+git clone https://github.com/kovrichard/portable-agent-layer.git
+cd portable-agent-layer
+bun install
+bun run install:all
+```
+
+In repo mode, add an alias to your shell profile:
+
+```bash
+alias pal="bun run ~/path/to/portable-agent-layer/src/cli/index.ts"
+```
+
+---
+
+## Quick start
+
+```bash
+pal cli init          # scaffold home, install hooks for all targets
+pal                   # start a Claude session (with session summary on exit)
+pal cli status        # check your setup
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pal` | Start a Claude session with session summary on exit |
+| `pal cli init` | Scaffold PAL home directory and install hooks |
+| `pal cli install` | Register hooks/skills for targets |
+| `pal cli uninstall` | Remove hooks/skills for targets |
+| `pal cli export` | Export user state (telos, memory) to a zip |
+| `pal cli import` | Import user state from a zip |
+| `pal cli status` | Show current PAL configuration |
+| `pal cli doctor` | Check prerequisites and system health |
+
+### Target flags
+
+`init`, `install`, and `uninstall` accept target flags:
+
+```bash
+pal cli install --claude      # Claude Code only
+pal cli install --opencode    # opencode only
+pal cli install               # both (default)
+```
+
+---
+
+## Environment variables
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Required for PAL's hook inference (sentiment analysis, session naming). Uses Haiku for low-cost background calls. |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `GEMINI_API_KEY` | For YouTube video analysis skill |
+| `PAL_HOME` | Override user state directory (default: `~/.pal` or repo root) |
+| `PAL_PKG` | Override package root |
+| `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |
+| `PAL_OPENCODE_DIR` | Override opencode config dir (default: `~/.config/opencode`) |
+| `PAL_AGENTS_DIR` | Override agents dir (default: `~/.agents`) |
+
+---
+
+## Skills
+
+PAL ships with built-in skills that extend your agent's capabilities:
+
+| Skill | Description |
+|-------|-------------|
+| `analyze-pdf` | Download and analyze PDF files |
+| `analyze-youtube` | Analyze YouTube videos using Gemini |
+| `council` | Multi-perspective parallel debate on decisions |
+| `create-skill` | Scaffold a new skill from a description |
+| `extract-entities` | Extract people and companies from content |
+| `extract-wisdom` | Extract structured insights from content |
+| `first-principles` | Break down problems to fundamentals |
+| `fyzz-chat-api` | Query Fyzz Chat conversations via API |
+| `reflect` | Diagnose why a PAL behavior didn't trigger |
+| `research` | Multi-agent parallel research |
+| `review` | Security-focused code review |
+| `summarize` | Structured summarization |
+
+---
+
 ## Core idea
 
 PAL stands for **Portable Agent Layer**.
@@ -78,3 +188,9 @@ PAL is for people who want:
 - to move between machines without rebuilding everything
 - a durable way to store and reuse context
 - an open foundation for portable agent workflows
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -9,7 +9,6 @@
   "files": [
     "src/",
     "assets/",
-    "bin/",
     "README.md",
     "LICENSE"
   ],

package/src/cli/index.ts

@@ -2,23 +2,168 @@
 /**
  * PAL CLI — Portable Agent Layer
  *
- * Usage: pal <command> [options]
+ * Usage:
+ *   pal [claude-args...]              Start a Claude session with session summary on exit
+ *   pal cli <command> [options]       Admin commands
  *
- * Commands:
- *   init                 Scaffold PAL home, install hooks for all targets
- *   install              Register hooks/skills for targets
- *   uninstall            Remove hooks/skills for targets
- *   export               Export user state (telos, memory) to a zip
- *   import               Import user state from a zip
- *   status               Show current PAL configuration
+ * Admin commands (pal cli ...):
+ *   init                              Scaffold PAL home, install hooks for all targets
+ *   install [--claude] [--opencode]   Register hooks/skills for targets
+ *   uninstall [--claude] [--opencode] Remove hooks/skills for targets
+ *   export [path] [--dry-run]         Export user state to zip
+ *   import [path] [--dry-run]         Import user state from zip
+ *   status                            Show current PAL configuration
+ *   doctor                            Check prerequisites and system health
  */
 
-import { existsSync, mkdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
 import { log } from "../targets/lib";
 
-const [command, ...args] = process.argv.slice(2);
+const allArgs = process.argv.slice(2);
+
+// ── Route: pal cli <command> or pal [claude-args] ──
+
+if (allArgs[0] === "cli") {
+  const [, command, ...args] = allArgs;
+  await runCli(command, args);
+} else if (allArgs[0] === "--help" || allArgs[0] === "-h" || allArgs[0] === "help") {
+  showHelp();
+} else {
+  await session(allArgs);
+}
+
+// ── Session: pal [args] ──
+
+interface ToolCheck {
+  name: string;
+  available: boolean;
+  version?: string;
+}
+
+function checkTool(cmd: string, versionArgs: string[] = ["--version"]): ToolCheck {
+  try {
+    const result = spawnSync(cmd, versionArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      timeout: 5000,
+    });
+    if (result.status === 0) {
+      const version = (result.stdout?.toString() || "").trim().split("\n")[0];
+      return { name: cmd, available: true, version };
+    }
+  } catch {
+    // not found
+  }
+  return { name: cmd, available: false };
+}
+
+function detectAgent(): string | null {
+  if (checkTool("claude").available) return "claude";
+  if (checkTool("opencode").available) return "opencode";
+  return null;
+}
+
+async function session(sessionArgs: string[]) {
+  const agent = detectAgent();
+  if (!agent) {
+    log.error("No supported agent found. Install Claude Code or opencode.");
+    process.exit(1);
+  }
+
+  const result = spawnSync(agent, sessionArgs, {
+    stdio: "inherit",
+    shell: true,
+  });
+
+  const exitCode = result.status ?? 1;
+
+  // Session summary (Claude only)
+  if (agent !== "claude") process.exit(exitCode);
+  try {
+    const projectsDir = resolve(homedir(), ".claude", "projects");
+    if (!existsSync(projectsDir)) process.exit(exitCode);
+
+    // Find most recently modified .jsonl file
+    let latestFile = "";
+    let latestMtime = 0;
+
+    for (const project of readdirSync(projectsDir, { withFileTypes: true })) {
+      if (!project.isDirectory()) continue;
+      const dir = resolve(projectsDir, project.name);
+      for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".jsonl")) continue;
+        const filepath = resolve(dir, file);
+        const { mtimeMs } = statSync(filepath);
+        if (mtimeMs > latestMtime) {
+          latestMtime = mtimeMs;
+          latestFile = filepath;
+        }
+      }
+    }
+
+    if (latestFile) {
+      const content = readFileSync(latestFile, "utf-8").trim();
+      const lastLine = content.split("\n").pop();
+      if (lastLine) {
+        const sessionId = JSON.parse(lastLine).sessionId;
+        if (sessionId) {
+          const summaryScript = resolve(palPkg(), "src", "tools", "session-summary.ts");
+          spawnSync("bun", ["run", summaryScript, "--", "--session", sessionId], {
+            stdio: "inherit",
+          });
+        }
+      }
+    }
+  } catch {
+    // Silently ignore summary errors
+  }
+
+  process.exit(exitCode);
+}
+
+// ── CLI dispatcher ──
+
+async function runCli(command: string | undefined, args: string[]) {
+  switch (command) {
+    case "init":
+      await init(args);
+      break;
+    case "install":
+      banner();
+      await install(resolveTargets(args));
+      break;
+    case "uninstall":
+      await uninstall(args);
+      break;
+    case "export":
+      await exportState(args);
+      break;
+    case "import":
+      await importState(args);
+      break;
+    case "status":
+      await status();
+      break;
+    case "doctor":
+      doctor();
+      break;
+    case "--help":
+    case "-h":
+    case "help":
+      showHelp();
+      break;
+    default:
+      if (command) log.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(command ? 1 : 0);
+  }
+}
+
+// ── Helpers ──
 
 function banner() {
   console.log("");
@@ -31,15 +176,19 @@ function banner() {
 
 function showHelp() {
   console.log(`
-  Usage: pal <command> [options]
-
-  Commands:
-    init [--claude] [--opencode] [--all]    Scaffold and install (default: all)
-    install [--claude] [--opencode] [--all]  Register hooks for targets
-    uninstall [--claude] [--opencode] [--all] Remove hooks for targets
-    export [path] [--dry-run]               Export state to zip
-    import [path] [--dry-run]               Import state from zip
-    status                                  Show PAL configuration
+  Usage:
+    pal [claude-args...]                    Start a Claude session
+    pal cli <command> [options]             Admin commands
+
+  Admin commands:
+    pal cli init [--claude] [--opencode]    Scaffold and install (default: all)
+    pal cli install [--claude] [--opencode] Register hooks for targets
+    pal cli uninstall [--claude] [--opencode] Remove hooks for targets
+    pal cli export [path] [--dry-run]       Export state to zip
+    pal cli import [path] [--dry-run]       Import state from zip
+    pal cli status                          Show PAL configuration
+    pal cli doctor                          Check prerequisites and health
+
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
     PAL_PKG               Override package root
@@ -53,8 +202,6 @@ function parseTargets(args: string[]): {
   claude: boolean;
   opencode: boolean;
 } {
-  if (args.length === 0) return { claude: true, opencode: true };
-
   let claude = false;
   let opencode = false;
   for (const arg of args) {
@@ -65,24 +212,125 @@ function parseTargets(args: string[]): {
       opencode = true;
     }
   }
-  // If no target flags, default to all
   if (!claude && !opencode) return { claude: true, opencode: true };
   return { claude, opencode };
 }
 
+/** Resolve targets against available agents. Errors if explicitly requested but missing. */
+function resolveTargets(
+  args: string[],
+  health?: DoctorResult
+): { claude: boolean; opencode: boolean } {
+  const requested = parseTargets(args);
+  const h = health || doctor(true);
+  const explicit = args.some(
+    (a) => a === "--claude" || a === "--opencode" || a === "--all"
+  );
+
+  if (explicit) {
+    // User explicitly requested — error if not available
+    if (requested.claude && !h.claude.available) {
+      log.error("Claude Code is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    if (requested.opencode && !h.opencode.available) {
+      log.error("opencode is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    return requested;
+  }
+
+  // Default (no flags) — install for available agents only
+  const targets = {
+    claude: h.claude.available,
+    opencode: h.opencode.available,
+  };
+
+  if (!targets.claude) log.info("Skipping Claude Code (not installed)");
+  if (!targets.opencode) log.info("Skipping opencode (not installed)");
+
+  return targets;
+}
+
+// ── Doctor ──
+
+interface DoctorResult {
+  bun: ToolCheck;
+  claude: ToolCheck;
+  opencode: ToolCheck;
+  hasAgent: boolean;
+}
+
+function doctor(silent = false): DoctorResult {
+  // Allow CI/tests to skip agent detection
+  if (process.env.PAL_SKIP_DOCTOR === "1") {
+    return {
+      bun: { name: "bun", available: true, version: Bun.version },
+      claude: { name: "claude", available: true },
+      opencode: { name: "opencode", available: true },
+      hasAgent: true,
+    };
+  }
+
+  const bun = { name: "bun", available: true, version: Bun.version };
+  const claude = checkTool("claude");
+  const opencode = checkTool("opencode");
+  const hasAgent = claude.available || opencode.available;
+
+  const home = palHome();
+  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
+  const telosCount = (() => {
+    try {
+      return readdirSync(resolve(home, "telos")).filter((f) => f.endsWith(".md")).length;
+    } catch {
+      return 0;
+    }
+  })();
+
+  if (!silent) {
+    const ok = (msg: string) => log.info(`  \u2713 ${msg}`);
+    const fail = (msg: string) => log.warn(`  \u2717 ${msg}`);
+
+    console.log("");
+    log.info("Doctor");
+    ok(`Bun ${bun.version}`);
+    claude.available
+      ? ok(`Claude Code ${claude.version || ""}`.trim())
+      : fail("Claude Code — not found");
+    opencode.available
+      ? ok(`opencode ${opencode.version || ""}`.trim())
+      : fail("opencode — not found");
+    ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
+    telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
+
+    if (!hasAgent) {
+      console.log("");
+      log.error("No supported agent found. Install Claude Code or opencode.");
+    }
+    console.log("");
+  }
+
+  return { bun, claude, opencode, hasAgent };
+}
+
 // ── Commands ──
 
-async function init() {
+async function init(args: string[]) {
   const { ensureSetupState, isSetupComplete } = await import("../hooks/lib/setup");
   const { scaffoldTelos } = await import("../targets/lib");
 
   banner();
 
+  // Run doctor first — abort if no agents available
+  const health = doctor(false);
+  if (!health.hasAgent) {
+    process.exit(1);
+  }
+
   const home = palHome();
   const isRepo = existsSync(resolve(palPkg(), ".palroot"));
 
   if (!isRepo) {
-    // Package mode — scaffold ~/.pal/
     log.info(`Creating PAL home at ${home}`);
     mkdirSync(resolve(home, "telos"), { recursive: true });
     mkdirSync(resolve(home, "memory"), { recursive: true });
@@ -91,7 +339,8 @@ async function init() {
   scaffoldTelos();
   ensureSetupState();
 
-  const targets = parseTargets(args);
+  // Auto-detect available targets
+  const targets = resolveTargets(args, health);
   await install(targets);
 
   console.log("");
@@ -101,16 +350,14 @@ async function init() {
   }
 }
 
-async function install(targets?: { claude: boolean; opencode: boolean }) {
-  const t = targets || parseTargets(args);
-
-  if (t.claude) {
+async function install(targets: { claude: boolean; opencode: boolean }) {
+  if (targets.claude) {
     console.log("━━━ Claude Code ━━━");
     await import("../targets/claude/install");
     console.log("");
   }
 
-  if (t.opencode) {
+  if (targets.opencode) {
     console.log("━━━ opencode ━━━");
     await import("../targets/opencode/install");
     console.log("");
@@ -119,7 +366,7 @@ async function install(targets?: { claude: boolean; opencode: boolean }) {
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
-async function uninstall() {
+async function uninstall(args: string[]) {
   const targets = parseTargets(args);
 
   if (targets.claude) {
@@ -139,13 +386,13 @@ async function uninstall() {
   );
 }
 
-async function exportState() {
+async function exportState(args: string[]) {
   const { collectExportFiles, exportZip, timestamp } = await import(
     "../hooks/lib/export"
   );
 
   const dryRun = args.includes("--dry-run");
-  const pathArg = args.find((a) => !a.startsWith("-") && a !== "export");
+  const pathArg = args.find((a) => !a.startsWith("-"));
   const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
 
   if (dryRun) {
@@ -166,14 +413,14 @@ async function exportState() {
   }
 }
 
-async function importState() {
-  const { readdirSync, statSync } = await import("node:fs");
+async function importState(args: string[]) {
+  const { statSync } = await import("node:fs");
   const { createInterface } = await import("node:readline");
   const AdmZip = (await import("adm-zip")).default;
 
   const home = palHome();
   const dryRun = args.includes("--dry-run");
-  const pathArg = args.find((a) => !a.startsWith("-") && a !== "import");
+  const pathArg = args.find((a) => !a.startsWith("-"));
 
   function findLatest(): string | null {
     const candidates: string[] = [];
@@ -214,7 +461,7 @@ async function importState() {
   } else {
     const latest = findLatest();
     if (!latest) {
-      log.error("No export or backup files found. Provide a path: pal import <path>");
+      log.error("No export or backup files found. Provide a path: pal cli import <path>");
       process.exit(1);
     }
     console.log(`Found: ${latest}`);
@@ -254,13 +501,11 @@ async function importState() {
   } else {
     zip.extractAllTo(home, true);
     console.log(`Imported ${entries.length} files → ${home}`);
-    log.info("Run 'pal install' to re-register hooks.");
+    log.info("Run 'pal cli install' to re-register hooks.");
   }
 }
 
 async function status() {
-  const { existsSync, readdirSync, readFileSync } = await import("node:fs");
-
   const home = palHome();
   const pkg = palPkg();
   const isRepo = existsSync(resolve(pkg, ".palroot"));
@@ -274,13 +519,11 @@ async function status() {
   log.info(`Home:     ${home}`);
   console.log("");
 
-  // Platform dirs
   log.info(`Claude:   ${platform.claudeDir()}`);
   log.info(`opencode: ${platform.opencodeDir()}`);
   log.info(`Agents:   ${platform.agentsDir()}`);
   console.log("");
 
-  // Counts
   const count = (dir: string, ext?: string) => {
     try {
       const files = readdirSync(dir);
@@ -298,7 +541,6 @@ async function status() {
   const agentsDir = resolve(platform.claudeDir(), "agents");
   log.info(`Agents:   ${count(agentsDir, ".md")} installed`);
 
-  // Check if hooks are registered
   const settingsPath = resolve(platform.claudeDir(), "settings.json");
   try {
     const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
@@ -309,36 +551,3 @@ async function status() {
   }
   console.log("");
 }
-
-// ── Dispatch ──
-
-switch (command) {
-  case "init":
-    await init();
-    break;
-  case "install":
-    banner();
-    await install();
-    break;
-  case "uninstall":
-    await uninstall();
-    break;
-  case "export":
-    await exportState();
-    break;
-  case "import":
-    await importState();
-    break;
-  case "status":
-    await status();
-    break;
-  case "--help":
-  case "-h":
-  case "help":
-    showHelp();
-    break;
-  default:
-    if (command) log.error(`Unknown command: ${command}`);
-    showHelp();
-    process.exit(command ? 1 : 0);
-}

package/src/hooks/StopOrchestrator.ts

@@ -6,6 +6,7 @@
  * Transcript is read from the file at transcript_path, NOT from stdin.
  */
 
+import { checkReadmeSync } from "./handlers/readme-sync";
 import { logError } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 import { runStopHandlers } from "./lib/stop";
@@ -17,6 +18,17 @@ interface StopHookInput {
   last_assistant_message?: string;
 }
 
+// Check README sync before anything else — may block the session
+try {
+  const decision = checkReadmeSync();
+  if (decision.decision === "block") {
+    console.log(JSON.stringify(decision));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:readme-sync", err);
+}
+
 const input = await readStdinJSON<StopHookInput>();
 if (!input?.transcript_path) {
   logError("StopOrchestrator", "No transcript_path in hook input");

package/src/hooks/handlers/readme-sync.ts

@@ -0,0 +1,61 @@
+/**
+ * Stop handler: check if README.md is out of sync with code.
+ *
+ * Runs git diff to see if documentable files changed in this session.
+ * If they did and README is stale, returns a block decision.
+ */
+
+import { execSync } from "node:child_process";
+import { logDebug } from "../lib/log";
+import { palPkg } from "../lib/paths";
+import { validateReadmeSync, WATCHED_PATHS } from "../lib/readme-sync";
+
+/** Check if any watched files have uncommitted changes. */
+function hasDocumentableChanges(): boolean {
+  try {
+    const diff = execSync("git diff --name-only HEAD", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const staged = execSync("git diff --name-only --cached", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const changed = `${diff}\n${staged}`.split("\n").filter((f) => f.length > 0);
+
+    return changed.some((file) =>
+      WATCHED_PATHS.some((watched) => file === watched || file.startsWith(`${watched}/`))
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ReadmeSyncDecision {
+  decision?: "block";
+  reason?: string;
+}
+
+/** Returns a block decision if README is stale, or empty object to allow stop. */
+export function checkReadmeSync(): ReadmeSyncDecision {
+  if (!hasDocumentableChanges()) {
+    logDebug("readme-sync", "No documentable changes detected");
+    return {};
+  }
+
+  logDebug("readme-sync", "Documentable files changed — validating README");
+  const result = validateReadmeSync();
+
+  if (!result.ok) {
+    logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
+    return {
+      decision: "block",
+      reason: `README.md is out of date. Please update it before finishing:\n${result.issues.map((i) => `- ${i}`).join("\n")}`,
+    };
+  }
+
+  logDebug("readme-sync", "README is in sync");
+  return {};
+}

package/src/hooks/lib/claude-md.ts

@@ -18,7 +18,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { loadTelos } from "./context";
-import { assets, palHome, paths, platform } from "./paths";
+import { assets, ensureDir, palHome, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
@@ -116,6 +116,7 @@ export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   ensureSymlink();
   if (!needsRebuild()) return false;
+  ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
   return true;
 }

package/src/hooks/lib/readme-sync.ts

@@ -0,0 +1,129 @@
+/**
+ * README sync validation — ensures README.md reflects current code surfaces.
+ *
+ * Checks CLI commands, environment variables, and skills against README content.
+ * Used by tests (CI/pre-commit) and the Stop hook (blocks session if stale).
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palPkg } from "./paths";
+
+export interface SyncResult {
+  ok: boolean;
+  issues: string[];
+}
+
+/** Files that, when changed, should trigger a README check. */
+export const WATCHED_PATHS = [
+  "src/cli/index.ts",
+  "src/hooks/lib/paths.ts",
+  "src/hooks/lib/inference.ts",
+  "src/tools/youtube-analyze.ts",
+  "assets/skills",
+  "assets/agents",
+];
+
+/** Extract CLI command names from the switch statement in index.ts */
+function extractCliCommands(): string[] {
+  const pkg = palPkg();
+  const cliPath = resolve(pkg, "src", "cli", "index.ts");
+  if (!existsSync(cliPath)) return [];
+
+  const content = readFileSync(cliPath, "utf-8");
+  const matches = content.matchAll(/case\s+"([^"]+)":/g);
+  const commands: string[] = [];
+
+  for (const match of matches) {
+    const cmd = match[1];
+    // Skip help aliases and internal routing
+    if (["--help", "-h", "help", "cli"].includes(cmd)) continue;
+    commands.push(cmd);
+  }
+
+  return [...new Set(commands)];
+}
+
+/** Extract PAL_* env var names from paths.ts + API keys from source */
+function extractEnvVars(): string[] {
+  const pkg = palPkg();
+  const vars: Set<string> = new Set();
+
+  // PAL_* from paths.ts
+  const pathsFile = resolve(pkg, "src", "hooks", "lib", "paths.ts");
+  if (existsSync(pathsFile)) {
+    const content = readFileSync(pathsFile, "utf-8");
+    for (const match of content.matchAll(/process\.env\.(PAL_\w+)/g)) {
+      vars.add(match[1]);
+    }
+  }
+
+  // ANTHROPIC_API_KEY from inference.ts
+  const inferenceFile = resolve(pkg, "src", "hooks", "lib", "inference.ts");
+  if (existsSync(inferenceFile)) {
+    const content = readFileSync(inferenceFile, "utf-8");
+    if (content.includes("ANTHROPIC_API_KEY")) {
+      vars.add("ANTHROPIC_API_KEY");
+    }
+  }
+
+  // GEMINI_API_KEY from youtube-analyze.ts
+  const youtubeFile = resolve(pkg, "src", "tools", "youtube-analyze.ts");
+  if (existsSync(youtubeFile)) {
+    const content = readFileSync(youtubeFile, "utf-8");
+    if (content.includes("GEMINI_API_KEY")) {
+      vars.add("GEMINI_API_KEY");
+    }
+  }
+
+  return [...vars];
+}
+
+/** Extract skill names from assets/skills/ */
+function extractSkillNames(): string[] {
+  const pkg = palPkg();
+  const skillsDir = resolve(pkg, "assets", "skills");
+  if (!existsSync(skillsDir)) return [];
+
+  return readdirSync(skillsDir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""));
+}
+
+/** Validate that README.md documents all code surfaces. */
+export function validateReadmeSync(): SyncResult {
+  const pkg = palPkg();
+  const readmePath = resolve(pkg, "README.md");
+
+  if (!existsSync(readmePath)) {
+    return { ok: false, issues: ["README.md not found"] };
+  }
+
+  const readme = readFileSync(readmePath, "utf-8");
+  const issues: string[] = [];
+
+  // Check CLI commands
+  for (const cmd of extractCliCommands()) {
+    if (!readme.includes(`pal cli ${cmd}`)) {
+      issues.push(`CLI command "${cmd}" exists in code but not documented in README`);
+    }
+  }
+
+  // Check environment variables
+  for (const envVar of extractEnvVars()) {
+    if (!readme.includes(envVar)) {
+      issues.push(
+        `Environment variable "${envVar}" used in code but not documented in README`
+      );
+    }
+  }
+
+  // Check skills — just verify the count is mentioned or each name appears
+  const skills = extractSkillNames();
+  const undocumentedSkills = skills.filter((name) => !readme.includes(name));
+  if (undocumentedSkills.length > 0) {
+    issues.push(`Skills not documented in README: ${undocumentedSkills.join(", ")}`);
+  }
+
+  return { ok: issues.length === 0, issues };
+}

package/src/targets/lib.ts

@@ -48,6 +48,7 @@ export function scaffoldTelos(): void {
   const templatesDir = assets.telosTemplates();
   const telosDir = resolve(palHome(), "telos");
   if (!existsSync(templatesDir)) return;
+  mkdirSync(telosDir, { recursive: true });
 
   for (const file of readdirSync(templatesDir).filter((f) => f.endsWith(".md"))) {
     const src = resolve(templatesDir, file);

package/bin/pal

@@ -1,24 +0,0 @@
-#!/usr/bin/env bash
-# Jarvis — Claude Code wrapper with session summary on exit.
-#
-# After Claude exits, finds the most recently modified transcript JSONL
-# in ~/.claude/projects/ and extracts the sessionId from its last line.
-
-PAL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-
-# Run Claude (blocking — keeps the interactive terminal)
-claude "$@"
-EXIT_CODE=$?
-
-# Find the most recently modified transcript and extract its session ID
-LATEST=$(find "$HOME/.claude/projects" -name '*.jsonl' -type f -print0 2>/dev/null \
-  | xargs -0 ls -t 2>/dev/null | head -1)
-
-if [ -n "$LATEST" ]; then
-  SESSION_ID=$(tail -1 "$LATEST" | python3 -c "import sys,json; print(json.loads(sys.stdin.readline()).get('sessionId',''))" 2>/dev/null)
-  if [ -n "$SESSION_ID" ]; then
-    bun run "$PAL_DIR/src/tools/session-summary.ts" -- --session "$SESSION_ID" 2>/dev/null
-  fi
-fi
-
-exit $EXIT_CODE

package/bin/pal.bat

@@ -1,8 +0,0 @@
-@echo off
-REM Jarvis — Claude Code wrapper with session summary on exit.
-REM
-REM Uses PowerShell to start Claude, capture its PID, read the session ID
-REM from %USERPROFILE%\.claude\sessions\<PID>.json, then show a cost
-REM summary after Claude exits.
-
-powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0pal.ps1" %*

package/bin/pal.ps1

@@ -1,30 +0,0 @@
-# Jarvis — Claude Code wrapper with session summary on exit.
-#
-# After Claude exits, finds the most recently modified transcript JSONL
-# in ~/.claude/projects/ and extracts the sessionId from its last line.
-
-$palDir = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path)
-
-# Run Claude (blocking — keeps the interactive terminal)
-& claude @args
-$exitCode = $LASTEXITCODE
-
-# Find the most recently modified transcript and extract its session ID
-$latest = Get-ChildItem "$env:USERPROFILE\.claude\projects\*\*.jsonl" -ErrorAction SilentlyContinue |
-    Sort-Object LastWriteTime -Descending |
-    Select-Object -First 1
-
-if ($latest) {
-    $lastLine = Get-Content $latest.FullName -Tail 1 -ErrorAction SilentlyContinue
-    if ($lastLine) {
-        try {
-            $sessionId = ($lastLine | ConvertFrom-Json).sessionId
-            if ($sessionId) {
-                $summaryScript = Join-Path $palDir "src" "tools" "session-summary.ts"
-                & bun run $summaryScript -- --session $sessionId 2>$null
-            }
-        } catch {}
-    }
-}
-
-exit $exitCode