@tekmidian/pai 0.10.1 → 0.11.0

package/README.md

@@ -299,34 +299,28 @@ All hooks are TypeScript compiled to `.mjs` modules. They run as separate proces
 
 PAI gives you a complete picture of every Claude Code session running on your machine — live tabs in iTerm2, paused snapshots on disk, and everything in between.
 
-### The Core Idea: Think in Topics
+### The Core Idea: One Entry Point
 
-The user's mental model is simple: "I did something on a given subject. Where was I working on it? Let me continue."
+`pai <name>` is the universal session command. It does the right thing based on session state:
 
-PAI v0.10.0 is built around this. You think in **topics**, not project names or session UUIDs. PAI handles the lookup.
+- **Live session** — switches the iTerm2 tab to front (no new Claude launched)
+- **Resumable session** — probes `claude --resume`, launches with the saved UUID
+- **Transcript/stub** — starts a fresh Claude in the same project directory
+- **No match** — searches `~/.claude/history.jsonl`, shows a candidate picker
 
 ```bash
-pai mdf             # Find every session where you worked on MDF
-pai solar panels    # Free-text search across your prompt history
-pai 0856d40b        # Resume by UUID prefix (from pai sessions)
-pai                 # Show all recent sessions (interactive picker)
+pai aibroker        # Switch to the live AIBroker tab (iTerm comes to front)
+pai youdrill        # Resume the youdrill session, or fresh if snapshot is stale
+pai mdf             # Free-text search across your prompt history
+pai 0856d40b        # Resume by UUID prefix
+pai                 # Show all sessions (deduped, one row per name)
 ```
 
-When you type `pai mdf`, PAI checks:
-1. Is "mdf" a named session in the catalog? → launch immediately, no picker
-2. Is "mdf" a UUID prefix? → direct filesystem resume
-3. Otherwise → grep `~/.claude/history.jsonl` for matching prompts, show candidate list, you pick a number
-
-The picked session resolves to the best resumable snapshot in the same project directory. PAI probes `claude --resume` automatically. If the snapshot is stale, it starts a fresh Claude in the same directory.
-
-### Daily Verbs
-
-The commands you'll use every day:
+### Daily Commands
 
 ```bash
-pai                   # Recent sessions picker (live + disk)
-pai <topic>           # Find + launch session by topic/keyword/UUID
-pai cd <name>         # cd to a project directory (no Claude launch)
+pai                   # List sessions (deduped by name, one row per name)
+pai <name>            # Switch / resume / fresh — universal
 pai pause             # Save state checkpoint (write ## Continue to TODO.md)
 pai pause all         # Pause every live Claude session at once
 pai end               # Finalize: save state + mark session note Completed
@@ -339,15 +333,25 @@ And inside Claude Code, the two slash commands that matter:
 /end      →  same as /pause, plus marks the session note Completed
 ```
 
-### Finding Sessions
+### Session Listing
+
+`pai` (no args) shows a single deduped table — one row per session name, regardless of how many snapshots exist on disk:
 
-`pai` (no args) shows two sections:
+```
+Sessions:
+
+  #   name        status      age       project                       last prompt
+  --  ----------  ----------  --------  ----------------------------  --------------------------
+  1   AIBroker    live        now       —                             —
+  2   PAI         resumable   2m ago    /…dev/ai/PAI                  "refactor session listing…"
+  3   MDF         transcript  3d ago    /…MDF/Infrastruktur/Webseiten "ok so we recently had…"
+```
 
-**Live Sessions** — pulled from AIBroker in real time. One row per active iTerm2 pane running Claude Code. Columns: `#`, `id`, `name`, `at prompt`.
+Status values: `live` (active iTerm tab), `resumable` (clean snapshot on disk), `transcript` (history available, not resumable), `stub` (empty or minimal).
 
-**Recent Sessions** — disk scan of `~/.claude/projects/`, sorted by last-modified.
+### Finding Sessions by Topic
 
-`pai <topic>` searches your prompt history in `~/.claude/history.jsonl`, groups results by session, and shows a table:
+`pai <topic>` first checks session names, then falls back to searching your prompt history:
 
 ```
 Sessions matching "mdf":
@@ -360,16 +364,14 @@ Sessions matching "mdf":
   Enter # to launch (1-2), or press Enter to cancel:
 ```
 
-Type the number and press Enter. PAI launches Claude, resumes if possible, starts fresh if not.
-
-Use `pai <topic> --auto` (or `-y`) to auto-pick #1 without the prompt. Use `pai <topic> 2` to pick #2 directly.
+Use `pai <topic> --auto` (or `-y`) to auto-pick #1. Use `pai <topic> 2` to pick directly.
 
 ### Power User Access
 
-The full session management namespace is still available for power users:
+The full session management namespace is still available:
 
 ```bash
-pai sessions              # Live + disk listing (same as bare pai, with more columns)
+pai sessions              # Live + disk listing (with more columns)
 pai sessions --all        # Include unnamed orphan sessions
 pai sessions --all-tabs   # Include shell tabs in the live section
 pai sessions goto <name>  # Named-session resolver (same as pai <name>)

package/dist/cli/index.mjs

@@ -2758,6 +2758,29 @@ async function sendToSession(sessionId, text) {
 		};
 	}
 }
+/**
+* Switch iTerm2 focus to the session identified by `target`.
+*
+* `target` can be a sessionId, paiName, or tab index number (as string).
+* After switching, activates the iTerm2 application itself so the window
+* comes to the foreground.
+*
+* Returns { ok: true } if AIBroker confirmed the switch, or
+* { ok: false, error } if AIBroker is not running or the session was not found.
+*/
+async function switchToSession(target) {
+	try {
+		await callAiBroker("switch", { target });
+		const { spawnSync } = await import("node:child_process");
+		spawnSync("osascript", ["-e", "tell application \"iTerm\" to activate"], { stdio: "ignore" });
+		return { ok: true };
+	} catch (e) {
+		return {
+			ok: false,
+			error: String(e)
+		};
+	}
+}
 
 //#endregion
 //#region src/cli/commands/session/recent.ts
@@ -2766,7 +2789,7 @@ function fmtSize(bytes) {
 	if (bytes < 1048576) return `${Math.round(bytes / 1024)}K`;
 	return `${(bytes / 1048576).toFixed(1)}M`;
 }
-function fmtStatus(status) {
+function fmtStatus$1(status) {
 	switch (status) {
 		case "resumable": return chalk.green("resumable");
 		case "stub": return chalk.yellow("stub");
@@ -2872,7 +2895,7 @@ async function cmdRecent(db, opts) {
 			prompt,
 			s.userLines > 0 ? String(s.userLines) : dim("—"),
 			dim(fmtSize(s.topLevelSize)),
-			fmtStatus(s.sessionStatus)
+			fmtStatus$1(s.sessionStatus)
 		];
 	});
 	console.log(renderTable(headers, rows));
@@ -9594,6 +9617,64 @@ async function searchHistory(query, maxResults) {
 
 //#endregion
 //#region src/cli/commands/main-resolver.ts
+const STATUS_PRIORITY = {
+	live: 0,
+	resumable: 1,
+	"transcript-only": 2,
+	stub: 3,
+	orphan: 4
+};
+function buildDeduped(liveSessions, diskSessions) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const s of liveSessions) {
+		if (s.kind === "shell") continue;
+		const rawName = s.paiName ?? s.name ?? s.sessionId.slice(0, 8);
+		const key = rawName.toLowerCase();
+		const entry = {
+			name: rawName,
+			status: "live",
+			liveSessionId: s.sessionId,
+			lastActivity: Date.now(),
+			project: "",
+			lastPrompt: ""
+		};
+		const existing = byName.get(key);
+		if (!existing || STATUS_PRIORITY["live"] < STATUS_PRIORITY[existing.status]) byName.set(key, entry);
+	}
+	for (const s of diskSessions) {
+		const rawName = s.friendlyName ?? s.shortId;
+		const key = rawName.toLowerCase();
+		let status;
+		if (s.resumable) status = "resumable";
+		else if (s.sessionStatus === "transcript-only") status = "transcript-only";
+		else if (s.sessionStatus === "stub") status = "stub";
+		else status = "orphan";
+		const entry = {
+			name: rawName,
+			status,
+			diskSession: s,
+			lastActivity: s.mtime,
+			project: s.decodedPath ?? "",
+			lastPrompt: s.lastUserPrompt ?? ""
+		};
+		const existing = byName.get(key);
+		if (!existing) byName.set(key, entry);
+		else {
+			const existingPriority = STATUS_PRIORITY[existing.status];
+			const newPriority = STATUS_PRIORITY[status];
+			if (newPriority < existingPriority) byName.set(key, entry);
+			else if (newPriority === existingPriority && entry.lastActivity > existing.lastActivity) byName.set(key, entry);
+		}
+	}
+	const entries = Array.from(byName.values());
+	entries.sort((a, b) => {
+		const pa = STATUS_PRIORITY[a.status];
+		const pb = STATUS_PRIORITY[b.status];
+		if (pa !== pb) return pa - pb;
+		return b.lastActivity - a.lastActivity;
+	});
+	return entries;
+}
 function probeResume(uuid, cwd) {
 	const result = spawnSync("claude", [
 		"--resume",
@@ -9626,23 +9707,13 @@ function probeResume(uuid, cwd) {
 	};
 	return { ok: true };
 }
-/**
-* Launch Claude for the given session. Handles resume probe + fallback to fresh.
-* Never returns on success (process.exit inside spawnSync block).
-*/
 function launchSession(session, allSessions, dryRun) {
 	let resumableUuid;
-	let resumableSession;
-	if (session.resumable) {
-		resumableUuid = session.uuid;
-		resumableSession = session;
-	} else if (session.encodedDir) {
+	if (session.resumable) resumableUuid = session.uuid;
+	else if (session.encodedDir) {
 		const sameProject = allSessions.filter((s) => s.encodedDir === session.encodedDir && s.resumable);
 		sameProject.sort((a, b) => b.mtime - a.mtime);
-		if (sameProject.length > 0) {
-			resumableSession = sameProject[0];
-			resumableUuid = resumableSession.uuid;
-		}
+		if (sameProject.length > 0) resumableUuid = sameProject[0].uuid;
 	}
 	const rawDir = session.clcDirectory ?? session.registryRootPath ?? session.decodedPath;
 	let projectDir;
@@ -9723,11 +9794,6 @@ function launchSession(session, allSessions, dryRun) {
 		process.exit(result.status ?? 0);
 	}
 }
-/**
-* Given a SessionMatch from history search, find the corresponding ScannedSession
-* (for launch). Falls back to a minimal synthetic session using the decodedPath
-* from the history entry's project field.
-*/
 function matchToSession(match, allSessions) {
 	if (!match.sessionId) return null;
 	const catalogMatch = allSessions.find((s) => s.uuid === match.sessionId);
@@ -9762,6 +9828,15 @@ function shortenProject(p, maxLen = 44) {
 	if (!p || p.length <= maxLen) return p || dim("—");
 	return "…" + p.slice(-(maxLen - 1));
 }
+function fmtStatus(s) {
+	switch (s) {
+		case "live": return chalk.green("live");
+		case "resumable": return chalk.cyan("resumable");
+		case "transcript-only": return chalk.dim("transcript");
+		case "stub": return chalk.dim("stub");
+		case "orphan": return chalk.dim("orphan");
+	}
+}
 async function askForChoice(max) {
 	return new Promise((resolve) => {
 		const rl = createInterface({
@@ -9787,51 +9862,36 @@ async function cmdMain(db, query, pickN, opts) {
 		try {
 			liveSessions = await fetchLiveSessions();
 		} catch {}
-		const claudeLive = liveSessions.filter((s) => s.kind !== "shell");
-		const recentDisk = allSessions.slice(0, maxResults);
-		if (claudeLive.length === 0 && recentDisk.length === 0) {
+		const deduped = buildDeduped(liveSessions, allSessions);
+		if (deduped.length === 0) {
 			console.log(warn("No sessions found. Start Claude Code in a project directory first."));
 			return;
 		}
-		if (claudeLive.length > 0) {
-			console.log("\n" + header("Live Sessions") + "\n");
-			const liveHeaders = [
-				"#",
-				"id",
-				"name",
-				"at prompt"
-			];
-			const liveRows = claudeLive.map((s, i) => [
+		console.log("\n" + header("Sessions") + "\n");
+		const tableHeaders = [
+			"#",
+			"name",
+			"status",
+			"age",
+			"project",
+			"last prompt"
+		];
+		const tableRows = deduped.slice(0, maxResults).map((entry, i) => {
+			const age = entry.status === "live" ? chalk.green("now") : dim(fmtAge(entry.lastActivity));
+			const snippet = entry.lastPrompt.replace(/\n+/g, " ").trim().slice(0, 36);
+			const project = entry.diskSession ? dim(shortenProject(entry.diskSession.friendlyName ?? entry.diskSession.decodedPath, 28)) : dim("—");
+			return [
 				dim(String(i + 1)),
-				chalk.cyan(s.sessionId.slice(0, 8)),
-				s.paiName ?? s.name ?? dim("—"),
-				s.atPrompt ? chalk.green("yes") : chalk.dim("no")
-			]);
-			console.log(renderTable(liveHeaders, liveRows));
-		}
-		if (recentDisk.length > 0) {
-			console.log("\n" + header("Recent Sessions") + "\n");
-			const diskHeaders = [
-				"#",
-				"id",
-				"age",
-				"project",
-				"last prompt"
+				chalk.white(entry.name),
+				fmtStatus(entry.status),
+				age,
+				project,
+				chalk.dim(snippet ? `"${snippet}"` : "—")
 			];
-			const diskRows = recentDisk.map((s, i) => {
-				const snippet = s.lastUserPrompt.replace(/\n+/g, " ").trim().slice(0, 40);
-				return [
-					dim(String(i + 1)),
-					chalk.cyan(s.shortId),
-					dim(fmtAge(s.mtime)),
-					dim(shortenProject(s.friendlyName ?? s.decodedPath, 30)),
-					chalk.dim(snippet ? `"${snippet}"` : "—")
-				];
-			});
-			console.log(renderTable(diskHeaders, diskRows));
-		}
+		});
+		console.log(renderTable(tableHeaders, tableRows));
 		console.log();
-		console.log(dim("  Resume a session: ") + chalk.white("pai <topic>") + dim("  or  ") + chalk.white("pai <id>"));
+		console.log(dim("  Switch/resume/start: ") + chalk.white("pai <name>") + dim("  or  ") + chalk.white("pai <uuid-prefix>"));
 		console.log();
 		return;
 	}
@@ -9848,39 +9908,94 @@ async function cmdMain(db, query, pickN, opts) {
 		}
 	}
 	{
+		let liveSessions = [];
+		try {
+			liveSessions = await fetchLiveSessions();
+		} catch {}
+		const deduped = buildDeduped(liveSessions, allSessions);
 		const qLower = query.toLowerCase();
-		const byExact = allSessions.filter((s) => s.friendlyName && s.friendlyName.toLowerCase() === qLower);
-		if (byExact.length >= 1) {
-			launchSession(byExact[0], allSessions, opts.dryRun ?? false);
-			return;
+		const exactMatch = deduped.find((e) => e.name.toLowerCase() === qLower);
+		if (exactMatch) {
+			if (exactMatch.status === "live" && exactMatch.liveSessionId) {
+				if (opts.dryRun) {
+					console.log("\n" + chalk.bold("Dry run — would switch iTerm tab:") + "\n");
+					console.log(`  target: ${exactMatch.name} (${exactMatch.liveSessionId.slice(0, 8)})`);
+					console.log(`  action: aibroker_switch + osascript iTerm activate`);
+					console.log();
+					return;
+				}
+				const result = await switchToSession(exactMatch.liveSessionId);
+				if (result.ok) console.log(ok(`Switched to live session: ${chalk.white(exactMatch.name)}`));
+				else {
+					console.error(warn(`Could not switch via AIBroker: ${result.error ?? "unknown error"}`));
+					console.error(dim("  Falling back to disk launch..."));
+					if (exactMatch.diskSession) launchSession(exactMatch.diskSession, allSessions, opts.dryRun ?? false);
+				}
+				return;
+			}
+			if (exactMatch.diskSession) {
+				launchSession(exactMatch.diskSession, allSessions, opts.dryRun ?? false);
+				return;
+			}
 		}
-		const byPartial = allSessions.filter((s) => s.friendlyName && s.friendlyName.toLowerCase().includes(qLower));
-		if (byPartial.length === 1) {
-			launchSession(byPartial[0], allSessions, opts.dryRun ?? false);
-			return;
+		const partialMatches = deduped.filter((e) => e.name.toLowerCase().includes(qLower));
+		if (partialMatches.length === 1) {
+			const match = partialMatches[0];
+			if (match.status === "live" && match.liveSessionId) {
+				if (opts.dryRun) {
+					console.log("\n" + chalk.bold("Dry run — would switch iTerm tab:") + "\n");
+					console.log(`  target: ${match.name} (${match.liveSessionId.slice(0, 8)})`);
+					console.log(`  action: aibroker_switch + osascript iTerm activate`);
+					console.log();
+					return;
+				}
+				const result = await switchToSession(match.liveSessionId);
+				if (result.ok) console.log(ok(`Switched to live session: ${chalk.white(match.name)}`));
+				else {
+					console.error(warn(`Could not switch via AIBroker: ${result.error ?? "unknown error"}`));
+					if (match.diskSession) launchSession(match.diskSession, allSessions, opts.dryRun ?? false);
+				}
+				return;
+			}
+			if (match.diskSession) {
+				launchSession(match.diskSession, allSessions, opts.dryRun ?? false);
+				return;
+			}
 		}
-		if (byPartial.length > 1) {
+		if (partialMatches.length > 1) {
 			console.log("\n" + header(`Sessions matching "${query}"`) + "\n");
 			const headers = [
 				"#",
-				"id",
-				"age",
 				"name",
+				"status",
+				"age",
 				"project"
 			];
-			const rows = byPartial.slice(0, maxResults).map((s, i) => [
-				dim(String(i + 1)),
-				chalk.cyan(s.shortId),
-				dim(fmtAge(s.mtime)),
-				s.friendlyName ?? dim("—"),
-				dim(shortenProject(s.decodedPath, 36))
-			]);
+			const rows = partialMatches.slice(0, maxResults).map((entry, i) => {
+				const age = entry.status === "live" ? chalk.green("now") : dim(fmtAge(entry.lastActivity));
+				const project = entry.diskSession ? dim(shortenProject(entry.diskSession.decodedPath, 36)) : dim("—");
+				return [
+					dim(String(i + 1)),
+					chalk.white(entry.name),
+					fmtStatus(entry.status),
+					age,
+					project
+				];
+			});
 			console.log(renderTable(headers, rows));
 			console.log();
 			if (pickN !== void 0) {
 				const idx = pickN - 1;
-				if (idx >= 0 && idx < byPartial.length) {
-					launchSession(byPartial[idx], allSessions, opts.dryRun ?? false);
+				if (idx >= 0 && idx < partialMatches.length) {
+					const match = partialMatches[idx];
+					if (match.status === "live" && match.liveSessionId) {
+						if (!opts.dryRun) {
+							await switchToSession(match.liveSessionId);
+							console.log(ok(`Switched to live session: ${chalk.white(match.name)}`));
+						}
+						return;
+					}
+					if (match.diskSession) launchSession(match.diskSession, allSessions, opts.dryRun ?? false);
 					return;
 				}
 				console.error(err(`Invalid choice: ${pickN}`));
@@ -9888,17 +10003,34 @@ async function cmdMain(db, query, pickN, opts) {
 				return;
 			}
 			if (opts.auto) {
-				launchSession(byPartial[0], allSessions, opts.dryRun ?? false);
+				const match = partialMatches[0];
+				if (match.status === "live" && match.liveSessionId) {
+					if (!opts.dryRun) {
+						await switchToSession(match.liveSessionId);
+						console.log(ok(`Switched to live session: ${chalk.white(match.name)}`));
+					}
+					return;
+				}
+				if (match.diskSession) launchSession(match.diskSession, allSessions, opts.dryRun ?? false);
 				return;
 			}
-			const choice = await askForChoice(Math.min(byPartial.length, maxResults));
-			if (choice !== null) launchSession(byPartial[choice - 1], allSessions, opts.dryRun ?? false);
+			const choice = await askForChoice(Math.min(partialMatches.length, maxResults));
+			if (choice !== null) {
+				const match = partialMatches[choice - 1];
+				if (match.status === "live" && match.liveSessionId) {
+					await switchToSession(match.liveSessionId);
+					console.log(ok(`Switched to live session: ${chalk.white(match.name)}`));
+					return;
+				}
+				if (match.diskSession) launchSession(match.diskSession, allSessions, opts.dryRun ?? false);
+			}
 			return;
 		}
 	}
 	if (!existsSync(HISTORY_FILE)) {
 		console.error(err("~/.claude/history.jsonl not found."));
 		console.error(dim("  No prompt history available for search."));
+		console.error(dim(`  Try: pai  (no args) to see all sessions.`));
 		process.exitCode = 1;
 		return;
 	}
@@ -9907,7 +10039,7 @@ async function cmdMain(db, query, pickN, opts) {
 	if (matches.length === 0) {
 		console.log(warn(`No sessions found matching "${query}".`));
 		console.log(dim(`  Try a shorter or different search term.`));
-		console.log(dim(`  Or run: `) + chalk.white("pai") + dim(" (no args) to see all recent sessions."));
+		console.log(dim(`  Or run: `) + chalk.white("pai") + dim(" (no args) to see all sessions."));
 		return;
 	}
 	console.log("\n" + header(`Sessions matching "${query}"`) + "\n");
@@ -9976,13 +10108,12 @@ async function cmdMain(db, query, pickN, opts) {
 //#endregion
 //#region src/cli/index.ts
 /**
-* PAI Knowledge OS — CLI entry point (v0.10.0 topic-first redesign)
+* PAI Knowledge OS — CLI entry point (v0.11.0 deduped sessions + universal pai <name>)
 *
-* Top-level surface:
-*   pai                    → recent sessions picker
-*   pai <topic>            → history search + candidate picker + launch
+* Daily surface:
+*   pai                    → deduped session listing (one row per name)
+*   pai <name>             → universal: switch live tab / resume / fresh
 *   pai <uuid-prefix>      → direct session resume via filesystem scan
-*   pai cd <name>          → cd to project directory (no Claude launch)
 *   pai pause [all]        → save state (or mass-pause every live session)
 *   pai end                → finalize session
 *
@@ -10012,28 +10143,25 @@ function getDb() {
 }
 const program = new Command();
 program.name("pai").description("PAI Knowledge OS — Personal AI Infrastructure CLI").version(getVersion(), "-V, --version", "Print version and exit").addHelpText("after", `
-Usage:
-  pai                     Show recent sessions (interactive picker)
-  pai <topic>             Find sessions by topic and launch the chosen one
-  pai <uuid-prefix>       Resume a specific session by UUID
-  pai cd <name>           cd to a project directory (no Claude launch)
-  pai pause [all]         Save state (or mass-pause every live session)
-  pai end                 Finalize session: save state + mark note Completed
+Daily commands:
+  pai                     List your sessions (deduped by name)
+  pai <name>              Switch / resume / fresh — universal
+  pai pause               Save state checkpoint for the current session
+  pai pause all           Pause every live Claude session at once
+  pai end                 Finalize current session: save state + mark Completed
+
+Subcommands (advanced):
+  pai sessions ...        Full session management
+  pai projects ...        Project management
+  pai registry ...        Registry maintenance
+  pai memory ...          Memory engine
+  pai shell-init          Shell integration (eval "$(pai shell-init)")
 
 Examples:
-  pai mdf                 Find all sessions where you worked on MDF
-  pai solar panels        Free-text search across your prompt history
+  pai aibroker            Switch to the live AIBroker tab in iTerm
+  pai mdf                 Find sessions where you worked on MDF
   pai 81c5c3dc            Resume session by UUID prefix
-  pai                     See the 20 most recent sessions
-
-Power-user namespaces (run "pai sessions --help" etc. for details):
-  pai sessions ...        Full session management (list, goto, info, ...)
-  pai projects ...        Project management (cd, rebind, list, ...)
-  pai registry ...        Registry maintenance (scan, ...)
-  pai memory ...          Memory engine (index, search, ...)
-
-Shell integration:
-  eval "$(pai shell-init)"    # Add to ~/.zshrc for pai cd to work`);
+  pai                     See all sessions (deduped, one row per name)`);
 registerProjectsCommands(program.command("projects").description("Manage registered projects (list, cd, add, info, ...)"), getDb);
 const sessionsCmd = program.command("sessions").description("Session management (list, goto, pause, ...)");
 registerSessionsCommands(sessionsCmd, getDb);
@@ -10071,10 +10199,10 @@ program.command("pause [target]").description("Save state and display safe-exit
 program.command("end").description("Finalize a session: save state, mark note Completed, display safe-exit instructions.\nLong form: pai sessions end").option("--dry-run", "Preview all changes without writing them").action((opts) => {
 	cmdEnd(getDb(), opts);
 });
-program.command("resume <name>").description("Go to a session by name or UUID: resume if resumable, start fresh otherwise.\nAlso: pai <name>  (shorter)  |  pai sessions goto <name>  (long form)").option("--dry-run", "Print the exact argv and cwd, then exit without launching").action((name, opts) => {
+program.command("resume <name>", { hidden: true }).description("Go to a session by name or UUID: resume if resumable, start fresh otherwise.\nPrefer: pai <name>  |  Long form: pai sessions goto <name>").option("--dry-run", "Print the exact argv and cwd, then exit without launching").action((name, opts) => {
 	cmdGoto(getDb(), name, { dryRun: opts.dryRun });
 });
-program.command("cd <identifier>").description("cd to a project directory (shell wrapper handles the actual cd).\nLong form: pai projects cd <identifier>\nThe shell function installed by pai shell-init intercepts this command\nand calls builtin cd with the resolved path.\nAuto-detects moved projects when the registered path no longer exists.").action((identifier) => {
+program.command("cd <identifier>", { hidden: true }).description("cd to a project directory (shell wrapper handles the actual cd).\nLong form: pai projects cd <identifier>\nThe shell function installed by pai shell-init intercepts this command\nand calls builtin cd with the resolved path.\nAuto-detects moved projects when the registered path no longer exists.").action((identifier) => {
 	const db = getDb();
 	const project = resolveIdentifier(db, identifier);
 	if (!project) {