@tekmidian/pai 1.0.0 → 1.0.3

package/dist/worker-config-DESkIjMF.mjs

@@ -0,0 +1,41 @@
+import "./utils-J2b9y8PC.mjs";
+import "./config-XpZWOYOG.mjs";
+import "./config-Bu1_vbY8.mjs";
+import "./paths-CHifubDh.mjs";
+import "./worktree-CRs2gyg0.mjs";
+import "./status-ggJ7lgVg.mjs";
+import "./pool-Dh-q3iJi.mjs";
+import "./helpers-CRuBUas3.mjs";
+import "./scope-D-h6F6DN.mjs";
+import "./routing-BAAST9vT.mjs";
+import "./tool-errors-7E13StWd.mjs";
+import "./wait-ByV0OyMZ.mjs";
+import "./local-tiers-BE4jGaMa.mjs";
+import "./caller-identity-yLFb7CKq.mjs";
+import "./capacity-DEveQdFV.mjs";
+import "./local-instances-DOxSgT_L.mjs";
+import "./local-candidate-DLdwQt0s.mjs";
+import "./factory-DjAAsqr_.mjs";
+import "./postgres-C6ti4haA.mjs";
+import "./embedding-gate-6rZrWRXa.mjs";
+import "./embeddings-BVq3esBF.mjs";
+import "./router-CQSc3lk3.mjs";
+import "./launch-Jh5NVeNe.mjs";
+import "./health-Dnym-qcT.mjs";
+import "./run-CSC7mgPf.mjs";
+import "./controls-CPoeudou.mjs";
+import "./endreason-C577xIQz.mjs";
+import "./render-BYmQkuLd.mjs";
+import "./operator-CyuB3aVw.mjs";
+import "./kill-tree-EWYaEk5v.mjs";
+import "./pool-cli-BggU8GRp.mjs";
+import "./pane-audit-DKQt71s4.mjs";
+import "./providers-CblTFrhz.mjs";
+import { A as workerMcpCommand, C as workerBenchCommand, D as workerFallbackCommand, E as workerControlsCommand, F as workerProvidersCommand, I as workerProxyCommand, L as workerRolesCommand, M as workerOnCommand, N as workerPolicyCommand, O as workerInstallCommand, P as workerPoolCommand, R as workerRouteCommand, S as stopInstance, T as workerConfigCommand, _ as portOpen, a as collectEnv, b as startTier, c as currentInstances, d as isUp, f as killInstance, g as portListeners, h as parseCostTier, i as cliInflight, j as workerOffCommand, k as workerLocalCommand, l as fail, m as listServers, n as WORKER_CONFIG_COMMANDS, o as collectTags, p as launchDetached, r as buildClassTarget, s as controlsArgv, t as PROVIDER_EDIT_COMMANDS, u as healthOk, v as serverLine, w as workerClassesCommand, x as stopAll, y as startInstance } from "./worker-config-CJhEMk19.mjs";
+import "./main-config-ops-BEMpuhDz.mjs";
+import "./cockpit-actions-BBHeyEZI.mjs";
+import "./ipc-client-CaiGJnSM.mjs";
+import "./embed-pass-DIWjA68P.mjs";
+import "./fallback-DFlItw1Z.mjs";
+
+export { currentInstances, startInstance, startTier, stopAll, stopInstance };

package/dist/{workers-config-DEI9lrV4.mjs → workers-config-f8KrkY4L.mjs}

@@ -1,4 +1,4 @@
-import { $ as starterWorkersYamlText, B as WORKERS_YAML_FILENAME, G as inlineWorkersYamlKeys, H as defaultWorkersYamlPath, J as parseBuiltinAnthropic, K as migrateWorkersToYaml, Q as relocateWorkersYaml, U as effectiveWorkersYamlData, V as buildWorkersYamlText, W as initWorkersYaml, X as readMergeVerify, Y as parseWorkersYamlDocument, Z as readWorkersYaml, et as workersYamlLegacyNotice, it as yamlProviderToRaw, nt as writeWorkersYaml, q as needsWorkersYamlRelocation, rt as writeWorkersYamlText, tt as workersYamlPath } from "./config-D5chi2LO.mjs";
-import "./config-BSXKyeJ1.mjs";
+import { $ as starterWorkersYamlText, B as WORKERS_YAML_FILENAME, G as inlineWorkersYamlKeys, H as defaultWorkersYamlPath, J as parseBuiltinAnthropic, K as migrateWorkersToYaml, Q as relocateWorkersYaml, U as effectiveWorkersYamlData, V as buildWorkersYamlText, W as initWorkersYaml, X as readMergeVerify, Y as parseWorkersYamlDocument, Z as readWorkersYaml, et as workersYamlLegacyNotice, it as yamlProviderToRaw, nt as writeWorkersYaml, q as needsWorkersYamlRelocation, rt as writeWorkersYamlText, tt as workersYamlPath } from "./config-XpZWOYOG.mjs";
+import "./config-Bu1_vbY8.mjs";
 
 export { workersYamlPath };

package/dist/{worktree-zmRf556h.mjs → worktree-CRs2gyg0.mjs}

@@ -1,8 +1,9 @@
-import { wt as appendLedger } from "./config-D5chi2LO.mjs";
-import { i as ledgerPath, l as statusPath } from "./paths-DoIyRnhx.mjs";
-import { a as UNLABELED, g as isLive, k as saveStatus, v as loadStatus, y as loadStatuses } from "./status-CvVi9cDf.mjs";
-import { t as fmtAge } from "./fmt-age-BiSHrTKN.mjs";
-import { v as readPoolState } from "./pool-CZ5MZaXg.mjs";
+import { t as writeFileAtomic } from "./atomic-file-BorMa4T3.mjs";
+import { wt as appendLedger } from "./config-XpZWOYOG.mjs";
+import { i as ledgerPath, l as statusPath } from "./paths-CHifubDh.mjs";
+import { a as UNLABELED, g as isLive, k as saveStatus, v as loadStatus, y as loadStatuses } from "./status-ggJ7lgVg.mjs";
+import { t as fmtAge } from "./fmt-age-ByDkvkoU.mjs";
+import { v as readPoolState } from "./pool-Dh-q3iJi.mjs";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { platform, tmpdir } from "node:os";
@@ -138,7 +139,7 @@ function invalidatePendingCache(logDir, repoRoot) {
 	}
 	if (!changed) return;
 	try {
-		writeFileSync(file, JSON.stringify(cache));
+		writeFileAtomic(file, JSON.stringify(cache));
 	} catch {}
 }
 
@@ -2148,6 +2149,24 @@ function leftoverWorktrees(logDir) {
 	}
 	return n;
 }
+/**
+* True only for a directory that is itself a git worktree: its toplevel is the directory
+* and its repository lists it. A leftover without .git (say, only node_modules) resolves
+* git to an enclosing repository, which must never be status'ed, stashed or archived.
+*/
+function isRealWorktree(dir) {
+	try {
+		const real = realpathSync(dir);
+		if (realpathSync(git(dir, ["rev-parse", "--show-toplevel"])) !== real) return false;
+		return git(dir, [
+			"worktree",
+			"list",
+			"--porcelain"
+		]).split("\n").some((l) => l.startsWith("worktree ") && realpathOr(l.slice(9)) === real);
+	} catch {
+		return false;
+	}
+}
 const GC_STAMP = "gc-last";
 /**
 * Pid of a live process whose cwd is `dir` or below (shell drivers parked in a
@@ -2470,6 +2489,10 @@ function gcWorktrees(logDir, olderThanHours = 24, dryRun = false, now = Date.now
 	const owned = new Set(statuses.map((s) => ownedTree(s)?.dir).filter((d) => !!d).map((d) => resolve(d)));
 	const archive = (id, dir, branch, st) => {
 		const target = `refs/pai-archive/${id}`;
+		if (!isRealWorktree(dir)) return void out.push({
+			id,
+			skipped: "not a worktree"
+		});
 		const pid = busyPid(dir);
 		if (pid) {
 			if (!dryRun) appendLedger(ledgerPath(logDir), "WORKER-GC-SKIP", {
@@ -2621,6 +2644,13 @@ function gcPoolWorktrees(logDir, dryRun = false) {
 	list(join(logDir, "slots"), () => true, (n) => `slot-${n}`);
 	for (const { id, dir } of cands) {
 		if (owned.has(resolve(dir))) continue;
+		if (!isRealWorktree(dir)) {
+			out.push({
+				id,
+				skipped: "not a worktree"
+			});
+			continue;
+		}
 		const pid = busyPid(dir);
 		if (pid) {
 			out.push({
@@ -2680,4 +2710,4 @@ function gcWorktreesThrottled(logDir, everyMin = 60, now = Date.now(), opts = {}
 
 //#endregion
 export { applyScratchEnv as A, worktreeWanted as C, formatPending as D, worktreesStatsCached as E, pendingGate as O, worktreeSystemPrompt as S, worktreesStats as T, ownedTree as _, archiveEmptyResult as a, verifyWorker as b, formatKnowledge as c, gcWorktrees as d, gcWorktreesThrottled as f, mergeWorker as g, markResumed as h, adoptTree as i, scratchPromptLine as j, pendingResults as k, formatWorktreesStats as l, leftoverWorktrees as m, MergeConflictError as n, commitLines as o, inPlaceSystemPrompt as p, addWorktree as r, discardWorker as s, GATE_MARK as t, gcPoolWorktrees as u, recordWorktree as v, worktreesDir as w, worktreeRefusesStart as x, salvageOnExit as y };
-//# sourceMappingURL=worktree-zmRf556h.mjs.map
+//# sourceMappingURL=worktree-CRs2gyg0.mjs.map

package/dist/{zettelkasten-nigq7fqs.mjs → zettelkasten-B_rRRRvD.mjs}

@@ -1,7 +1,7 @@
-import "./config-BSXKyeJ1.mjs";
-import "./embedding-gate-BHuBsgHD.mjs";
-import "./embeddings-D4t6L-EH.mjs";
-import { r as saveQueryResult } from "./query-feedback-I-txSnld.mjs";
-import { a as zettelThemes, c as zettelExplore, i as zettelHealth, n as zettelGodNotes, o as zettelConverse, r as zettelSuggest, s as zettelSurprise, t as zettelCommunities } from "./zettelkasten-Cr_Xj0mG.mjs";
+import "./config-Bu1_vbY8.mjs";
+import "./embedding-gate-6rZrWRXa.mjs";
+import "./embeddings-BVq3esBF.mjs";
+import { r as saveQueryResult } from "./query-feedback-BRfPtqki.mjs";
+import { a as zettelThemes, c as zettelExplore, i as zettelHealth, n as zettelGodNotes, o as zettelConverse, r as zettelSuggest, s as zettelSurprise, t as zettelCommunities } from "./zettelkasten-BzMm8REH.mjs";
 
 export { zettelConverse, zettelExplore, zettelHealth, zettelSuggest, zettelSurprise, zettelThemes };

package/dist/{zettelkasten-Cr_Xj0mG.mjs → zettelkasten-BzMm8REH.mjs}

@@ -1,6 +1,6 @@
-import { t as STOP_WORDS$1 } from "./stop-words-SdSL1WKH.mjs";
-import { a as requireQueryEmbedding } from "./embedding-gate-BHuBsgHD.mjs";
-import { i as deserializeEmbedding, r as cosineSimilarity } from "./embeddings-D4t6L-EH.mjs";
+import { t as STOP_WORDS$1 } from "./stop-words-DSEYQdNe.mjs";
+import { a as requireQueryEmbedding } from "./embedding-gate-6rZrWRXa.mjs";
+import { i as deserializeEmbedding, r as cosineSimilarity } from "./embeddings-BVq3esBF.mjs";
 import { basename, dirname } from "node:path";
 
 //#region src/zettelkasten/explore.ts
@@ -250,14 +250,24 @@ function extractDomain(vaultPath) {
 	const slash = vaultPath.indexOf("/");
 	return slash === -1 ? vaultPath : vaultPath.slice(0, slash);
 }
+/** Hard caps so a hub-heavy vault cannot fan out into thousands of queries. */
+const MAX_DEPTH = 3;
+const MAX_FRONTIER = 200;
+const LOOKUP_BATCH = 20;
+/** Map `items` through `fn`, at most LOOKUP_BATCH calls in flight at once. */
+async function mapInBatches(items, fn) {
+	const out = [];
+	for (let i = 0; i < items.length; i += LOOKUP_BATCH) out.push(...await Promise.all(items.slice(i, i + LOOKUP_BATCH).map(fn)));
+	return out;
+}
 /**
 * Expand one level of graph neighbors for a set of paths.
 * Returns all outbound and inbound neighbor paths (excluding already-visited).
 */
 async function expandNeighbors(backend, paths) {
 	if (paths.size === 0) return [];
-	const pathList = Array.from(paths);
-	const [forwardLinks, backwardLinks] = await Promise.all([backend.getVaultLinksFromPaths(pathList), Promise.all(pathList.map((p) => backend.getLinksToTarget(p)))]);
+	const pathList = Array.from(paths).slice(0, MAX_FRONTIER);
+	const [forwardLinks, backwardLinks] = await Promise.all([backend.getVaultLinksFromPaths(pathList), mapInBatches(pathList, (p) => backend.getLinksToTarget(p))]);
 	const neighbors = [];
 	for (const link of forwardLinks) if (link.targetPath) neighbors.push(link.targetPath);
 	for (const linkList of backwardLinks) for (const link of linkList) neighbors.push(link.sourcePath);
@@ -335,7 +345,7 @@ async function zettelConverse(backend, opts) {
 	}
 	const allPaths = new Set(searchHits.keys());
 	let frontier = new Set(searchHits.keys());
-	for (let d = 0; d < depth; d++) {
+	for (let d = 0; d < Math.min(depth, MAX_DEPTH); d++) {
 		const neighbors = await expandNeighbors(backend, frontier);
 		const newFrontier = /* @__PURE__ */ new Set();
 		for (const n of neighbors) if (!allPaths.has(n)) {
@@ -351,7 +361,7 @@ async function zettelConverse(backend, opts) {
 		isSearchResult: true
 	}));
 	const neighborPaths = Array.from(allPaths).filter((p) => !searchHits.has(p));
-	const neighborHealthRows = await Promise.all(neighborPaths.map((p) => backend.getVaultHealth(p)));
+	const neighborHealthRows = await mapInBatches(neighborPaths, (p) => backend.getVaultHealth(p));
 	const neighborRanked = neighborPaths.map((path, idx) => ({
 		path,
 		score: 0,
@@ -491,8 +501,9 @@ function averageEmbeddings(embeddings) {
 	return avg;
 }
 /**
-* Detect emerging themes in recently-modified notes using agglomerative single-linkage
-* clustering of note-level embeddings.
+* Detect emerging themes in recently-modified notes using agglomerative average-linkage
+* clustering of note-level embeddings: the closest pair of clusters (cosine similarity
+* of their centroids) is merged repeatedly while it stays above the threshold.
 */
 async function zettelThemes(backend, opts) {
 	const lookbackDays = opts.lookbackDays ?? 30;
@@ -989,12 +1000,8 @@ function louvainPhase1(graph, community, resolution) {
 	}
 	for (const [c, w] of communityInternalWeight) communityInternalWeight.set(c, w / 2);
 	let improved = false;
-	const shuffled = [...graph.nodes];
-	for (let i = shuffled.length - 1; i > 0; i--) {
-		const j = Math.floor(Math.random() * (i + 1));
-		[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
-	}
-	for (const node of shuffled) {
+	const ordered = [...graph.nodes].sort();
+	for (const node of ordered) {
 		const currentComm = community.get(node);
 		const ki = graph.degree.get(node) ?? 0;
 		const neighbors = graph.adj.get(node) ?? /* @__PURE__ */ new Map();
@@ -1156,7 +1163,6 @@ async function zettelCommunities(backend, opts) {
 	const titleMap = /* @__PURE__ */ new Map();
 	for (const f of allFiles) titleMap.set(f.vaultPath, f.title);
 	const communities = [];
-	let commId = 0;
 	for (const [, members] of groups) {
 		if (members.length < minSize) continue;
 		const memberSet = new Set(members);
@@ -1184,7 +1190,7 @@ async function zettelCommunities(backend, opts) {
 		}
 		const topFolders = [...folderCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([f]) => f);
 		communities.push({
-			id: commId++,
+			id: 0,
 			label,
 			nodes,
 			size: members.length,
@@ -1192,7 +1198,11 @@ async function zettelCommunities(backend, opts) {
 			topFolders
 		});
 	}
-	communities.sort((a, b) => b.size - a.size);
+	const minPath = (c) => c.nodes.map((n) => n.path).sort()[0];
+	communities.sort((a, b) => b.size - a.size || minPath(a).localeCompare(minPath(b)));
+	communities.forEach((c, i) => {
+		c.id = i;
+	});
 	return {
 		communities: communities.slice(0, maxCommunities),
 		totalNodes: graph.nodes.length,
@@ -1203,4 +1213,4 @@ async function zettelCommunities(backend, opts) {
 
 //#endregion
 export { zettelThemes as a, zettelExplore as c, zettelHealth as i, zettelGodNotes as n, zettelConverse as o, zettelSuggest as r, zettelSurprise as s, zettelCommunities as t };
-//# sourceMappingURL=zettelkasten-Cr_Xj0mG.mjs.map
+//# sourceMappingURL=zettelkasten-BzMm8REH.mjs.map

package/docs/README.md

@@ -1,5 +1,7 @@
 # PAI documentation
 
+**Start here: [everything PAI does](features.md)**: every capability by family, with the command or phrase to use.
+
 ## Words used in these docs
 
 - **PAI home**: the directory where PAI keeps its files (`config.yaml`, `workers.yaml`, keys, logs, state). It is `~/.pai`; installs from before the move use `~/.claude/pai` until `pai home migrate` is run. `pai home path` prints the one in use, `pai worker config path` prints the path of `workers.yaml`. Details: [PAI home](pai-home.md). Where a page writes `<PAI home>`, read this directory.

package/docs/cockpit.md

@@ -2,7 +2,7 @@
 
 The cockpit is one web page served by the [router](concepts/router.md). It answers four questions in one place: how full are my provider limits, where do delegated workers go and what are they doing, what are the local model servers and the machine doing, and where do my tokens and cache hits go. It is mostly read-only. The few controls it has start and stop local models and name them.
 
-![The cockpit's top: Limits and local servers with the local server tiles and the cloud provider gauges, then Routing with one line per delegation tier](images/cockpit-limits-routing.jpg)
+![Worker runs, speed per model, and Routing with one line per delegation tier](images/cockpit-06-runs-speed-routing.jpg)
 
 ## Open it
 
@@ -61,7 +61,7 @@ A runtime's note (`models.runtimes.<name>.note`) is the tooltip of the runtime c
 
 A card folds by clicking its header. By default a running coding runtime is open and the rest are folded.
 
-![Models: the local engine card with speed, memory, workers and conversation cache tiles and the local model switch, then one card per consumer on the shared runtimes](images/cockpit-models.jpg)
+![Local servers with their instances, the Models cards with start and stop per model, and the Worker pool](images/cockpit-03-local-servers-models-pool.jpg)
 
 ### Memory (`memory`)
 
@@ -76,7 +76,9 @@ Answers: is the machine under pressure. Metric tiles for memory, load, temperatu
 
 Tile grids never leave a partial last row: in wide mode the grid has 12 tracks, and when the last row is short its tiles widen to fill it, so there is no 3+1.
 
-![Workers and the worker pool, the Models cards, System tiles and Totals in this window](images/cockpit-workers-system.jpg)
+![Workers running and waiting, and the Memory section with backend, passes, embedding and index progress](images/cockpit-04-workers-memory.jpg)
+
+![System tiles for memory, load, temperature and power, the local model servers, and Tokens per bucket and per day per model](images/cockpit-01-system-tokens.jpg)
 
 ### Totals in this window (`kpis`)
 
@@ -90,7 +92,7 @@ Answers: when were tokens spent and of what kind. Stacked bars per time bucket i
 
 Answers: is the cache earning its keep. **Cache hit ratio** is `cache_read / (read + write + fresh input)`, one ring per provider and model; models under `lowRequestMin` requests are folded into a chip instead. A local server that reports no cache fields per request shows its own prefix-cache counter instead, marked `*` (it covers the time since that server started, so its window differs from the router log). **Providers** is one tile per provider; the tiles fill their row. Each has requests, tokens, average latency and time to first token.
 
-![Cache hit ratio and Providers, Tokens per day per model and Tokens per bucket by kind](images/cockpit-usage.jpg)
+![Totals in this window, Cache hit ratio per model, the local prefix cache and Providers](images/cockpit-02-totals-cache.jpg)
 
 ### Speed per model (`speed`)
 
@@ -104,6 +106,8 @@ Answers: did the cache expire between turns. Per model, hits grouped by the paus
 
 Answers: which sessions cost the most. The top `sessionsRows` sessions with models, requests, tokens, fresh input, output, hit percentage, cache busts, errors and last activity. A worker session carries its verdict.
 
+![Performance details: Cache verdict by pause and Sessions by tokens](images/cockpit-05-performance.jpg)
+
 ### Worker runs (`runs`)
 
 Answers: how did delegated workers end. The latest `workerRows` workers as label, verdict and tokens; the label takes two lines at most, with the provider and run id small beneath, and the full label is in the tooltip. The verdict is a short word and its full text is in the tooltip. Verdicts: **ok** and **done** in green, **report flagged** in amber (the worker finished but its report needs a look), **failed** in red; anything else is dim.
@@ -137,6 +141,8 @@ Nothing about your arrangement is sent to the server, so a different browser sta
 
 ## Configuration
 
+![Settings: the model registry (workers.yaml) in the editor with validate, save and duplicate, and its backups with diff, name, restore and delete](images/cockpit-07-settings-registry.jpg)
+
 ### Choosing sections
 
 `router.cockpit.sections` is a list of section ids; only those are shown, in that order. A single page load can override it:

package/docs/commands/README.md

@@ -24,7 +24,7 @@ Generated reference for every `pai` command. Read any page in the terminal with
 | [`pai home`](home.md) | Where PAI keeps its files; move them out of ~/.claude |
 | [`pai hooks-db`](hooks-db.md) | Registry updates for the stop and pre-compact hooks |
 | [`pai identity`](identity.md) | Say who you are, so mail to you can be told from mail to others |
-| [`pai install`](install.md) | First-time setup: storage, search, hooks, daemon |
+| [`pai install`](install.md) | First-time setup: storage, search, hooks, daemon, router |
 | [`pai issue`](issue.md) | Claim and release forge issues for this project |
 | [`pai kg`](kg.md) | Facts extracted from your notes, with the time they were true |
 | [`pai launch`](launch.md) | Start Claude Code on a chosen provider (for scripts) |
@@ -55,7 +55,7 @@ Generated reference for every `pai` command. Read any page in the terminal with
 | [`pai router`](router.md) | Local model router: start, stop, restart, status, run, stats |
 | [`pai session`](session.md) | Work with sessions: list, open, new, rename |
 | [`pai sessions`](sessions.md) | Old plural session commands (use `ls` and `session`) |
-| [`pai setup`](setup.md) | First-time setup: storage, search, hooks, daemon |
+| [`pai setup`](setup.md) | First-time setup: storage, search, hooks, daemon, router |
 | [`pai setups`](setups.md) | Orchestrator + worker combinations (save your own) |
 | [`pai shell-init`](shell-init.md) | Print the shell integration code |
 | [`pai skill`](skill.md) | How your skills are used |
@@ -137,7 +137,7 @@ Generated reference for every `pai` command. Read any page in the terminal with
 | `pai identity remove` | Stop treating an address as yours |
 | `pai identity set-delivery` | Choose where digests and "mail me" messages go |
 | `pai identity show` | Show your addresses and where mail is delivered |
-| `pai install` | First-time setup: storage, search, hooks, daemon |
+| `pai install` | First-time setup: storage, search, hooks, daemon, router |
 | `pai issue` | Claim and release forge issues for this project |
 | `pai issue claim` | Mark issue N as yours (assignee and in-progress label) |
 | `pai issue claims` | List the issues of this project marked in-progress |
@@ -326,7 +326,7 @@ Generated reference for every `pai` command. Read any page in the terminal with
 | `pai sessions route` | Link a session note to another project |
 | `pai sessions slug` | Suggest a short name for a session note from its transcript |
 | `pai sessions tag` | Show or set the tags of a session note |
-| `pai setup` | First-time setup: storage, search, hooks, daemon |
+| `pai setup` | First-time setup: storage, search, hooks, daemon, router |
 | `pai setups` | Orchestrator + worker combinations (save your own) |
 | `pai setups save` | Save the current combination under a name |
 | `pai shell-init` | Print the shell integration code |

package/docs/commands/backup.md

@@ -13,10 +13,12 @@ Copies the registry database and config into a dated folder under PAI_HOME/backu
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--no-postgres` | flag | — | Skip the Postgres dump (faster; registry and config only) |
+| `--dry-run` | flag | — | Print the database that would be dumped, write nothing |
 
 ```sh
 pai backup
 pai backup --no-postgres
+pai backup --dry-run
 ```
 
 See also: `pai restore`

package/docs/commands/install.md

@@ -2,25 +2,50 @@
 
 # pai install
 
-First-time setup: storage, search, hooks, daemon
+First-time setup: storage, search, hooks, daemon, router
 
 ```
 pai install [options]
 ```
 
-Walks through everything PAI needs: where data is stored, search embeddings, Claude Code hooks and settings, the background daemon and the first index.
-Safe to run again. With --yes it takes every default and asks nothing.
+Walks through everything PAI needs: where data is stored, search embeddings, Claude Code hooks and settings, the background daemon, the router and cockpit (port, reach), AIBroker (messaging; installed automatically) and the first index.
+Safe to run again. With --yes it takes every default and asks nothing; every question has a flag, so `pai setup --yes <flags>` can express any answer. `pai setup --questions [--json]` lists the questions with their flags, defaults and current values (for callers without a terminal).
 
 Shortcut for `pai setup`.
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `-y, --yes` | flag | — | Take every default and read no input |
+| `-y, --yes` | flag | — | Take every default (or the flag given) and read no input |
+| `--questions` | flag | — | Print every question with its flag, default and allowed values; change nothing |
+| `--json` | flag | — | With --questions: machine-readable JSON |
 | `--storage BACKEND` | string | — | Where to store data: sqlite or postgres (with --yes: sqlite unless a local Postgres answers) |
+| `--pg-url URL` | string | — | PostgreSQL connection string (implies --storage postgres) |
+| `--embedding MODEL` | string | — | Embeddings: snowflake, bge, nomic, ollama (Arctic on Ollama) or none |
+| `--da-name NAME` | string | — | What the assistant is called (default PAI) |
+| `--router` | flag | — | Enable the router and cockpit (default) |
+| `--no-router` | flag | — | Do not enable the router and cockpit |
+| `--router-port PORT` | number | — | Cockpit port (default: config router.port, 8790) |
+| `--router-bind SCOPE` | string | — | Who reaches the cockpit: loopback (default), tailscale or an IPv4 address |
+| `--no-aibroker` | flag | — | Do not install AIBroker (the messaging layer) |
+| `--no-claude-md` | flag | — | Skip: Write ~/.claude/CLAUDE.md from the PAI template? |
+| `--no-skill` | flag | — | Skip: Install the PAI skill? |
+| `--no-steering-rules` | flag | — | Skip: Install the AI steering rules? |
+| `--no-skill-stubs` | flag | — | Skip: Symlink the PAI skill stubs into ~/.claude/skills/? |
+| `--no-hooks` | flag | — | Skip: Install the lifecycle hooks (session stop, pre-compact, statusline)? |
+| `--no-ts-hooks` | flag | — | Skip: Install the TypeScript hooks to ~/.claude/Hooks/? |
+| `--no-settings` | flag | — | Skip: Patch ~/.claude/settings.json with PAI hooks, env vars and settings? |
+| `--no-daemon` | flag | — | Skip: Install the daemon as a login service? |
+| `--no-mcp` | flag | — | Skip: Register the PAI MCP server in ~/.claude.json? |
+| `--registry-scan` | flag | — | Do: Run `pai registry scan` after setup? |
+| `--task-bus` | flag | — | Do: Enable the task bus (needs a Todoist account)? |
+| `--no-workers` | flag | — | Skip: Turn workers on with the built-in anthropic provider? |
+| `--dry-run` | flag | — | Validate the flags, print the AIBroker install commands and change nothing (other steps are not previewed) |
 
 ```sh
 pai setup
 pai setup --yes --storage sqlite
+pai setup --questions --json
+pai setup --yes --storage sqlite --embedding none --router-port 9000 --router-bind tailscale --no-hooks
 ```
 
 See also: `pai update`, `pai daemon status`

package/docs/commands/providers.md

@@ -70,7 +70,7 @@ ChatGPT plan through the Codex CLI: --engine codex. Image generation: --engine i
 | `--base-url URL` | string | — | Anthropic-compatible API base URL (required unless --protocol openai) |
 | `--url URL` | string | — | Same as --base-url |
 | `--model ID` | string | — | Default model id for this provider (required) |
-| `--key TOKEN` | string | — | API token, written into workers.yaml; use instead of --key-file |
+| `--key TOKEN` | string | — | API token, written into workers.yaml; visible in ps and shell history, prefer --key-file |
 | `--key-file PATH` | string | — | File holding the API token (kept private); leave out for a local server |
 | `--fast-model ID` | string | — | Cheaper model for quick checks and routing |
 | `--env NAME=VALUE` | string | — | Extra environment variable for runs (repeat for several) |

package/docs/commands/restore.md

@@ -18,9 +18,13 @@ Overwrites the current registry, config and (unless skipped) the Postgres databa
 |---|---|---|---|
 | `--no-postgres` | flag | — | Do not restore the Postgres database |
 | `--yes` | flag | — | Do not ask for confirmation |
+| `--into DB` | string | — | Restore into this Postgres database instead of the daemon's (required when the backup came from another database) |
+| `--no-safety-dump` | flag | — | Do not dump the live database before replacing it (a failed safety dump otherwise aborts the restore) |
+| `--dry-run` | flag | — | Print the target and source databases, change nothing |
 
 ```sh
 pai restore
+pai restore --dry-run
 pai restore ~/.pai/backups/20260101-120000 --no-postgres --yes
 ```
 

package/docs/commands/setup.md

@@ -2,23 +2,48 @@
 
 # pai setup
 
-First-time setup: storage, search, hooks, daemon
+First-time setup: storage, search, hooks, daemon, router
 
 ```
 pai setup [options]
 ```
 
-Walks through everything PAI needs: where data is stored, search embeddings, Claude Code hooks and settings, the background daemon and the first index.
-Safe to run again. With --yes it takes every default and asks nothing.
+Walks through everything PAI needs: where data is stored, search embeddings, Claude Code hooks and settings, the background daemon, the router and cockpit (port, reach), AIBroker (messaging; installed automatically) and the first index.
+Safe to run again. With --yes it takes every default and asks nothing; every question has a flag, so `pai setup --yes <flags>` can express any answer. `pai setup --questions [--json]` lists the questions with their flags, defaults and current values (for callers without a terminal).
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `-y, --yes` | flag | — | Take every default and read no input |
+| `-y, --yes` | flag | — | Take every default (or the flag given) and read no input |
+| `--questions` | flag | — | Print every question with its flag, default and allowed values; change nothing |
+| `--json` | flag | — | With --questions: machine-readable JSON |
 | `--storage BACKEND` | string | — | Where to store data: sqlite or postgres (with --yes: sqlite unless a local Postgres answers) |
+| `--pg-url URL` | string | — | PostgreSQL connection string (implies --storage postgres) |
+| `--embedding MODEL` | string | — | Embeddings: snowflake, bge, nomic, ollama (Arctic on Ollama) or none |
+| `--da-name NAME` | string | — | What the assistant is called (default PAI) |
+| `--router` | flag | — | Enable the router and cockpit (default) |
+| `--no-router` | flag | — | Do not enable the router and cockpit |
+| `--router-port PORT` | number | — | Cockpit port (default: config router.port, 8790) |
+| `--router-bind SCOPE` | string | — | Who reaches the cockpit: loopback (default), tailscale or an IPv4 address |
+| `--no-aibroker` | flag | — | Do not install AIBroker (the messaging layer) |
+| `--no-claude-md` | flag | — | Skip: Write ~/.claude/CLAUDE.md from the PAI template? |
+| `--no-skill` | flag | — | Skip: Install the PAI skill? |
+| `--no-steering-rules` | flag | — | Skip: Install the AI steering rules? |
+| `--no-skill-stubs` | flag | — | Skip: Symlink the PAI skill stubs into ~/.claude/skills/? |
+| `--no-hooks` | flag | — | Skip: Install the lifecycle hooks (session stop, pre-compact, statusline)? |
+| `--no-ts-hooks` | flag | — | Skip: Install the TypeScript hooks to ~/.claude/Hooks/? |
+| `--no-settings` | flag | — | Skip: Patch ~/.claude/settings.json with PAI hooks, env vars and settings? |
+| `--no-daemon` | flag | — | Skip: Install the daemon as a login service? |
+| `--no-mcp` | flag | — | Skip: Register the PAI MCP server in ~/.claude.json? |
+| `--registry-scan` | flag | — | Do: Run `pai registry scan` after setup? |
+| `--task-bus` | flag | — | Do: Enable the task bus (needs a Todoist account)? |
+| `--no-workers` | flag | — | Skip: Turn workers on with the built-in anthropic provider? |
+| `--dry-run` | flag | — | Validate the flags, print the AIBroker install commands and change nothing (other steps are not previewed) |
 
 ```sh
 pai setup
 pai setup --yes --storage sqlite
+pai setup --questions --json
+pai setup --yes --storage sqlite --embedding none --router-port 9000 --router-bind tailscale --no-hooks
 ```
 
 See also: `pai update`, `pai daemon status`

package/docs/commands/worker.md

@@ -876,7 +876,7 @@ ChatGPT plan through the Codex CLI: --engine codex. Image generation: --engine i
 | `--base-url URL` | string | — | Anthropic-compatible API base URL (required unless --protocol openai) |
 | `--url URL` | string | — | Same as --base-url |
 | `--model ID` | string | — | Default model id for this provider (required) |
-| `--key TOKEN` | string | — | API token, written into workers.yaml; use instead of --key-file |
+| `--key TOKEN` | string | — | API token, written into workers.yaml; visible in ps and shell history, prefer --key-file |
 | `--key-file PATH` | string | — | File holding the API token (kept private); leave out for a local server |
 | `--fast-model ID` | string | — | Cheaper model for quick checks and routing |
 | `--env NAME=VALUE` | string | — | Extra environment variable for runs (repeat for several) |

package/docs/config.md

@@ -1,5 +1,7 @@
 # config.yaml
 
+The router and cockpit answers (`router.enabled`, `router.port`, `router.bind`) are asked by `pai setup`; the questions and their flags are listed in [Setup questions and flags](install/index.md#setup-questions-and-flags).
+
 The main PAI config: search defaults, storage backend, notifications, task bus, identity, the non-provider `workers` settings, the router and cockpit, plus whatever else a writer has stashed in the file. `pai config list|get|set|unset` and the matching `config_*` MCP tools read and change it whether the file is YAML or JSON; `pai config yaml` converts an old `config.json` to commented YAML; `pai config migrate` moves old per-user files into the PAI home.
 
 ## Shipped defaults and precedence