@iowarp/clio-coder 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.7",
+	"version": "0.4.9",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
@@ -57,7 +57,6 @@
 		".claude-plugin/marketplace.json",
 		"evals/**",
 		"docs/**/*.md",
-		"!docs/html/**",
 		"README.md",
 		"CHANGELOG.md",
 		"CONTRIBUTING.md",
@@ -72,8 +71,8 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "tsup && node --import tsx scripts/build-codewiki-asset.ts",
-		"dev": "tsup --watch",
+		"build": "node --import tsx scripts/build.ts && node --import tsx scripts/build-codewiki-asset.ts",
+		"dev": "node --import tsx scripts/build.ts --watch",
 		"clean": "rm -rf dist",
 		"typecheck": "tsc -p tsconfig.tests.json",
 		"format": "biome format --write .",
@@ -82,18 +81,21 @@
 		"pi:surface-snapshot": "node --import tsx scripts/pi-surface-diff.ts --write",
 		"test:file": "node --import tsx --import ./tests/harness/tmp-root.ts --test",
 		"pretest": "test -f dist/cli/index.js || pnpm run build",
-		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/smoke/*.test.ts",
-		"test:trace-viewer": "pnpm --filter @iowarp/clio-trace-viewer test",
-		"trace:ui": "node apps/trace-viewer/server.mjs",
-		"ci": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test && pnpm run test:trace-viewer",
-		"ci:release": "pnpm run ci && node scripts/check-release.mjs",
+		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test --test-concurrency=2 tests/contracts/*.test.ts tests/smoke/acp-boundary.test.ts tests/smoke/real-binary-boot.test.ts tests/smoke/process-lifecycle.test.ts",
+		"test:web": "pnpm --filter @iowarp/clio-coder-web test",
+		"ci": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test && pnpm run test:web",
+		"ci:release": "node scripts/release-candidate.mjs qualify",
 		"install:local": "bash scripts/install-local.sh",
 		"smoke:real-home": "bash scripts/smoke-real-home.sh",
-		"prepublishOnly": "CLIO_CODER_RELEASE_CONTEXT=publish pnpm run ci:release",
+		"prepublishOnly": "node scripts/release-candidate.mjs preflight",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
 		"library:pin": "node --import tsx scripts/pin-library.ts",
-		"library:check": "node --import tsx scripts/pin-library.ts --check"
+		"library:check": "node --import tsx scripts/pin-library.ts --check",
+		"test:full": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/extended/*.test.ts tests/smoke/*.test.ts tests/extended-smoke/*.test.ts",
+		"test:package": "node --import tsx --import ./tests/harness/tmp-root.ts --test --test-concurrency=2 tests/smoke/installed-package.test.ts tests/smoke/native-call-timing.test.ts",
+		"release:preflight": "node scripts/release-candidate.mjs preflight",
+		"test:web:full": "pnpm --filter @iowarp/clio-coder-web test:full"
 	},
 	"optionalDependencies": {
 		"@anthropic-ai/claude-agent-sdk": "0.3.186"

package/src/cli/argv.ts

@@ -8,6 +8,16 @@
  */
 
 import chalk from "chalk";
+import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+
+// A type-only import keeps this module out of the domain graph; `satisfies`
+// fails the build if the levels ever drift from the safety domain's list.
+const AUTONOMY_LEVELS = [
+	"read-only",
+	"suggest",
+	"auto-edit",
+	"full-auto",
+] as const satisfies ReadonlyArray<AutonomyLevel>;
 
 export function printError(message: string, detail?: string): void {
 	const head = chalk.red("error:");
@@ -75,6 +85,8 @@ export interface GlobalCliFlags {
 	 * both beat the `panes.enabled` setting; absent means the setting decides.
 	 */
 	panes?: "with" | "without";
+	/** `--autonomy <level>` before any subcommand: one interactive session at that level. */
+	autonomy?: AutonomyLevel;
 	rest: string[];
 	error?: string;
 }
@@ -136,6 +148,7 @@ export function extractGlobalFlags(
 	let noContextFiles = false;
 	let noSkills = false;
 	let panes: "with" | "without" | undefined;
+	let autonomy: AutonomyLevel | undefined;
 	const skillPaths: string[] = [];
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -174,6 +187,23 @@ export function extractGlobalFlags(
 			panes = arg === "--with-panes" ? "with" : "without";
 			continue;
 		}
+		if (arg === "--autonomy") {
+			const value = argv[i + 1];
+			if (value === undefined || !AUTONOMY_LEVELS.includes(value as AutonomyLevel)) {
+				return {
+					noContextFiles,
+					noSkills,
+					skillPaths,
+					rest,
+					error: `--autonomy must be one of: ${AUTONOMY_LEVELS.join("|")}`,
+					...(apiKey === undefined ? {} : { apiKey }),
+					...(panes === undefined ? {} : { panes }),
+				};
+			}
+			autonomy = value as AutonomyLevel;
+			i += 1;
+			continue;
+		}
 		if (arg === "--api-key" || arg === "--skill") {
 			const value = argv[i + 1];
 			if (value === undefined || value.startsWith("-") || isSubcommand(value)) {
@@ -209,5 +239,6 @@ export function extractGlobalFlags(
 		rest,
 		...(apiKey === undefined ? {} : { apiKey }),
 		...(panes === undefined ? {} : { panes }),
+		...(autonomy === undefined ? {} : { autonomy }),
 	};
 }

package/src/cli/clio.ts

@@ -13,7 +13,22 @@ function terminalLeaseEligible(
 	return !options.headless && !options.acp && env.CLIO_CODER_INTERACTIVE === "1";
 }
 
-export async function runClioCommand(options: BootOptions = {}): Promise<number> {
+export interface ClioCommandDependencies {
+	bootOrchestrator: typeof import("../entry/orchestrator.js").bootOrchestrator;
+}
+
+const DEFAULT_DEPENDENCIES: ClioCommandDependencies = {
+	bootOrchestrator: async (options) => {
+		const { bootOrchestrator } = await import("../entry/orchestrator.js");
+		return bootOrchestrator(options);
+	},
+};
+
+export async function runClioCommand(
+	options: BootOptions = {},
+	dependencies: Partial<ClioCommandDependencies> = {},
+): Promise<number> {
+	const deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
 	// Bare `clio` (no subcommand) boots interactive mode implicitly, but only
 	// when stdin is a real TTY. Piped or /dev/null stdin (used by verify.ts,
 	// CI runners, and non-interactive scripts) should fall through to the
@@ -69,18 +84,7 @@ export async function runClioCommand(options: BootOptions = {}): Promise<number>
 				}
 			}
 		}
-		// Deterministic built-PTY interleaving seam. It is unavailable outside
-		// NODE_ENV=test and bounded even under a malformed value.
-		if (terminalLease && process.env.NODE_ENV === "test") {
-			const requestedDelay = Number.parseInt(process.env.CLIO_CODER_TEST_STAGE1_DELAY_MS ?? "0", 10);
-			const delayMs = Number.isFinite(requestedDelay) ? Math.max(0, Math.min(5_000, requestedDelay)) : 0;
-			if (delayMs > 0) await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
-			if (process.env.CLIO_CODER_TEST_STAGE1_FAIL === "1") {
-				throw new Error("injected Stage 1 hydration failure");
-			}
-		}
-		const { bootOrchestrator } = await import("../entry/orchestrator.js");
-		const result = await bootOrchestrator({
+		const result = await deps.bootOrchestrator({
 			...options,
 			...(startupSettings ? { startupSettings } : {}),
 			...(terminalLease ? { terminalLease } : {}),

package/src/cli/config.ts

@@ -24,6 +24,10 @@ function renderText(cwd: string): string {
 
 	out.push("Settings (only keys a layer set; everything else is built-in):");
 	if (graph.settings.length === 0) out.push("  (none; all built-in defaults)");
+	// An ignored layer explains a value better than the value does. Left to the
+	// trailing Issues block, an untrusted project file read as a setting that
+	// silently failed to apply.
+	for (const issue of graph.issues) if (issue.startsWith("settings ")) out.push(`  ! ${issue}`);
 	for (const entry of graph.settings) {
 		out.push(`  ${entry.key} = ${JSON.stringify(entry.value)}  [${entry.source}]`);
 	}

package/src/cli/docs.ts

@@ -1,354 +1,91 @@
-import { spawn } from "node:child_process";
-import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import type { AddressInfo } from "node:net";
-import { relative, resolve } from "node:path";
-import chalk from "chalk";
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
 import { resolvePackageRoot } from "../core/package-root.js";
-import { printError, printHeader } from "./argv.js";
-
-// Human-facing viewer over the source-checkout HTML blueprints. It binds an ephemeral
-// static file server to 127.0.0.1 only, serves docs/html/index.html as the
-// menu plus the blueprint pages, prints the URL, and runs until SIGINT. It
-// uses only Node's built-in http and fs: zero new dependencies, no daemon, no
-// persisted state, no telemetry, and no external network. The static-path
-// resolution and the menu synthesis are pure functions so they unit-test
-// without binding a port.
-
-const HOST = "127.0.0.1";
+import { printError } from "./argv.js";
+import { runWebCommand } from "./web.js";
 
 const HELP = `clio-coder docs [topic] [--no-open]
 
-Serve Clio Coder's interactive HTML documentation locally and open it in a
-browser. The blueprints live in docs/html of a source checkout; the npm package
-ships the categorized Markdown reference tree under docs/ and excludes HTML.
-The server binds an ephemeral port on
-127.0.0.1, keeps no state, runs no daemon, and reaches no external network.
-Press Ctrl+C to stop it.
+Open the documentation in the Clio Coder web app. Pages, navigation and outlines
+are rendered from the same Markdown reference shipped with Clio.
 
 Arguments:
-  [topic]      deep-link a specific blueprint (for example: safety, configuration,
-               tools). Omit to open the documentation menu.
+  [topic]      a topic such as safety, configuration, or fleet_dispatch, or a
+               document path such as architecture/safety-model.md.
+               Omit to open the documentation map.
 
 Flags:
-  --no-open    do not launch a browser; just print the URL.
+  --no-open    print the private launch link without opening a browser.
   --help, -h   this message.
-`;
-
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-	".html": "text/html; charset=utf-8",
-	".htm": "text/html; charset=utf-8",
-	".css": "text/css; charset=utf-8",
-	".js": "text/javascript; charset=utf-8",
-	".mjs": "text/javascript; charset=utf-8",
-	".json": "application/json; charset=utf-8",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".webp": "image/webp",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".ico": "image/x-icon",
-	".woff": "font/woff",
-	".woff2": "font/woff2",
-	".ttf": "font/ttf",
-	".map": "application/json; charset=utf-8",
-	".txt": "text/plain; charset=utf-8",
-};
-
-export interface DocsMenuEntry {
-	/** Short deep-link key, for example `safety`. */
-	topic: string;
-	/** Real on-disk file name, for example `safety_blueprint.html`. */
-	file: string;
-	/** Human label, for example `Safety`. */
-	label: string;
-}
-
-/** Resolve the source-checkout HTML root. The npm package deliberately excludes it. */
-function resolveDocsHtmlDir(): string {
-	return resolve(resolvePackageRoot(), "docs", "html");
-}
 
-/** Content-type for a file path by extension. Pure. Defaults to octet-stream. */
-function contentTypeFor(filePath: string): string {
-	const dot = filePath.lastIndexOf(".");
-	if (dot === -1) return "application/octet-stream";
-	return CONTENT_TYPES[filePath.slice(dot).toLowerCase()] ?? "application/octet-stream";
-}
-
-/**
- * Map a request URL to a safe relative path under the html root. Pure: no disk
- * access. Strips the query and fragment, decodes percent-escapes, defaults `/`
- * to `index.html`, and rejects any traversal segment so a request can never
- * escape the served directory.
- */
-function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
-	const pathPart = (rawUrl.split(/[?#]/, 1)[0] ?? "").trim();
-	let decoded: string;
-	try {
-		decoded = decodeURIComponent(pathPart);
-	} catch {
-		return { ok: false, reason: "bad-request" };
-	}
-	if (decoded.includes("\0")) return { ok: false, reason: "forbidden" };
-	const segments = decoded.split(/[/\\]/).filter((segment) => segment.length > 0 && segment !== ".");
-	if (segments.length === 0) return { ok: true, relative: "index.html" };
-	for (const segment of segments) {
-		if (segment === "..") return { ok: false, reason: "forbidden" };
-	}
-	return { ok: true, relative: segments.join("/") };
-}
-
-function titleize(topic: string): string {
-	return topic
-		.split(/[-_]+/)
-		.filter((word) => word.length > 0)
-		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-		.join(" ");
-}
-
-/**
- * Synthesize the deep-linkable topic menu from a directory listing. Pure: takes
- * the file-name list, not the directory. `index.html` is the menu itself and is
- * excluded; a trailing `_blueprint` is stripped from the topic key.
- */
-function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
-	const entries: DocsMenuEntry[] = [];
-	for (const name of fileNames) {
-		if (!name.toLowerCase().endsWith(".html")) continue;
-		if (name.toLowerCase() === "index.html") continue;
-		const topic = name.replace(/\.html$/i, "").replace(/_blueprint$/i, "");
-		entries.push({ topic, file: name, label: titleize(topic) });
-	}
-	entries.sort((a, b) => a.topic.localeCompare(b.topic));
-	return entries;
-}
-
-/**
- * Resolve a user-supplied `[topic]` to a real file name. Pure. Accepts the bare
- * topic (`safety`), the blueprint file stem (`safety_blueprint`), or a full
- * `.html` name, case-insensitively. Returns null when nothing matches.
- */
-function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
-	const wanted = topic
-		.trim()
-		.toLowerCase()
-		.replace(/\.html$/i, "");
-	if (wanted.length === 0) return null;
-	for (const candidate of [`${wanted}.html`, `${wanted}_blueprint.html`]) {
-		const match = fileNames.find((name) => name.toLowerCase() === candidate);
-		if (match) return match;
-	}
-	const hit = synthesizeMenu(fileNames).find((entry) => entry.topic.toLowerCase() === wanted);
-	return hit ? hit.file : null;
-}
-
-function isWithin(child: string, parent: string): boolean {
-	const rel = relative(parent, child);
-	return rel === "" || (!rel.startsWith("..") && !rel.startsWith(`..${"/"}`) && !/^([A-Za-z]:)?[/\\]/.test(rel));
-}
-
-function listHtmlFiles(htmlDir: string): string[] {
-	try {
-		return readdirSync(htmlDir)
-			.filter((name) => name.toLowerCase().endsWith(".html"))
-			.sort((a, b) => a.localeCompare(b));
-	} catch {
-		return [];
-	}
-}
+Reuses your installed background app when available. Otherwise starts a local
+foreground web server on 127.0.0.1; press Ctrl+C to stop it. No background service
+is installed by this command. Your current directory does not affect the docs.
+`;
 
-/** Build the static request handler for one html root. */
-export function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
-	const root = realpathSync(resolve(htmlDir));
-	return (req, res) => {
-		if (req.method !== "GET" && req.method !== "HEAD") {
-			res.writeHead(405, { "content-type": "text/plain; charset=utf-8", allow: "GET, HEAD" });
-			res.end("method not allowed");
-			return;
-		}
-		const resolved = resolveRequestPath(req.url ?? "/");
-		if (!resolved.ok) {
-			const status = resolved.reason === "forbidden" ? 403 : 400;
-			res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
-			res.end(resolved.reason);
-			return;
-		}
-		const requestedTarget = resolve(root, resolved.relative);
-		if (!isWithin(requestedTarget, root)) {
-			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-			res.end("forbidden");
-			return;
-		}
-		let size: number | null = null;
-		let target: string | null = null;
-		try {
-			target = realpathSync(requestedTarget);
-			if (!isWithin(target, root)) {
-				res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-				res.end("forbidden");
-				return;
-			}
-			const stat = statSync(target);
-			if (stat.isFile()) size = stat.size;
-		} catch {
-			size = null;
-		}
-		if (size === null || target === null) {
-			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-			res.end("not found");
-			return;
-		}
-		const headers = {
-			"content-type": contentTypeFor(target),
-			"content-length": String(size),
-			"cache-control": "no-store",
-		};
-		if (req.method === "HEAD") {
-			res.writeHead(200, headers);
-			res.end();
-			return;
-		}
-		res.writeHead(200, headers);
-		const stream = createReadStream(target);
-		stream.on("error", () => {
-			if (!res.writableEnded) res.end();
-		});
-		stream.pipe(res);
+const key = (value: string) => value.toLowerCase().replace(/_/g, "-");
+const route = (path: string) => `/docs/${path.split("/").map(encodeURIComponent).join("/")}`;
+
+/** Resolve only catalogued destinations; ambiguous basenames require a full path. */
+export function docsTopicRoute(topic: string | undefined, pages: readonly string[]): string | undefined {
+	if (topic === undefined) return "/docs";
+	if (!topic || /[\\\0?#]/.test(topic) || topic.startsWith("/") || topic.split("/").includes("..")) return;
+	const wanted = key(topic.replace(/^docs\//, ""));
+	const topics: Record<string, string> = {
+		safety: "architecture/safety-model.md",
+		configuration: "guide/configuration-and-targets.md",
+		trace: "architecture/trace-store.md",
 	};
-}
-
-export interface DocsServerHandle {
-	server: Server;
-	url: string;
-	port: number;
-	close(): Promise<void>;
-}
-
-export interface StartDocsServerOptions {
-	htmlDir: string;
-	/** Bind host. Defaults to 127.0.0.1 and is never widened. */
-	host?: string;
-	/** Bind port. Defaults to 0 (ephemeral). */
-	port?: number;
-}
-
-/** Start the viewer bound to 127.0.0.1 on an ephemeral port. */
-async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
-	const host = options.host ?? HOST;
-	const server = createServer(createDocsRequestHandler(options.htmlDir));
-	await new Promise<void>((resolveListen, rejectListen) => {
-		const onError = (err: Error): void => rejectListen(err);
-		server.once("error", onError);
-		server.listen(options.port ?? 0, host, () => {
-			server.removeListener("error", onError);
-			resolveListen();
-		});
-	});
-	const address = server.address() as AddressInfo;
-	const port = address.port;
-	return {
-		server,
-		port,
-		url: `http://${host}:${port}/`,
-		close: () => new Promise<void>((resolveClose) => server.close(() => resolveClose())),
+	const preferred = topics[wanted];
+	if (preferred && pages.includes(preferred)) return route(preferred);
+	const exact = pages.find((path) => key(path) === wanted || key(path.replace(/\.md$/i, "")) === wanted);
+	if (exact) return route(exact);
+	const name = wanted.replace(/\.md$/, "");
+	const exactNames = pages.filter((path) => key(basename(path).replace(/\.md$/i, "")) === name);
+	const matches = exactNames.length
+		? exactNames
+		: pages.filter((path) => key(basename(path).replace(/\.md$/i, "")).startsWith(`${name}-`));
+	const match = matches[0];
+	return matches.length === 1 && match ? route(match) : undefined;
+}
+
+function catalog(root: string) {
+	const pages: string[] = [];
+	const scan = (path: string) => {
+		for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+			const name = path ? `${path}/${entry.name}` : entry.name;
+			if (name === "html") continue;
+			if (entry.isDirectory()) scan(name);
+			else if (entry.isFile() && /\.md$/i.test(name)) pages.push(name);
+		}
 	};
+	scan("");
+	return pages;
 }
 
-function openBrowser(url: string): void {
-	const platform = process.platform;
-	const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-	const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-	try {
-		const child = spawn(command, args, { stdio: "ignore", detached: true });
-		child.on("error", () => {
-			// Best-effort: the printed URL is the fallback when no opener exists.
-		});
-		child.unref();
-	} catch {
-		// Best-effort: never fail the command because a browser could not launch.
-	}
-}
-
-export function waitForShutdown(): Promise<void> {
-	return new Promise((resolveShutdown) => {
-		const onSignal = (): void => {
-			process.removeListener("SIGINT", onSignal);
-			process.removeListener("SIGTERM", onSignal);
-			resolveShutdown();
-		};
-		process.once("SIGINT", onSignal);
-		process.once("SIGTERM", onSignal);
-	});
-}
-
-export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<number> {
+export async function runDocsCommand(args: readonly string[] = []): Promise<number> {
 	if (args.includes("--help") || args.includes("-h")) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	let noOpen = false;
-	const positionals: string[] = [];
-	for (const arg of args) {
-		if (arg === "--no-open") {
-			noOpen = true;
-			continue;
-		}
-		if (arg.startsWith("-")) {
-			printError(`unknown flag: ${arg}`);
-			process.stdout.write(HELP);
-			return 2;
-		}
-		positionals.push(arg);
-	}
-	if (positionals.length > 1) {
-		printError("docs accepts at most one [topic]");
-		process.stdout.write(HELP);
+	const positionals = args.filter((arg) => arg !== "--no-open");
+	const unknownFlag = positionals.find((arg) => arg.startsWith("-"));
+	if (unknownFlag || positionals.length > 1) {
+		printError(unknownFlag ? `unknown flag: ${unknownFlag}` : "docs accepts at most one [topic]");
 		return 2;
 	}
-
-	let htmlDir: string;
 	try {
-		htmlDir = resolveDocsHtmlDir();
-	} catch (err) {
-		printError(`could not resolve the docs HTML root: ${err instanceof Error ? err.message : String(err)}`);
-		return 1;
-	}
-	const files = listHtmlFiles(htmlDir);
-	if (files.length === 0) {
-		printError(`no HTML docs at ${htmlDir}`);
-		process.stdout.write(
-			`  the npm package ships only the categorized Markdown reference tree: ${resolve(resolvePackageRoot(), "docs")}\n` +
-				"  the interactive blueprints are in a source checkout and at https://github.com/iowarp/clio-coder/tree/main/docs/html\n",
-		);
-		return 1;
-	}
-
-	let landing = "index.html";
-	const topic = positionals[0];
-	if (topic !== undefined) {
-		const file = topicToFile(topic, files);
-		if (!file) {
-			printError(`unknown docs topic: ${topic}`);
-			const topics = synthesizeMenu(files).map((entry) => entry.topic);
-			if (topics.length > 0) process.stdout.write(`  available topics: ${topics.join(", ")}\n`);
+		const pages = catalog(join(resolvePackageRoot(), "docs"));
+		const path = docsTopicRoute(positionals[0], pages);
+		if (!path) {
+			printError(
+				`Unknown or ambiguous docs topic: ${positionals[0]}. Run clio-coder docs to browse the documentation map.`,
+			);
 			return 2;
 		}
-		landing = file;
+		return runWebCommand(["--path", path, "--reuse-background", args.includes("--no-open") ? "--no-open" : "--open"]);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not open the documentation.");
+		return 1;
 	}
-
-	const handle = await startDocsServer({ htmlDir });
-	const landingUrl = landing === "index.html" ? handle.url : `${handle.url}${landing}`;
-	printHeader("Clio docs viewer");
-	process.stdout.write(`  serving HTML root ${htmlDir}\n`);
-	process.stdout.write(`  open ${chalk.cyan(landingUrl)}\n`);
-	process.stdout.write("  bound to 127.0.0.1 only: no external network, no daemon, no state.\n");
-	process.stdout.write("  press Ctrl+C to stop.\n");
-	if (!noOpen) openBrowser(landingUrl);
-
-	await waitForShutdown();
-	await handle.close();
-	process.stdout.write("docs viewer stopped.\n");
-	return 0;
 }

package/src/cli/doctor-panes.ts

@@ -11,7 +11,7 @@ import { describeResolution, findPinnedTool, toolStatus } from "../domains/toolc
  *
  * Six rows, in the order an operator debugs them: what mode the pane layer
  * resolved to, whether the socket answered, whether the server is new enough
- * for the methods phase 3 uses, where the pane host binary resolves, what the
+ * for the notification and pane-control methods, where the pane host binary resolves, what the
  * boot layout composes, and whether the journal directory the viewer reads is
  * writable.
  *

package/src/cli/doctor.ts

@@ -20,6 +20,8 @@ const HELP = `clio-coder doctor [--fix] [--json]
 Diagnose Clio Coder state without creating files. On a home Clio has never
 written to, doctor says so in one row and exits 0. Use --fix to repair structure:
 missing directories, missing template files, and credential permissions.
+--fix also records the fleet preflight, which is what admits an SSH node to
+dispatch for the current project root; plain doctor only reports it.
 Settings are validated directly against the current schema.
 Pass --json to emit a machine-readable report on stdout.
 `;
@@ -63,7 +65,7 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	const interopChecks = untouched ? [] : await runDoctorInteropChecks();
 	// Fleet preflight probes each configured node over SSH and persists the
 	// per-node eligibility verdicts dispatch placement enforces.
-	const fleetChecks = untouched ? [] : await runDoctorFleetChecks();
+	const fleetChecks = untouched ? [] : await runDoctorFleetChecks(process.cwd(), { fix });
 	// Resolution reads PATH and the vendor root and creates nothing, but on an
 	// untouched home there is no vendor root to look at and the answer would be
 	// "none" for every row regardless, so the sweep stays with the others.