@tekmidian/pai 0.2.1 → 0.3.0

package/dist/cli/index.mjs

@@ -1,22 +1,22 @@
 #!/usr/bin/env node
 import { n as openRegistry } from "../db-4lSqLFb8.mjs";
-import { a as slugify, i as parseSessionFilename, n as decodeEncodedDir, t as buildEncodedDirMap } from "../migrate-Bwj7qPaE.mjs";
-import { n as ensurePaiMarker, t as discoverPaiMarkers } from "../pai-marker-DX_mFLum.mjs";
-import { n as openFederation } from "../db-BcDxXVBu.mjs";
-import { a as indexProject, n as embedChunks, r as indexAll } from "../indexer-B20bPHL-.mjs";
-import "../embeddings-mfqv-jFu.mjs";
-import { n as populateSlugs, r as searchMemory } from "../search-PjftDxxs.mjs";
-import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "../detect-BHqYcjJ1.mjs";
-import { a as fmtDate, c as ok, d as scaffoldProjectDirs, f as shortenPath, g as warn, i as err, l as renderTable, m as slugify$1, n as dim, o as header, p as slugFromPath, r as encodeDir, s as now, t as bold, u as resolvePath } from "../utils-DEWdIFQ0.mjs";
-import { t as PaiClient } from "../ipc-client-DPy7s3iu.mjs";
-import { a as expandHome, n as CONFIG_FILE$2, o as loadConfig$1, t as CONFIG_DIR } from "../config-DBh1bYM2.mjs";
-import { t as createStorageBackend } from "../factory-BDAiKtYR.mjs";
-import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { _ as warn, a as fmtDate, c as ok, d as scaffoldProjectDirs, f as shortenPath, i as err, l as renderTable, m as slugify, n as dim, o as header, p as slugFromPath, r as encodeDir, s as now, t as bold, u as resolvePath } from "../utils-QSfKagcj.mjs";
+import { a as slugify$1, i as parseSessionFilename, n as decodeEncodedDir, t as buildEncodedDirMap } from "../migrate-jokLenje.mjs";
+import { n as ensurePaiMarker, t as discoverPaiMarkers } from "../pai-marker-CXQPX2P6.mjs";
+import { n as openFederation } from "../db-Dp8VXIMR.mjs";
+import { a as indexProject, n as embedChunks, r as indexAll } from "../indexer-CKQcgKsz.mjs";
+import "../embeddings-DGRAPAYb.mjs";
+import { n as populateSlugs, r as searchMemory } from "../search-GK0ibTJy.mjs";
+import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "../detect-D7gPV3fQ.mjs";
+import { t as PaiClient } from "../ipc-client-CLt2fNlC.mjs";
+import { a as expandHome, n as CONFIG_FILE$2, o as loadConfig$1, t as CONFIG_DIR } from "../config-DELNqq3Z.mjs";
+import { t as createStorageBackend } from "../factory-DZLvRf4m.mjs";
+import { appendFileSync, chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import chalk from "chalk";
 import { Command } from "commander";
 import { fileURLToPath } from "node:url";
-import chalk from "chalk";
 import { execSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
 
@@ -65,7 +65,7 @@ function cmdPromote(db, opts) {
 		process.exit(1);
 	}
 	const displayName = opts.name ?? deriveNameFromFilename(sessionPath);
-	const slug = slugify$1(displayName);
+	const slug = slugify(displayName);
 	if (!slug) {
 		console.error(err(`Could not derive a valid slug from name: "${displayName}"`));
 		process.exit(1);
@@ -417,7 +417,7 @@ function suggestMovedPath(project) {
 	];
 	for (const c of candidates) if (existsSync(c)) return c;
 }
-function cmdHealth(db, opts) {
+function cmdHealth$1(db, opts) {
 	const rows = db.prepare(`SELECT p.*,
          (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id) AS session_count
        FROM projects p
@@ -729,7 +729,7 @@ function registerProjectCommands(projectCmd, getDb) {
 		cmdDetect(getDb(), pathArg, opts);
 	});
 	projectCmd.command("health").description("Audit all registered projects: check which paths still exist, find moved/dead projects").option("--fix", "Auto-remediate where possible (update moved paths, archive dead zero-session projects)").option("--json", "Output raw JSON report").option("--status <category>", "Filter output to: active | stale | dead").action((opts) => {
-		cmdHealth(getDb(), opts);
+		cmdHealth$1(getDb(), opts);
 	});
 	projectCmd.command("consolidate <identifier>").description("Consolidate scattered ~/.claude/projects/.../Notes/ directories for a project into its canonical Notes/ location").option("--yes", "Perform consolidation without confirmation prompt").option("--dry-run", "Preview what would be moved without making changes").action((identifier, opts) => {
 		cmdConsolidate(getDb(), identifier, opts);
@@ -1723,11 +1723,96 @@ function cmdHandover(db, projectSlug, numberOrLatest) {
 	}
 	process.exit(0);
 }
+function cmdActive(db, opts) {
+	const minutes = parseInt(opts.minutes ?? "60", 10);
+	const cutoff = Date.now() - minutes * 60 * 1e3;
+	const claudeProjectsDir = join(homedir(), ".claude", "projects");
+	if (!existsSync(claudeProjectsDir)) {
+		console.log(err("Claude projects directory not found."));
+		return;
+	}
+	const active = [];
+	const entries = readdirSync(claudeProjectsDir);
+	for (const entry of entries) {
+		const projectDir = join(claudeProjectsDir, entry);
+		try {
+			if (!statSync(projectDir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		let latestJsonl = null;
+		let latestMtime = 0;
+		try {
+			for (const file of readdirSync(projectDir)) {
+				if (!file.endsWith(".jsonl")) continue;
+				const filePath = join(projectDir, file);
+				try {
+					const mtime = statSync(filePath).mtimeMs;
+					if (mtime > latestMtime) {
+						latestMtime = mtime;
+						latestJsonl = filePath;
+					}
+				} catch {
+					continue;
+				}
+			}
+		} catch {
+			continue;
+		}
+		if (!latestJsonl || latestMtime < cutoff) continue;
+		const project = db.prepare("SELECT slug, display_name, root_path FROM projects WHERE encoded_dir = ?").get(entry);
+		active.push({
+			slug: project?.slug ?? entry,
+			displayName: project?.display_name ?? project?.slug ?? entry,
+			rootPath: project?.root_path ?? "",
+			encodedDir: entry,
+			lastModified: new Date(latestMtime),
+			jsonlFile: latestJsonl
+		});
+	}
+	active.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+	const seen = /* @__PURE__ */ new Set();
+	const deduped = active.filter((a) => {
+		const key = a.slug.replace(/-\d+$/, "");
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+	if (opts.json) {
+		console.log(JSON.stringify(deduped.map((a) => ({
+			slug: a.slug,
+			display_name: a.displayName,
+			root_path: a.rootPath,
+			last_modified: a.lastModified.toISOString()
+		})), null, 2));
+		return;
+	}
+	if (deduped.length === 0) {
+		console.log(dim(`No active sessions in the last ${minutes} minutes.`));
+		return;
+	}
+	console.log(header(`Currently Active Sessions`) + dim(` (modified in last ${minutes}min)`));
+	console.log();
+	const rows = deduped.map((a) => {
+		const time = a.lastModified.toTimeString().slice(0, 5);
+		const dirName = a.rootPath ? a.rootPath.replace(homedir(), "~").split("/").pop() ?? a.slug : a.slug;
+		return [
+			chalk.cyan(dirName),
+			dim(a.slug),
+			chalk.green(time)
+		];
+	});
+	console.log(renderTable([
+		"Directory",
+		"Project",
+		"Last Active"
+	], rows));
+}
 async function cmdAutoRoute(opts) {
-	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-D7W6RE06.mjs");
+	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-JjW3f7pV.mjs");
 	const { openRegistry } = await import("../db-4lSqLFb8.mjs").then((n) => n.t);
-	const { createStorageBackend } = await import("../factory-BDAiKtYR.mjs").then((n) => n.n);
-	const { loadConfig } = await import("../config-DBh1bYM2.mjs").then((n) => n.r);
+	const { createStorageBackend } = await import("../factory-DZLvRf4m.mjs").then((n) => n.n);
+	const { loadConfig } = await import("../config-DELNqq3Z.mjs").then((n) => n.r);
 	const config = loadConfig();
 	const registryDb = openRegistry();
 	const federation = await createStorageBackend(config);
@@ -1784,6 +1869,9 @@ function registerSessionCommands(sessionCmd, getDb) {
 	sessionCmd.command("checkpoint <message>").description("Append a timestamped checkpoint to the active session note.\nDesigned for hooks (PostToolUse, UserPromptSubmit) — fast and silent.\nRate-limited: skips silently if last checkpoint was < --min-gap seconds ago.").option("--min-gap <seconds>", "Minimum seconds between checkpoints (default: 300 = 5 minutes)", "300").action((message, opts) => {
 		cmdCheckpoint(message, opts);
 	});
+	sessionCmd.command("active").description("Show currently active Claude Code sessions.\nDetects live sessions by checking which JSONL transcript files\nwere recently modified in ~/.claude/projects/.").option("--minutes <n>", "Consider sessions active if modified within N minutes (default: 60)", "60").option("--json", "Output raw JSON instead of formatted display").action((opts) => {
+		cmdActive(getDb(), opts);
+	});
 	sessionCmd.command("auto-route").description("Auto-detect which project this session belongs to.\nTries: (1) path match in registry, (2) Notes/PAI.md marker walk, (3) topic detection.\nDesigned for use in CLAUDE.md session-start hooks.").option("--cwd <path>", "Working directory to detect from (default: process.cwd())").option("--context <text>", "Conversation context for topic-based fallback routing").option("--json", "Output raw JSON instead of formatted display").action(async (opts) => {
 		await cmdAutoRoute(opts);
 	});
@@ -2252,8 +2340,8 @@ async function displayDryRun(plans) {
 async function countVectorDbPaths(oldPaths) {
 	if (oldPaths.length === 0) return 0;
 	try {
-		const { loadConfig } = await import("../config-DBh1bYM2.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-Ccvpc6fC.mjs");
+		const { loadConfig } = await import("../config-DELNqq3Z.mjs").then((n) => n.r);
+		const { PostgresBackend } = await import("../postgres-CRBe30Ag.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -2279,8 +2367,8 @@ async function countVectorDbPaths(oldPaths) {
 async function updateVectorDbPaths(moves) {
 	if (moves.length === 0) return 0;
 	try {
-		const { loadConfig } = await import("../config-DBh1bYM2.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-Ccvpc6fC.mjs");
+		const { loadConfig } = await import("../config-DELNqq3Z.mjs").then((n) => n.r);
+		const { PostgresBackend } = await import("../postgres-CRBe30Ag.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -2653,7 +2741,7 @@ function performScan(db) {
 			result.projectsScanned++;
 			continue;
 		}
-		const slug = slugify(basename(rootPath) || encodedDir);
+		const slug = slugify$1(basename(rootPath) || encodedDir);
 		const { id, isNew } = upsertProject(db, slug, rootPath, encodedDir);
 		result.projectsScanned++;
 		if (isNew) result.projectsNew++;
@@ -2711,7 +2799,7 @@ function performScan(db) {
 		});
 		for (const child of children) {
 			const childPath = join(scanDir, child);
-			const childSlug = slugify(child);
+			const childSlug = slugify$1(child);
 			const childEncoded = encodeDir(childPath);
 			const existing = db.prepare("SELECT id FROM projects WHERE root_path = ?").get(childPath);
 			if (existing) {
@@ -2823,7 +2911,7 @@ function cmdMigrate$1(db) {
 		}
 		const rootPath = entry.original_path;
 		const encodedDir = entry.encoded_dir;
-		const slug = slugify(rootPath);
+		const slug = slugify$1(rootPath);
 		try {
 			const { isNew, id } = upsertProject(db, slug, rootPath, encodedDir);
 			if (isNew) projectsNew++;
@@ -3058,7 +3146,7 @@ function registerMemoryCommands(memoryCmd, getDb) {
 		else if (mode === "semantic" || mode === "hybrid") {
 			const backend = await createStorageBackend(loadConfig$1());
 			try {
-				const { generateEmbedding } = await import("../embeddings-mfqv-jFu.mjs").then((n) => n.i);
+				const { generateEmbedding } = await import("../embeddings-DGRAPAYb.mjs").then((n) => n.i);
 				console.log(dim("Generating query embedding..."));
 				const queryEmbedding = await generateEmbedding(query, true);
 				if (mode === "semantic") results = await backend.searchSemantic(queryEmbedding, searchOpts);
@@ -3552,8 +3640,8 @@ function cmdLogs(opts) {
 }
 function registerDaemonCommands(daemonCmd) {
 	daemonCmd.command("serve").description("Start the PAI daemon in the foreground").action(async () => {
-		const { serve } = await import("../daemon-v5O897D4.mjs").then((n) => n.t);
-		const { loadConfig: lc, ensureConfigDir } = await import("../config-DBh1bYM2.mjs").then((n) => n.r);
+		const { serve } = await import("../daemon-CeTX4NpF.mjs").then((n) => n.t);
+		const { loadConfig: lc, ensureConfigDir } = await import("../config-DELNqq3Z.mjs").then((n) => n.r);
 		ensureConfigDir();
 		await serve(lc());
 	});
@@ -3917,6 +4005,125 @@ function registerRestoreCommands(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/settings-manager.ts
+/**
+* settings-manager — merge-not-overwrite utility for ~/.claude/settings.json
+*
+* Provides safe, idempotent writes to Claude Code's settings.json:
+*   - env vars: added only if the key is absent (never overwrites)
+*   - hooks: appended per hookType, deduplicated by command string
+*   - statusLine: written only if the key is not already present
+*/
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
+function readSettingsJson() {
+	if (!existsSync(SETTINGS_FILE)) return {};
+	try {
+		return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+function writeSettingsJson(data) {
+	if (!existsSync(CLAUDE_DIR)) mkdirSync(CLAUDE_DIR, { recursive: true });
+	writeFileSync(SETTINGS_FILE, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+/**
+* Merge env vars — add keys that are absent, never overwrite existing ones.
+*/
+function mergeEnv(settings, incoming, report) {
+	let changed = false;
+	const existing = typeof settings["env"] === "object" && settings["env"] !== null ? settings["env"] : {};
+	for (const [key, value] of Object.entries(incoming)) if (Object.prototype.hasOwnProperty.call(existing, key)) report.push(chalk.dim(`  Skipped: env.${key} already set`));
+	else {
+		existing[key] = value;
+		report.push(chalk.green(`  Added env: ${key}`));
+		changed = true;
+	}
+	settings["env"] = existing;
+	return changed;
+}
+/**
+* Collect every command string already registered for a given hookType.
+* Stores both the full command and the basename for flexible matching
+* (handles ${PAI_DIR}/Hooks/foo.sh vs /Users/.../Hooks/foo.sh).
+*/
+function existingCommandsForHookType(rules) {
+	const cmds = /* @__PURE__ */ new Set();
+	for (const rule of rules) for (const entry of rule.hooks) {
+		cmds.add(entry.command);
+		const base = entry.command.split("/").pop();
+		if (base) cmds.add(base);
+	}
+	return cmds;
+}
+/**
+* Merge hooks — append entries, deduplicating by command string.
+*/
+function mergeHooks(settings, incoming, report) {
+	let changed = false;
+	const hooksSection = typeof settings["hooks"] === "object" && settings["hooks"] !== null ? settings["hooks"] : {};
+	for (const entry of incoming) {
+		const { hookType, matcher, command } = entry;
+		const existingRules = Array.isArray(hooksSection[hookType]) ? hooksSection[hookType] : [];
+		const existingCmds = existingCommandsForHookType(existingRules);
+		const basename = command.split("/").pop() ?? command;
+		if (existingCmds.has(command) || existingCmds.has(basename)) {
+			report.push(chalk.dim(`  Skipped: hook ${hookType} → ${basename} already registered`));
+			continue;
+		}
+		const newRule = { hooks: [{
+			type: "command",
+			command
+		}] };
+		if (matcher !== void 0) newRule.matcher = matcher;
+		existingRules.push(newRule);
+		hooksSection[hookType] = existingRules;
+		report.push(chalk.green(`  Added hook: ${hookType} → ${basename}`));
+		changed = true;
+	}
+	settings["hooks"] = hooksSection;
+	return changed;
+}
+/**
+* Merge statusLine — write only if the key is not already present.
+*/
+function mergeStatusLine(settings, incoming, report) {
+	if (Object.prototype.hasOwnProperty.call(settings, "statusLine")) {
+		report.push(chalk.dim("  Skipped: statusLine already configured"));
+		return false;
+	}
+	settings["statusLine"] = { ...incoming };
+	report.push(chalk.green("  Added statusLine"));
+	return true;
+}
+/**
+* Merge env vars, hooks, and/or a statusLine entry into ~/.claude/settings.json.
+* Never overwrites existing values — only adds what is missing.
+*
+* Returns { changed, report } where report contains human-readable lines.
+*/
+function mergeSettings(opts) {
+	const settings = readSettingsJson();
+	const report = [];
+	let changed = false;
+	if (opts.env !== void 0 && Object.keys(opts.env).length > 0) {
+		if (mergeEnv(settings, opts.env, report)) changed = true;
+	}
+	if (opts.hooks !== void 0 && opts.hooks.length > 0) {
+		if (mergeHooks(settings, opts.hooks, report)) changed = true;
+	}
+	if (opts.statusLine !== void 0) {
+		if (mergeStatusLine(settings, opts.statusLine, report)) changed = true;
+	}
+	if (changed) writeSettingsJson(settings);
+	return {
+		changed,
+		report
+	};
+}
+
 //#endregion
 //#region src/cli/commands/setup.ts
 const c = {
@@ -4038,6 +4245,24 @@ function getTemplatesDir$1() {
 	for (const c of candidates) if (existsSync(join(c, "claude-md.template.md"))) return c;
 	return join(process.cwd(), "templates");
 }
+function getHooksDir() {
+	const candidates = [
+		join(process.cwd(), "src", "hooks"),
+		join(homedir(), "dev", "ai", "PAI", "src", "hooks"),
+		join("/", "usr", "local", "lib", "node_modules", "@tekmidian", "pai", "src", "hooks")
+	];
+	for (const c of candidates) if (existsSync(join(c, "session-stop.sh"))) return c;
+	return join(process.cwd(), "src", "hooks");
+}
+function getStatuslineScript() {
+	const candidates = [
+		join(process.cwd(), "statusline-command.sh"),
+		join(homedir(), "dev", "ai", "PAI", "statusline-command.sh"),
+		join("/", "usr", "local", "lib", "node_modules", "@tekmidian", "pai", "statusline-command.sh")
+	];
+	for (const c of candidates) if (existsSync(c)) return c;
+	return null;
+}
 async function startDocker(rl) {
 	const dockerDir = getDockerDir();
 	if (!existsSync(join(dockerDir, "docker-compose.yml"))) {
@@ -4069,8 +4294,8 @@ async function startDocker(rl) {
 }
 async function testPostgresConnection(connectionString) {
 	try {
-		const { default: pg } = await import("pg");
-		const client = new pg.Client({ connectionString });
+		const pgModule = await import("pg");
+		const client = new (pgModule.default ?? pgModule).Client({ connectionString });
 		await client.connect();
 		await client.end();
 		return true;
@@ -4099,6 +4324,35 @@ function stepWelcome() {
 */
 async function stepStorage(rl) {
 	section("Step 2: Storage Backend");
+	const existing = readConfigRaw();
+	if (existing.storageBackend) {
+		const backend = String(existing.storageBackend);
+		if (backend === "postgres") {
+			try {
+				const status = spawnSync("docker", [
+					"ps",
+					"--filter",
+					"name=pai-pgvector",
+					"--format",
+					"{{.Status}}"
+				], { stdio: "pipe" }).stdout?.toString().trim();
+				if (status && status.includes("Up")) {
+					console.log(c.ok(`Storage backend: PostgreSQL (container running). Skipping.`));
+					return existing;
+				}
+				console.log(c.dim("  PostgreSQL container found but not running. Starting..."));
+				await startDocker(rl);
+				await new Promise((r) => setTimeout(r, 3e3));
+				console.log(c.ok("PostgreSQL container started."));
+			} catch {
+				console.log(c.ok(`Storage backend: PostgreSQL (configured). Skipping.`));
+			}
+			return existing;
+		} else {
+			console.log(c.ok(`Storage backend: ${backend}. Skipping.`));
+			return existing;
+		}
+	}
 	line$1();
 	line$1("  Choose how PAI stores your indexed knowledge:");
 	line$1();
@@ -4176,6 +4430,11 @@ async function stepStorage(rl) {
 */
 async function stepEmbedding(rl) {
 	section("Step 3: Embedding Model");
+	const existing = readConfigRaw();
+	if (existing.embeddingModel) {
+		console.log(c.ok(`Embedding model: ${existing.embeddingModel}. Skipping.`));
+		return { embeddingModel: existing.embeddingModel };
+	}
 	line$1();
 	line$1("  An embedding model converts your text into vectors for semantic search.");
 	line$1("  Models are downloaded from HuggingFace on first use.");
@@ -4278,10 +4537,192 @@ async function stepClaudeMd(rl) {
 	return true;
 }
 /**
-* Step 5: Directory scanning configuration
+* Step 5: PAI skill installation (~/.claude/skills/PAI/SKILL.md)
+*/
+async function stepPaiSkill(rl) {
+	section("Step 5: PAI Skill Installation");
+	line$1();
+	line$1("  PAI ships a SKILL.md that tells Claude Code how to invoke PAI commands.");
+	line$1();
+	const templatePath = join(getTemplatesDir$1(), "pai-skill.template.md");
+	if (!existsSync(templatePath)) {
+		console.log(c.warn("Skill template not found: " + templatePath));
+		console.log(c.dim("  Skipping PAI skill installation."));
+		return false;
+	}
+	const skillDir = join(homedir(), ".claude", "skills", "PAI");
+	const skillFile = join(skillDir, "SKILL.md");
+	if (existsSync(skillFile)) {
+		const content = readFileSync(skillFile, "utf-8");
+		const isGenerated = content.includes("Generated by PAI Setup");
+		if (isGenerated) console.log(c.dim("  Found existing PAI-generated SKILL.md."));
+		else {
+			console.log(c.yellow("  Found existing SKILL.md (not PAI-generated)."));
+			console.log(c.dim("  A backup will be created before overwriting."));
+		}
+		line$1();
+		if (!await promptYesNo(rl, "Update ~/.claude/skills/PAI/SKILL.md with the latest PAI skill?", isGenerated)) {
+			console.log(c.dim("  Keeping existing SKILL.md unchanged."));
+			return false;
+		}
+		if (!isGenerated) {
+			const backupPath = skillFile + ".backup";
+			writeFileSync(backupPath, content, "utf-8");
+			console.log(c.ok(`Backed up existing SKILL.md to ${backupPath}`));
+		}
+	} else if (!await promptYesNo(rl, "Install PAI skill to ~/.claude/skills/PAI/SKILL.md?", true)) {
+		console.log(c.dim("  Skipping PAI skill installation."));
+		return false;
+	}
+	let template = readFileSync(templatePath, "utf-8");
+	template = template.replace(/\$\{HOME\}/g, homedir());
+	if (!existsSync(skillDir)) mkdirSync(skillDir, { recursive: true });
+	writeFileSync(skillFile, template, "utf-8");
+	line$1();
+	console.log(c.ok("Installed ~/.claude/skills/PAI/SKILL.md"));
+	return true;
+}
+/**
+* Step 6: Hook scripts (pre-compact, session-stop, statusline)
+*/
+async function stepHooks(rl) {
+	section("Step 6: Lifecycle Hooks");
+	line$1();
+	line$1("  PAI hooks fire on session stop and context compaction to save state,");
+	line$1("  update notes, and display live statusline information.");
+	line$1();
+	if (!await promptYesNo(rl, "Install PAI lifecycle hooks (session stop, pre-compact, statusline)?", true)) {
+		console.log(c.dim("  Skipping hook installation."));
+		return false;
+	}
+	const hooksDir = getHooksDir();
+	const statuslineSrc = getStatuslineScript();
+	const claudeDir = join(homedir(), ".claude");
+	const hooksTarget = join(claudeDir, "Hooks");
+	if (!existsSync(hooksTarget)) mkdirSync(hooksTarget, { recursive: true });
+	let anyInstalled = false;
+	function installFile(src, dest, label) {
+		if (!existsSync(src)) {
+			console.log(c.warn(`  Source not found: ${src}`));
+			return;
+		}
+		const srcContent = readFileSync(src, "utf-8");
+		if (existsSync(dest)) {
+			if (srcContent === readFileSync(dest, "utf-8")) {
+				console.log(c.dim(`  Unchanged: ${label}`));
+				return;
+			}
+		}
+		copyFileSync(src, dest);
+		chmodSync(dest, 493);
+		console.log(c.ok(`Installed: ${label}`));
+		anyInstalled = true;
+	}
+	line$1();
+	installFile(join(hooksDir, "pre-compact.sh"), join(hooksTarget, "pai-pre-compact.sh"), "pai-pre-compact.sh");
+	installFile(join(hooksDir, "session-stop.sh"), join(hooksTarget, "pai-session-stop.sh"), "pai-session-stop.sh");
+	if (statuslineSrc) installFile(statuslineSrc, join(claudeDir, "statusline-command.sh"), "statusline-command.sh");
+	else console.log(c.warn("  statusline-command.sh not found — skipping statusline."));
+	return anyInstalled;
+}
+/**
+* Step 7: Patch ~/.claude/settings.json with PAI hooks, env vars, and statusline
+*/
+async function stepSettings(rl) {
+	section("Step 7: Settings Patch");
+	line$1();
+	line$1("  PAI will add env vars, hook registrations, and the statusline command");
+	line$1("  to ~/.claude/settings.json. Existing values are never overwritten.");
+	line$1();
+	if (!await promptYesNo(rl, "Patch ~/.claude/settings.json with PAI hooks, env vars, and statusline?", true)) {
+		console.log(c.dim("  Skipping settings patch."));
+		return false;
+	}
+	const result = mergeSettings({
+		env: {
+			PAI_DIR: join(homedir(), ".claude"),
+			CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "80"
+		},
+		hooks: [{
+			hookType: "PreCompact",
+			matcher: "",
+			command: "${PAI_DIR}/Hooks/pai-pre-compact.sh"
+		}, {
+			hookType: "Stop",
+			command: "${PAI_DIR}/Hooks/pai-session-stop.sh"
+		}],
+		statusLine: {
+			type: "command",
+			command: "bash ${PAI_DIR}/statusline-command.sh"
+		}
+	});
+	line$1();
+	for (const r of result.report) console.log(r);
+	if (!result.changed) console.log(c.dim("  Settings already up-to-date. No changes made."));
+	return result.changed;
+}
+/**
+* Step 8: Daemon install (launchd plist)
+*/
+async function stepDaemon(rl) {
+	section("Step 8: Daemon Install");
+	line$1();
+	line$1("  The PAI daemon indexes your projects every 5 minutes in the background.");
+	line$1();
+	if (existsSync(join(homedir(), "Library", "LaunchAgents", "com.pai.pai-daemon.plist"))) {
+		console.log(c.dim("  PAI daemon plist already installed."));
+		line$1();
+		if (!await promptYesNo(rl, "Reinstall the PAI daemon launchd plist?", false)) {
+			console.log(c.dim("  Keeping existing daemon installation."));
+			return false;
+		}
+	} else if (!await promptYesNo(rl, "Install the PAI daemon to run automatically at login?", true)) {
+		console.log(c.dim("  Skipping daemon install. Run manually: pai daemon install"));
+		return false;
+	}
+	line$1();
+	if (spawnSync("pai", ["daemon", "install"], { stdio: "inherit" }).status !== 0) {
+		console.log(c.warn("  Daemon install failed. Run manually: pai daemon install"));
+		return false;
+	}
+	console.log(c.ok("Daemon installed as com.pai.pai-daemon."));
+	return true;
+}
+/**
+* Step 9: MCP registration in ~/.claude.json
+*/
+async function stepMcp(rl) {
+	section("Step 9: MCP Registration");
+	line$1();
+	line$1("  Registering the PAI MCP server lets Claude Code call PAI tools directly.");
+	line$1();
+	const claudeJsonPath = join(homedir(), ".claude.json");
+	if (existsSync(claudeJsonPath)) try {
+		const raw = readFileSync(claudeJsonPath, "utf-8");
+		const mcpServers = JSON.parse(raw)["mcpServers"];
+		if (mcpServers && Object.prototype.hasOwnProperty.call(mcpServers, "pai")) {
+			console.log(c.ok("PAI MCP server already registered in ~/.claude.json."));
+			console.log(c.dim("  Skipping MCP registration."));
+			return false;
+		}
+	} catch {}
+	if (!await promptYesNo(rl, "Register the PAI MCP server in ~/.claude.json?", true)) {
+		console.log(c.dim("  Skipping MCP registration. Run manually: pai mcp install"));
+		return false;
+	}
+	line$1();
+	if (spawnSync("pai", ["mcp", "install"], { stdio: "inherit" }).status !== 0) {
+		console.log(c.warn("  MCP registration failed. Run manually: pai mcp install"));
+		return false;
+	}
+	console.log(c.ok("PAI MCP server registered in ~/.claude.json."));
+	return true;
+}
+/**
+* Step 10: Directory scanning configuration
 */
 async function stepDirectories(rl) {
-	section("Step 5: Directories to Index");
+	section("Step 10: Directories to Index");
 	line$1();
 	line$1("  PAI indexes files in your registered projects. You can register projects");
 	line$1("  individually with `pai project add <path>`, or let the registry scanner");
@@ -4308,10 +4749,10 @@ async function stepDirectories(rl) {
 	stepDirectories._runScan = runScan;
 }
 /**
-* Step 6: Initial index
+* Step 11: Initial index
 */
 async function stepInitialIndex(rl) {
-	section("Step 6: Initial Index");
+	section("Step 11: Initial Index");
 	line$1();
 	line$1("  Indexing scans your registered projects and builds the search index.");
 	line$1("  The daemon runs indexing automatically every 5 minutes once started.");
@@ -4353,9 +4794,9 @@ async function stepInitialIndex(rl) {
 	}
 }
 /**
-* Step 7: Summary and next steps
+* Step 12: Summary and next steps
 */
-function stepSummary(configUpdates, claudeMdGenerated) {
+function stepSummary(configUpdates, claudeMdGenerated, paiSkillInstalled, hooksInstalled, settingsPatched, daemonInstalled, mcpRegistered) {
 	section("Setup Complete");
 	line$1();
 	console.log(c.ok("PAI Knowledge OS is configured!"));
@@ -4366,7 +4807,14 @@ function stepSummary(configUpdates, claudeMdGenerated) {
 	line$1();
 	console.log(chalk.dim("  Storage backend:  ") + chalk.cyan(backend ?? "sqlite"));
 	console.log(chalk.dim("  Embedding model:  ") + chalk.cyan(model && model !== "none" ? model : "(none — keyword search only)"));
-	console.log(chalk.dim("  Agent config:     ") + chalk.cyan(claudeMdGenerated ? "~/.claude/CLAUDE.md (generated)" : "(unchanged)"));
+	console.log(chalk.dim("  CLAUDE.md:        ") + chalk.cyan(claudeMdGenerated ? "~/.claude/CLAUDE.md (generated)" : "(unchanged)"));
+	console.log(chalk.dim("  PAI skill:        ") + chalk.cyan(paiSkillInstalled ? "~/.claude/skills/PAI/SKILL.md (installed)" : "(unchanged)"));
+	console.log(chalk.dim("  Hooks:            ") + chalk.cyan(hooksInstalled ? "pai-pre-compact.sh, pai-session-stop.sh (installed)" : "(unchanged)"));
+	console.log(chalk.dim("  Settings:         ") + chalk.cyan(settingsPatched ? "env vars, hooks, statusline (patched)" : "(unchanged)"));
+	console.log(chalk.dim("  Daemon:           ") + chalk.cyan(daemonInstalled ? "com.pai.pai-daemon (installed)" : "(unchanged)"));
+	console.log(chalk.dim("  MCP:              ") + chalk.cyan(mcpRegistered ? "registered in ~/.claude.json" : "(unchanged)"));
+	line$1();
+	console.log(chalk.bold.yellow("  → RESTART Claude Code to activate all changes."));
 	line$1();
 	line$1(chalk.bold("  Next steps:"));
 	line$1();
@@ -4414,10 +4862,14 @@ async function runSetup() {
 		stepWelcome();
 		line$1();
 		await prompt(rl, chalk.dim("  Press Enter to begin setup..."));
-		section("Step 2: Storage Backend");
 		const storageConfig = await stepStorage(rl);
 		const embeddingConfig = await stepEmbedding(rl);
 		const claudeMdGenerated = await stepClaudeMd(rl);
+		const paiSkillInstalled = await stepPaiSkill(rl);
+		const hooksInstalled = await stepHooks(rl);
+		const settingsPatched = await stepSettings(rl);
+		const daemonInstalled = await stepDaemon(rl);
+		const mcpRegistered = await stepMcp(rl);
 		await stepDirectories(rl);
 		const allUpdates = {
 			...storageConfig,
@@ -4427,7 +4879,7 @@ async function runSetup() {
 		line$1();
 		console.log(c.ok("Configuration saved."));
 		await stepInitialIndex(rl);
-		stepSummary(allUpdates, claudeMdGenerated);
+		stepSummary(allUpdates, claudeMdGenerated, paiSkillInstalled, hooksInstalled, settingsPatched, daemonInstalled, mcpRegistered);
 	} finally {
 		rl.close();
 	}
@@ -5296,6 +5748,348 @@ function registerObsidianCommands(obsidianCmd, getDb) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/zettel.ts
+let _fedDb = null;
+function getFedDb() {
+	if (!_fedDb) try {
+		_fedDb = openFederation();
+	} catch (e) {
+		console.error(err(`Failed to open PAI federation DB: ${e}`));
+		process.exit(1);
+	}
+	return _fedDb;
+}
+/** Shorten a vault path to just the last 2-3 components for display. */
+function shortPath(p, parts = 3) {
+	return p.split("/").filter(Boolean).slice(-parts).join("/");
+}
+async function cmdExplore(note, opts) {
+	const depth = parseInt(opts.depth ?? "3", 10);
+	const direction = opts.direction ?? "both";
+	const mode = opts.mode ?? "all";
+	const { zettelExplore } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const result = zettelExplore(getFedDb(), {
+		startNote: note,
+		depth,
+		direction,
+		mode
+	});
+	console.log();
+	console.log(header("  PAI Zettel Explore"));
+	console.log(dim(`  Starting note: ${note}`));
+	console.log(dim(`  Depth: ${depth}  Direction: ${direction}  Mode: ${mode}`));
+	console.log();
+	if (result.nodes.length === 0) {
+		console.log(warn("  No connected notes found. Check that the note path exists in the vault index."));
+		console.log();
+		return;
+	}
+	console.log(`  ${chalk.cyan("●")} ${bold(shortPath(result.root))}  ${dim("(root)")}`);
+	const byDepth = /* @__PURE__ */ new Map();
+	for (const node of result.nodes) {
+		const list = byDepth.get(node.depth) ?? [];
+		list.push(node);
+		byDepth.set(node.depth, list);
+	}
+	for (let d = 1; d <= depth; d++) {
+		const nodes = byDepth.get(d) ?? [];
+		if (nodes.length === 0) continue;
+		console.log();
+		console.log(dim(`  ${"  ".repeat(d - 1)}Depth ${d}:`));
+		for (const node of nodes) {
+			const indent = "  ".repeat(d);
+			const isBranching = result.branchingPoints.includes(node.path);
+			const typeColor = node.linkType === "sequential" ? chalk.blue : chalk.magenta;
+			const branchMark = isBranching ? chalk.yellow(" ⑂ branching") : "";
+			const title = node.title ?? shortPath(node.path);
+			const stats = dim(`in:${node.inbound} out:${node.outbound}`);
+			console.log(`  ${indent}${typeColor("→")} ${bold(title)}${branchMark}  ${stats}  ${dim(typeColor(node.linkType))}`);
+		}
+	}
+	console.log();
+	const edgeSummary = `${result.edges.length} edges  (${result.edges.filter((e) => e.type === "sequential").length} sequential, ${result.edges.filter((e) => e.type === "associative").length} associative)`;
+	console.log(dim(`  ${edgeSummary}`));
+	if (result.branchingPoints.length > 0) console.log(ok(`  ${result.branchingPoints.length} branching point(s) found`));
+	if (result.maxDepthReached) console.log(warn("  Max depth reached — use --depth to explore further"));
+	console.log();
+}
+async function cmdHealth(opts) {
+	const scope = opts.scope ?? "full";
+	const projectPath = opts.project;
+	const recentDays = parseInt(opts.days ?? "30", 10);
+	const includeTypes = opts.include ? opts.include.split(",").map((s) => s.trim()) : void 0;
+	const { zettelHealth } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const result = zettelHealth(getFedDb(), {
+		scope,
+		projectPath,
+		recentDays,
+		include: includeTypes
+	});
+	console.log();
+	console.log(header("  PAI Zettel Health"));
+	console.log(dim(`  Scope: ${scope}${scope === "project" ? `  Path: ${projectPath ?? "(none)"}` : ""}${scope === "recent" ? `  Days: ${recentDays}` : ""}`));
+	console.log();
+	const score = result.healthScore;
+	const scoreColor = score >= 80 ? chalk.green : score >= 60 ? chalk.yellow : chalk.red;
+	const barWidth = 30;
+	const filled = Math.round(score / 100 * barWidth);
+	const bar = scoreColor("█".repeat(filled)) + dim("░".repeat(barWidth - filled));
+	console.log(`  Health Score: ${scoreColor(bold(String(score)))}%  [${bar}]`);
+	console.log();
+	console.log(dim(`  Files: ${result.totalFiles}   Links: ${result.totalLinks}`));
+	console.log();
+	if (result.deadLinks.length === 0) console.log(ok("  Dead links:         none"));
+	else {
+		console.log(warn(`  Dead links:         ${result.deadLinks.length}`));
+		const preview = result.deadLinks.slice(0, 10);
+		for (const dl of preview) console.log(`    ${chalk.red("✗")} ${dim(shortPath(dl.sourcePath))} → ${bold(dl.targetRaw)} ${dim(`(line ${dl.lineNumber})`)}`);
+		if (result.deadLinks.length > 10) console.log(dim(`    ... and ${result.deadLinks.length - 10} more`));
+		console.log();
+	}
+	if (result.orphans.length === 0) console.log(ok("  Orphan notes:       none"));
+	else {
+		console.log(warn(`  Orphan notes:       ${result.orphans.length}`));
+		const preview = result.orphans.slice(0, 10);
+		for (const o of preview) console.log(`    ${chalk.yellow("○")} ${dim(shortPath(o))}`);
+		if (result.orphans.length > 10) console.log(dim(`    ... and ${result.orphans.length - 10} more`));
+		console.log();
+	}
+	if (result.disconnectedClusters <= 1) console.log(ok("  Disconnected clusters: 1 (fully connected)"));
+	else console.log(warn(`  Disconnected clusters: ${result.disconnectedClusters}`));
+	if (result.lowConnectivity.length === 0) console.log(ok("  Low-connectivity:   none"));
+	else {
+		console.log(warn(`  Low-connectivity:   ${result.lowConnectivity.length} note(s) with ≤1 link`));
+		const preview = result.lowConnectivity.slice(0, 5);
+		for (const lc of preview) console.log(`    ${chalk.dim("—")} ${dim(shortPath(lc))}`);
+		if (result.lowConnectivity.length > 5) console.log(dim(`    ... and ${result.lowConnectivity.length - 5} more`));
+	}
+	console.log();
+}
+async function cmdSurprise(note, opts) {
+	if (!opts.vaultProjectId) {
+		console.error(err("  --vault-project-id is required"));
+		process.exit(1);
+	}
+	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
+	const limit = parseInt(opts.limit ?? "10", 10);
+	const minSimilarity = parseFloat(opts.minSimilarity ?? "0.3");
+	const minGraphDistance = parseInt(opts.minDistance ?? "3", 10);
+	const { zettelSurprise } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const db = getFedDb();
+	console.log();
+	console.log(header("  PAI Zettel Surprise"));
+	console.log(dim(`  Reference note: ${note}`));
+	process.stdout.write(dim("  Searching for surprising connections...\n"));
+	const results = await zettelSurprise(db, {
+		referencePath: note,
+		vaultProjectId,
+		limit,
+		minSimilarity,
+		minGraphDistance
+	});
+	if (results.length === 0) {
+		console.log(warn("  No surprising connections found. Try lowering --min-similarity or --min-distance."));
+		console.log();
+		return;
+	}
+	console.log();
+	console.log(bold(`  Found ${results.length} surprising connection(s):`));
+	console.log();
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i];
+		const title = r.title ?? shortPath(r.path);
+		const surpriseBar = Math.round(r.surpriseScore * 10);
+		console.log(`  ${chalk.cyan(String(i + 1).padStart(2, " "))}. ${bold(title)}`);
+		console.log(`      ${dim("Surprise:")} ${chalk.magenta(r.surpriseScore.toFixed(3))} ${"■".repeat(surpriseBar)}${"□".repeat(10 - surpriseBar)}`);
+		console.log(`      ${dim("Cosine:")} ${r.cosineSimilarity.toFixed(3)}   ${dim("Graph distance:")} ${r.graphDistance}`);
+		if (r.sharedSnippet) console.log(`      ${dim("Context:")} ${r.sharedSnippet.slice(0, 120)}`);
+		console.log();
+	}
+}
+async function cmdSuggest(note, opts) {
+	if (!opts.vaultProjectId) {
+		console.error(err("  --vault-project-id is required"));
+		process.exit(1);
+	}
+	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
+	const limit = parseInt(opts.limit ?? "5", 10);
+	const excludeLinked = opts.excludeLinked !== false;
+	const { zettelSuggest } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const db = getFedDb();
+	console.log();
+	console.log(header("  PAI Zettel Suggest"));
+	console.log(dim(`  Note: ${note}`));
+	process.stdout.write(dim("  Computing suggestions...\n"));
+	const suggestions = await zettelSuggest(db, {
+		notePath: note,
+		vaultProjectId,
+		limit,
+		excludeLinked
+	});
+	if (suggestions.length === 0) {
+		console.log(warn("  No suggestions found. The note may be well-connected already."));
+		console.log();
+		return;
+	}
+	console.log();
+	console.log(bold(`  ${suggestions.length} suggested connection(s):`));
+	console.log();
+	for (let i = 0; i < suggestions.length; i++) {
+		const s = suggestions[i];
+		const title = s.title ?? shortPath(s.path);
+		console.log(`  ${chalk.green(String(i + 1).padStart(2, " "))}. ${bold(title)}`);
+		console.log(`      ${dim("Score:")} ${chalk.green(s.score.toFixed(3))}  ${dim("Semantic:")} ${s.semanticScore.toFixed(2)}  ${dim("Tag:")} ${s.tagScore.toFixed(2)}  ${dim("Neighbor:")} ${s.neighborScore.toFixed(2)}`);
+		console.log(`      ${dim("Reason:")} ${s.reason}`);
+		console.log(`      ${dim("Wikilink:")} ${chalk.cyan(s.suggestedWikilink)}`);
+		console.log();
+	}
+}
+async function cmdConverse(question, opts) {
+	if (!opts.vaultProjectId) {
+		console.error(err("  --vault-project-id is required"));
+		process.exit(1);
+	}
+	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
+	const depth = parseInt(opts.depth ?? "2", 10);
+	const limit = parseInt(opts.limit ?? "15", 10);
+	const { zettelConverse } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const db = getFedDb();
+	console.log();
+	console.log(header("  PAI Zettel Converse"));
+	console.log(dim(`  Question: "${question}"`));
+	process.stdout.write(dim("  Searching vault for relevant notes...\n"));
+	const result = await zettelConverse(db, {
+		question,
+		vaultProjectId,
+		depth,
+		limit
+	});
+	if (result.relevantNotes.length === 0) {
+		console.log(warn("  No relevant notes found. Try rephrasing your question."));
+		console.log();
+		return;
+	}
+	console.log();
+	console.log(bold(`  ${result.relevantNotes.length} relevant note(s) from ${result.domains.length} domain(s):`));
+	console.log(dim(`  Domains: ${result.domains.join(", ")}`));
+	console.log();
+	for (const note of result.relevantNotes) {
+		const title = note.title ?? shortPath(note.path);
+		console.log(`  ${chalk.cyan("◆")} ${bold(title)}  ${dim(`[${note.domain}]  score: ${note.score.toFixed(3)}`)}`);
+		if (note.snippet) console.log(`    ${dim(note.snippet.slice(0, 200))}`);
+		console.log();
+	}
+	if (result.connections.length > 0) {
+		console.log(bold("  Cross-domain connections:"));
+		for (const conn of result.connections.slice(0, 10)) console.log(`  ${chalk.magenta("⟷")} ${dim(conn.fromDomain)} ${chalk.dim("→")} ${dim(conn.toDomain)}  ${dim(shortPath(conn.fromPath))} → ${dim(shortPath(conn.toPath))}  ${dim(`strength: ${conn.strength}`)}`);
+		console.log();
+	}
+	console.log(bold("  Synthesis prompt (paste into your AI):"));
+	console.log();
+	const promptLines = result.synthesisPrompt.split("\n");
+	for (const line of promptLines) console.log(`  ${dim(line)}`);
+	console.log();
+}
+async function cmdThemes(opts) {
+	if (!opts.vaultProjectId) {
+		console.error(err("  --vault-project-id is required"));
+		process.exit(1);
+	}
+	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
+	const lookbackDays = parseInt(opts.days ?? "30", 10);
+	const minClusterSize = parseInt(opts.minSize ?? "3", 10);
+	const maxThemes = parseInt(opts.maxThemes ?? "10", 10);
+	const similarityThreshold = parseFloat(opts.threshold ?? "0.65");
+	const { zettelThemes } = await import("../zettelkasten-Co-w0XSZ.mjs");
+	const db = getFedDb();
+	console.log();
+	console.log(header("  PAI Zettel Themes"));
+	console.log(dim(`  Lookback: ${lookbackDays}d  Min cluster: ${minClusterSize}  Threshold: ${similarityThreshold}`));
+	process.stdout.write(dim("  Detecting emerging themes...\n"));
+	const result = await zettelThemes(db, {
+		vaultProjectId,
+		lookbackDays,
+		minClusterSize,
+		maxThemes,
+		similarityThreshold
+	});
+	if (result.themes.length === 0) {
+		console.log(warn(`  No themes detected in the last ${lookbackDays} days. Try --days with a larger window.`));
+		console.log();
+		return;
+	}
+	const fromDate = new Date(result.timeWindow.from).toISOString().slice(0, 10);
+	const toDate = new Date(result.timeWindow.to).toISOString().slice(0, 10);
+	console.log();
+	console.log(bold(`  ${result.themes.length} theme(s) from ${result.totalNotesAnalyzed} notes  [${fromDate} → ${toDate}]:`));
+	console.log();
+	for (let i = 0; i < result.themes.length; i++) {
+		const cluster = result.themes[i];
+		const diversityBar = Math.round(cluster.folderDiversity * 10);
+		const indexSuggestion = cluster.suggestIndexNote ? chalk.yellow("  ⚑ suggest index note") : "";
+		console.log(`  ${chalk.cyan(String(i + 1).padStart(2, " "))}. ${bold(cluster.label)}${indexSuggestion}`);
+		console.log(`      ${dim("Notes:")} ${cluster.size}  ${dim("Diversity:")} ${"█".repeat(diversityBar)}${"░".repeat(10 - diversityBar)} ${cluster.folderDiversity.toFixed(2)}  ${dim("Linked:")} ${Math.round(cluster.linkedRatio * 100)}%`);
+		const preview = cluster.notes.slice(0, 5);
+		for (const note of preview) {
+			const title = note.title ?? shortPath(note.path);
+			console.log(`      ${dim("•")} ${title}`);
+		}
+		if (cluster.notes.length > 5) console.log(dim(`      ... and ${cluster.notes.length - 5} more`));
+		console.log();
+	}
+}
+function registerZettelCommands(parent, _getDb) {
+	parent.command("explore <note>").description("Follow link chains from a starting note").option("--depth <n>", "Maximum traversal depth (1-10)", "3").option("--direction <d>", "Link direction: forward | backward | both", "both").option("--mode <m>", "Edge mode: sequential | associative | all", "all").action(async (note, opts) => {
+		try {
+			await cmdExplore(note, opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+	parent.command("health").description("Vault structural health audit: dead links, orphans, connectivity").option("--scope <s>", "Scope: full | recent | project", "full").option("--project <path>", "Project path prefix (requires --scope project)").option("--days <n>", "Look-back window in days (requires --scope recent)", "30").option("--include <types>", "Comma-separated subset: dead_links,orphans,disconnected,low_connectivity").action(async (opts) => {
+		try {
+			await cmdHealth(opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+	parent.command("surprise <note>").description("Find semantically similar but graph-distant notes (surprising connections)").requiredOption("--vault-project-id <n>", "Project ID for the vault in the federation DB").option("--limit <n>", "Maximum results", "10").option("--min-similarity <f>", "Minimum cosine similarity (0–1)", "0.3").option("--min-distance <n>", "Minimum graph distance", "3").action(async (note, opts) => {
+		try {
+			await cmdSurprise(note, opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+	parent.command("suggest <note>").description("Suggest new wikilink connections for a note").requiredOption("--vault-project-id <n>", "Project ID for the vault in the federation DB").option("--limit <n>", "Maximum suggestions", "5").option("--no-exclude-linked", "Include notes already linked from this one").action(async (note, opts) => {
+		try {
+			await cmdSuggest(note, opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+	parent.command("converse <question>").description("Ask the vault a question and get a synthesis prompt with relevant notes").requiredOption("--vault-project-id <n>", "Project ID for the vault in the federation DB").option("--depth <n>", "Graph expansion depth around matched notes", "2").option("--limit <n>", "Maximum relevant notes to include", "15").action(async (question, opts) => {
+		try {
+			await cmdConverse(question, opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+	parent.command("themes").description("Detect emerging theme clusters in recently edited notes").requiredOption("--vault-project-id <n>", "Project ID for the vault in the federation DB").option("--days <n>", "Look-back window in days", "30").option("--min-size <n>", "Minimum notes per cluster", "3").option("--max-themes <n>", "Maximum themes to return", "10").option("--threshold <f>", "Similarity threshold for clustering (0–1)", "0.65").action(async (opts) => {
+		try {
+			await cmdThemes(opts);
+		} catch (e) {
+			console.error(err(`  Error: ${e}`));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/update.ts
 function line(text = "") {
@@ -5906,6 +6700,7 @@ registerUpdateCommand(program);
 registerNotifyCommands(program.command("notify").description("Notification config: status, get, set, test, send"));
 registerTopicCommands(program.command("topic").description("Topic shift detection: check whether context has drifted to a different project"));
 registerObsidianCommands(program.command("obsidian").description("Obsidian vault: sync project notes, view status, open in Obsidian"), getDb);
+registerZettelCommands(program.command("zettel").description("Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest"), getDb);
 program.command("go <query>").description("Jump to a project directory by slug or partial name.\nPrints the root path to stdout — use with: cd $(pai go <query>)\nExample shell function in ~/.zshrc:\n  pcd() { cd \"$(pai go \"$@\")\" }").action((query) => {
 	cmdGo(getDb(), query);
 });