@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/cli/configure.ts

@@ -1,40 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import {
+	bindAgentProfileInSettings,
 	type ClioSettings,
 	readSettings,
 	removeTargetFromSettings,
 	settingsPath,
 	updateSettings,
 } from "../core/config.js";
+import {
+	type AutonomyLevel,
+	type OutputVerbosity,
+	type PanesSettings,
+	type SmoothStreaming,
+	THINKING_LEVELS,
+	type ThinkingLevel,
+	type TuiMode,
+	type WorkerPermissionMode,
+} from "../core/defaults.js";
 import { initializeClioHome } from "../core/init.js";
-import { openAuthStorage, resolveAuthTarget, targetRequiresAuth } from "../domains/providers/auth/index.js";
-import { getCatalogModelForRuntime } from "../domains/providers/catalog.js";
-import { credentialsPresent } from "../domains/providers/credentials.js";
+import { resolveClioDirs } from "../core/xdg.js";
+import { getVersionInfo } from "../domains/lifecycle/version.js";
+import { openAuthStorage, targetRequiresAuth } from "../domains/providers/auth/index.js";
 import {
 	buildProviderSupportEntry,
 	configuredTargetsForRuntime,
 	describeRuntimeModels,
 	isOrchestratorEligibleRuntime,
-	listKnownModelsForRuntime,
 	listProviderSupportEntries,
 	type ProviderSupportEntry,
-	readTargetModelSnapshot,
 	recordTargetModelSnapshot,
 	resolveRuntimeAuthTarget,
 	supportGroupLabel,
 } from "../domains/providers/index.js";
-import { probeCapabilitiesForModel } from "../domains/providers/model-capabilities.js";
 import { fingerprintNativeRuntime } from "../domains/providers/probe/fingerprint.js";
 import { getRuntimeRegistry } from "../domains/providers/registry.js";
 import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.js";
 import { greetLmStudio } from "../domains/providers/runtimes/common/lmstudio-http.js";
-import type {
-	ProbeContext,
-	ProbeModelStatus,
-	ProbeResult,
-	RuntimeDescriptor,
-} from "../domains/providers/types/runtime-descriptor.js";
+import type { ProbeResult, RuntimeDescriptor } from "../domains/providers/types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../domains/providers/types/target-descriptor.js";
 import { registerClioOAuthProviders } from "../engine/oauth.js";
 import { ask, askYesNo } from "./ask.js";
@@ -47,22 +51,57 @@ import {
 	matchCategoryChoice,
 	type RuntimeListRow,
 } from "./configure-layout.js";
-import { createDelayedManualCodeInput } from "./oauth-manual-input.js";
-import { promptOAuthSelection } from "./oauth-select.js";
+import { loginOAuthRuntime } from "./configure-oauth.js";
+import { canRunOnboarding, runOnboardingWizard } from "./configure-onboarding.js";
+import {
+	applyTarget,
+	assertOrchestratorReplacementEligible,
+	buildDescriptor,
+	defaultUrlFor,
+	deriveTargetId,
+	describeAuthStatus,
+	normalizeUrl,
+	PROTOCOL_COMPAT_RUNTIME_IDS,
+	probeLines,
+	railPrefix,
+	resolveSupportedWireModels,
+	runtimeProbe,
+	runtimesForCategory,
+	setBackgroundPointer,
+	setOrchestratorPointer,
+	setWorkerDefaultPointer,
+	setWorkerProfilePointer,
+	validateContextWindowOverride,
+	validateResolvedModel,
+	type WireModelInventory,
+	warnUndiscoveredContextWindow,
+} from "./configure-target.js";
+import { createLifecyclePresenter, type LifecyclePresenter, shortenPath } from "./lifecycle-presenter.js";
+import { canSelect, promptSelect } from "./select.js";
 import { credentialWriteFailed, printError, printOk, printPlaintextCredentialWarning } from "./shared.js";
 import { terminalColumns, wrapPlain } from "./text-layout.js";
-import { type LiveModelInventory, validateModelChoice } from "./validate-model.js";
 
 const HELP = `clio-coder configure
 
-Configure model targets for chat and fleet-agent dispatch.
+Configure model targets and runtime settings for chat and fleet dispatch.
 
 Usage:
-  clio-coder configure                   interactive wizard
+  clio-coder configure                   interactive configuration wizard
+  clio-coder configure --section <name>  open one section directly:
+                                         targets, models, chat, fleet,
+                                         permissions, panes, skills, diagnostics
+                                         Without a terminal this prints the
+                                         section's values and exits.
+  clio-coder configure --json            emit the effective settings as JSON
   clio-coder configure --interop         review detected coding agents as delegation peers
   clio-coder configure --list            list target runtimes (user-facing only)
   clio-coder configure --list --all      list every registered runtime including aliases
   clio-coder configure --id <targetId> [flags] --runtime <runtimeId>
+  clio-coder configure --help, -h        show this message
+
+In the interactive menus: arrow keys move, enter opens, escape goes back, q
+quits. Where the terminal cannot support that, the same menus are numbered and
+answered by typing a number, b for back, or q to quit.
 
 Non-interactive flags:
   --id <targetId>                  target id to register (required when non-interactive)
@@ -75,6 +114,7 @@ Non-interactive flags:
                                    (mutually exclusive with --agent-profile)
   --agent-profile <name>           save this target as a named fleet profile
   --agent-profile-model <id>       model to use for --agent-profile
+  --bind-agent <agentId>           bind this --agent-profile to an agent
   --api-key-env <VAR>              read API key from this env var at call time
   --api-key <literal>              store API key in credentials.yaml
   --force                          save a model outside the runtime catalog, or one the
@@ -90,30 +130,14 @@ Non-interactive flags:
   --reasoning <true|false>         capability override
 `;
 
-const DEFAULT_PORTS: Record<string, number> = {
-	llamacpp: 8080,
-	"llamacpp-anthropic": 8080,
-	"llamacpp-completion": 8080,
-	"llamacpp-embed": 8080,
-	"llamacpp-rerank": 8080,
-	"lmstudio-native": 1234,
-	lmstudio: 1234,
-	"ollama-native": 11434,
-	vllm: 8000,
-	sglang: 30000,
-	"lemonade-anthropic": 8000,
-	lemonade: 8000,
-	"anthropic-compat": 8000,
-	"openai-compat": 8000,
-	litellm: 4000,
-};
-
 interface ParsedArgs {
 	positional: string[];
 	help: boolean;
 	list: boolean;
 	all: boolean;
 	interop: boolean;
+	json: boolean;
+	section?: string;
 	remove?: string;
 	renameOld?: string;
 	renameNew?: string;
@@ -126,6 +150,7 @@ interface ParsedArgs {
 	workerModel?: string;
 	workerProfile?: string;
 	workerProfileModel?: string;
+	bindAgent?: string;
 	apiKeyEnv?: string;
 	apiKey?: string;
 	force: boolean;
@@ -146,6 +171,7 @@ function parseSetupArgs(argv: ReadonlyArray<string>): ParsedArgs {
 		list: false,
 		all: false,
 		interop: false,
+		json: false,
 		force: false,
 		gateway: false,
 		setOrchestrator: false,
@@ -165,6 +191,12 @@ function parseSetupArgs(argv: ReadonlyArray<string>): ParsedArgs {
 			case "-h":
 				out.help = true;
 				break;
+			case "--json":
+				out.json = true;
+				break;
+			case "--section":
+				out.section = need();
+				break;
 			case "--list":
 				out.list = true;
 				break;
@@ -208,6 +240,9 @@ function parseSetupArgs(argv: ReadonlyArray<string>): ParsedArgs {
 			case "--agent-profile-model":
 				out.workerProfileModel = need();
 				break;
+			case "--bind-agent":
+				out.bindAgent = need();
+				break;
 			case "--api-key-env":
 				out.apiKeyEnv = need();
 				break;
@@ -269,32 +304,6 @@ function ensureRegistryPopulated(): void {
 	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
 }
 
-function trimTrailing(url: string): string {
-	return url.endsWith("/") && url.length > 1 ? url.slice(0, -1) : url;
-}
-
-function normalizeUrl(input: string, runtimeId: string): string {
-	const trimmed = input.trim();
-	if (trimmed.length === 0) return defaultUrlFor(runtimeId);
-	const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
-	let withScheme = hasScheme ? trimmed : `http://${trimmed}`;
-	if (runtimeId === "lmstudio") withScheme = withScheme.replace(/^ws:/u, "http:").replace(/^wss:/u, "https:");
-	try {
-		const parsed = new URL(withScheme);
-		if (!hasScheme && !parsed.port && DEFAULT_PORTS[runtimeId]) {
-			parsed.port = String(DEFAULT_PORTS[runtimeId]);
-		}
-		return trimTrailing(parsed.toString());
-	} catch {
-		return trimTrailing(withScheme);
-	}
-}
-
-function defaultUrlFor(runtimeId: string): string {
-	const port = DEFAULT_PORTS[runtimeId];
-	return port ? `http://127.0.0.1:${port}` : "http://127.0.0.1:8080";
-}
-
 const RUNTIME_LIST_CAPTION =
 	"every registered runtime. run `clio-coder auth list` for the ones clio authenticates itself; the rest authenticate through their own tool (claude-cli, aws-sdk) or need no credential.";
 
@@ -342,256 +351,6 @@ function printRuntimeList(includeHidden: boolean): void {
 	}
 }
 
-function deriveTargetId(runtimeId: string, existing: ReadonlyArray<TargetDescriptor>): string {
-	const base = runtimeId;
-	const taken = new Set(existing.map((e) => e.id));
-	if (!taken.has(base)) return base;
-	for (let i = 2; i < 1000; i++) {
-		const candidate = `${base}-${i}`;
-		if (!taken.has(candidate)) return candidate;
-	}
-	return `${base}-${Date.now()}`;
-}
-
-async function buildProbeContext(runtime?: RuntimeDescriptor, target?: TargetDescriptor): Promise<ProbeContext> {
-	const probeCtx: ProbeContext = {
-		credentialsPresent: credentialsPresent(),
-		httpTimeoutMs: 5000,
-	};
-	if (!runtime || !target || !targetRequiresAuth(target, runtime)) return probeCtx;
-	try {
-		const resolution = await openAuthStorage().resolveForTarget(resolveAuthTarget(target, runtime), {
-			includeFallback: false,
-		});
-		if (resolution.apiKey) probeCtx.authToken = resolution.apiKey;
-	} catch {
-		// Let the runtime's probe report its own missing-auth diagnostic.
-	}
-	return probeCtx;
-}
-
-function runtimeKnownModelsFor(runtimeId: string): ReadonlyArray<string> {
-	return listKnownModelsForRuntime(runtimeId);
-}
-
-function catalogContextWindowFor(runtime: RuntimeDescriptor, modelId: string): number | null {
-	const catalogModel = getCatalogModelForRuntime(runtime.id, modelId);
-	if (typeof catalogModel?.contextWindow === "number" && catalogModel.contextWindow > 0) {
-		return catalogModel.contextWindow;
-	}
-	if (runtimeKnownModelsFor(runtime.id).includes(modelId) && runtime.defaultCapabilities.contextWindow > 0) {
-		return runtime.defaultCapabilities.contextWindow;
-	}
-	return null;
-}
-
-/**
- * Check the resolved model against the catalog where there is one and against
- * the target's own list where there is not. A runtime with no catalog used to
- * pass any string here while the same command had a live list that ruled it
- * out, so the target saved as `ok` and failed on its first
- * turn. Without a catalog or a live list there is nothing to check against, and
- * the note says so rather than implying the id was verified.
- */
-function validateResolvedModel(
-	runtime: RuntimeDescriptor,
-	target: Pick<TargetDescriptor, "id" | "url">,
-	modelId: string | undefined,
-	force: boolean,
-	inventory: WireModelInventory,
-): boolean {
-	if (!modelId) return true;
-	const knownModels = runtimeKnownModelsFor(runtime.id);
-	const live = inventory.source === "probe" ? liveInventoryFor(target, inventory) : undefined;
-	const validation = validateModelChoice({ runtimeId: runtime.id, modelId, knownModels, live, force });
-	if (!validation.ok) {
-		process.stderr.write(`error: ${validation.reason}\n`);
-		return false;
-	}
-	if (validation.warning) process.stderr.write(`warning: ${validation.warning}\n`);
-	if (knownModels.length === 0 && live === undefined && runtime.kind === "http") {
-		process.stderr.write(
-			`warning: could not verify model '${modelId}': ${target.url ?? `target '${target.id}'`} returned no model list; it is saved as written\n`,
-		);
-	}
-	return true;
-}
-
-function validateContextWindowOverride(
-	runtime: RuntimeDescriptor,
-	modelId: string | undefined,
-	contextWindow: number | undefined,
-	force: boolean,
-): boolean {
-	if (contextWindow === undefined || !modelId) return true;
-	const catalogMax = catalogContextWindowFor(runtime, modelId);
-	if (catalogMax === null || contextWindow <= catalogMax) return true;
-	const message = `--context-window ${contextWindow} exceeds catalog max ${catalogMax} for model '${modelId}'`;
-	if (!force) {
-		process.stderr.write(`error: ${message}. Use --force to override.\n`);
-		return false;
-	}
-	process.stderr.write(`warning: ${message}\n`);
-	return true;
-}
-
-async function runtimeProbe(
-	runtime: RuntimeDescriptor,
-	target: TargetDescriptor,
-	authToken?: string,
-): Promise<ProbeResult | null> {
-	if (typeof runtime.probe !== "function") return null;
-	try {
-		const context = await buildProbeContext(runtime, target);
-		return await runtime.probe(target, authToken === undefined ? context : { ...context, authToken });
-	} catch (err) {
-		return { ok: false, error: err instanceof Error ? err.message : String(err) };
-	}
-}
-
-async function runtimeProbeModels(
-	runtime: RuntimeDescriptor,
-	target: TargetDescriptor,
-	authToken?: string,
-): Promise<string[]> {
-	if (typeof runtime.probeModels !== "function") return [];
-	try {
-		const context = await buildProbeContext(runtime, target);
-		return await runtime.probeModels(target, authToken === undefined ? context : { ...context, authToken });
-	} catch {
-		return [];
-	}
-}
-
-function applyTarget(settings: ClioSettings, descriptor: TargetDescriptor): void {
-	const idx = settings.targets.findIndex((e) => e.id === descriptor.id);
-	if (idx >= 0) settings.targets[idx] = descriptor;
-	else settings.targets.push(descriptor);
-}
-
-function setOrchestratorPointer(settings: ClioSettings, descriptor: TargetDescriptor, model?: string | null): void {
-	const runtime = getRuntimeRegistry().get(descriptor.runtime);
-	if (!runtime) {
-		throw new Error(
-			`cannot use target '${descriptor.id}' as orchestrator target because runtime '${descriptor.runtime}' is not registered`,
-		);
-	}
-	if (!isOrchestratorEligibleRuntime(runtime)) {
-		throw new Error(
-			`cannot use target '${descriptor.id}' as orchestrator target because runtime '${runtime.id}' is not an HTTP/native runtime`,
-		);
-	}
-	settings.chat.target = descriptor.id;
-	settings.chat.model = model ?? descriptor.defaultModel ?? null;
-}
-
-function setWorkerDefaultPointer(settings: ClioSettings, descriptor: TargetDescriptor, model?: string | null): void {
-	settings.fleet.default.target = descriptor.id;
-	settings.fleet.default.model = model ?? descriptor.defaultModel ?? null;
-}
-
-function setBackgroundPointer(settings: ClioSettings, descriptor: TargetDescriptor, model?: string | null): void {
-	const runtime = getRuntimeRegistry().get(descriptor.runtime);
-	if (!runtime || !isOrchestratorEligibleRuntime(runtime)) {
-		throw new Error(
-			`cannot use target '${descriptor.id}' as background target because runtime '${descriptor.runtime}' is not an HTTP/native runtime`,
-		);
-	}
-	settings.context.memory.target = descriptor.id;
-	settings.context.memory.model = model ?? descriptor.defaultModel ?? null;
-}
-
-function assertOrchestratorReplacementEligible(settings: ClioSettings, descriptor: TargetDescriptor): void {
-	if (settings.chat.target !== descriptor.id && settings.context.memory.target !== descriptor.id) return;
-	const role = settings.chat.target === descriptor.id ? "orchestrator" : "background";
-	const runtime = getRuntimeRegistry().get(descriptor.runtime);
-	if (!runtime) {
-		throw new Error(
-			`cannot update ${role} target '${descriptor.id}' because runtime '${descriptor.runtime}' is not registered`,
-		);
-	}
-	if (!isOrchestratorEligibleRuntime(runtime)) {
-		throw new Error(`cannot update ${role} target '${descriptor.id}' to non-HTTP/native runtime '${runtime.id}'`);
-	}
-}
-
-function setWorkerProfilePointer(
-	settings: ClioSettings,
-	name: string,
-	descriptor: TargetDescriptor,
-	model?: string | null,
-): void {
-	const trimmed = name.trim();
-	if (trimmed.length === 0) throw new Error("fleet profile name must be non-empty");
-	settings.fleet.profiles[trimmed] = {
-		target: descriptor.id,
-		model: model ?? descriptor.defaultModel ?? null,
-		thinkingLevel: "off",
-	};
-}
-
-/**
- * A target that was probed successfully and still reported no context window
- * will run against the runtime descriptor's placeholder. Say so at the moment
- * the target is written, because the alternative is a plausible-looking number
- * the operator never chose and the server never claimed.
- */
-function warnUndiscoveredContextWindow(descriptor: TargetDescriptor, probe: ProbeResult | null): void {
-	if (!probe?.ok) return;
-	if (typeof descriptor.capabilities?.contextWindow === "number" && descriptor.capabilities.contextWindow > 0) return;
-	const discovered = probeCapabilitiesForModel(
-		{
-			target: descriptor,
-			probeCapabilities: probe.discoveredCapabilities ?? null,
-			probeModelCapabilities: probe.modelCapabilities ?? null,
-			probeModelId: probe.capabilityModelId ?? null,
-		},
-		descriptor.defaultModel,
-	);
-	if (typeof discovered?.contextWindow === "number" && discovered.contextWindow > 0) return;
-	process.stdout.write(
-		"  warning: the target reported no context window; Clio will use the runtime default as a guess. Set one with --context-window.\n",
-	);
-}
-
-/**
- * What the probe read, as opposed to whether it connected.
- *
- * A health check can pass while every enrichment read behind it returns
- * nothing, and reporting that as `probe ok` makes it indistinguishable from a
- * full read. That is how a target gets blessed at configure time and then
- * fails on the first turn. Naming the gap is the difference between a user who
- * knows to look now and one who finds out from a raw 404 later.
- */
-function probeReadings(probe: ProbeResult): string[] {
-	const readings: string[] = [];
-	if (probe.models && probe.models.length > 0) readings.push(`${probe.models.length} models`);
-	if (probe.serverVersion) readings.push(probe.serverVersion);
-	if (probe.discoveredCapabilities && Object.keys(probe.discoveredCapabilities).length > 0) {
-		readings.push("capabilities");
-	}
-	return readings;
-}
-
-/** The probe result as the lines a user reads, cause and next step included. */
-function probeLines(descriptor: TargetDescriptor, probe: ProbeResult): string[] {
-	const latency = probe.latencyMs !== undefined ? ` (${probe.latencyMs}ms)` : "";
-	if (!probe.ok) {
-		const where = descriptor.url ? ` ${descriptor.url}` : "";
-		return [
-			`probe failed${latency}:${where} ${probe.error ?? "unknown"}`,
-			`  check the server is running and reachable, then re-run: clio-coder configure --id ${descriptor.id} --url <url>`,
-		];
-	}
-	const readings = probeReadings(probe);
-	if (readings.length > 0) return [`probe ok${latency} ${readings.join(", ")}`];
-	return [
-		`probe reachable${latency}, but the target answered no model list and no version`,
-		"  Clio cannot verify the model id or the context window from here and will send both as written.",
-		"  re-read them once the server serves them with: clio-coder targets --probe",
-	];
-}
-
 function printSummary(settings: ClioSettings, descriptor: TargetDescriptor, probe: ProbeResult | null): void {
 	process.stdout.write(`\nsaved target ${descriptor.id} (runtime=${descriptor.runtime})\n`);
 	if (descriptor.url) process.stdout.write(`  url        ${descriptor.url}\n`);
@@ -612,166 +371,6 @@ function printSummary(settings: ClioSettings, descriptor: TargetDescriptor, prob
 	process.stdout.write(`\nsettings written to ${settingsPath()}\n`);
 }
 
-function buildDescriptor(
-	runtime: RuntimeDescriptor,
-	id: string,
-	parts: {
-		url?: string;
-		model?: string;
-		apiKeyEnv?: string;
-		apiKeyRef?: string;
-		oauthProfile?: string;
-		gateway?: boolean;
-		lifecycle?: TargetDescriptor["lifecycle"];
-		contextWindow?: number;
-		maxTokens?: number;
-		reasoning?: boolean;
-		lmstudio?: TargetDescriptor["lmstudio"];
-	},
-): TargetDescriptor {
-	const descriptor: TargetDescriptor = { id, runtime: runtime.id };
-	if (parts.url) descriptor.url = parts.url;
-	if (parts.model) descriptor.defaultModel = parts.model;
-	const auth: NonNullable<TargetDescriptor["auth"]> = {};
-	if (parts.apiKeyEnv) auth.apiKeyEnvVar = parts.apiKeyEnv;
-	if (parts.apiKeyRef) auth.apiKeyRef = parts.apiKeyRef;
-	if (parts.oauthProfile) auth.oauthProfile = parts.oauthProfile;
-	if (Object.keys(auth).length > 0) descriptor.auth = auth;
-	if (parts.gateway) descriptor.gateway = true;
-	if (parts.lifecycle) descriptor.lifecycle = parts.lifecycle;
-	const caps: NonNullable<TargetDescriptor["capabilities"]> = {};
-	if (parts.contextWindow !== undefined) caps.contextWindow = parts.contextWindow;
-	if (parts.maxTokens !== undefined) caps.maxTokens = parts.maxTokens;
-	if (parts.reasoning !== undefined) caps.reasoning = parts.reasoning;
-	if (Object.keys(caps).length > 0) descriptor.capabilities = caps;
-	if (parts.lmstudio) descriptor.lmstudio = parts.lmstudio;
-	return descriptor;
-}
-
-function describeAuthStatus(runtime: RuntimeDescriptor): string {
-	const status = openAuthStorage().statusForTarget(resolveRuntimeAuthTarget(runtime), { includeFallback: false });
-	// This describes a credential, not a network state. It is printed before the
-	// wizard has asked for a URL, so `not connected` read as a connection that
-	// had already been tried and failed.
-	if (!status.available) return "none stored";
-	if (status.source === "environment") return `environment${status.detail ? ` (${status.detail})` : ""}`;
-	if (status.source === "stored-api-key") return "stored api key";
-	if (status.source === "stored-oauth") return "stored oauth";
-	return status.source;
-}
-
-async function loginOAuthRuntime(rl: ReturnType<typeof createInterface>, runtime: RuntimeDescriptor): Promise<boolean> {
-	const auth = openAuthStorage();
-	if (runtime.authNotice) process.stdout.write(`note: ${runtime.authNotice}\n`);
-	const manualCodeInput = createDelayedManualCodeInput(
-		rl,
-		"Paste verification code if browser callback does not complete automatically: ",
-	);
-	try {
-		await auth.login(runtime.oauthProviderId ?? runtime.id, {
-			onAuth: ({ url, instructions }) => {
-				process.stdout.write(`\nOpen: ${url}\n`);
-				if (instructions) process.stdout.write(`${instructions}\n`);
-				process.stdout.write("Waiting for the browser callback. A manual code prompt will appear if needed.\n");
-			},
-			onDeviceCode: ({ verificationUri, userCode }) => {
-				process.stdout.write(`\nOpen: ${verificationUri}\n`);
-				process.stdout.write(`Enter code: ${userCode}\n`);
-			},
-			onPrompt: async (prompt) => {
-				const answer = await rl.question(`${prompt.message}${prompt.allowEmpty ? " " : ": "}`);
-				return prompt.allowEmpty ? answer : answer.trim();
-			},
-			onSelect: (prompt) => promptOAuthSelection(rl, prompt),
-			onManualCodeInput: manualCodeInput.onManualCodeInput,
-			onProgress: (message) => {
-				process.stderr.write(`${message}\n`);
-			},
-		});
-		if (credentialWriteFailed(auth, `credential for ${runtime.id} was not stored`)) return false;
-		printOk(`authenticated ${runtime.id}`);
-		return true;
-	} catch (error) {
-		printError(error instanceof Error ? error.message : String(error));
-		return false;
-	} finally {
-		manualCodeInput.cancel();
-	}
-}
-
-/**
- * The model ids a target can be configured with, and where they came from.
- * `probe` is the only source that says anything about the server in front of
- * us right now; `catalog` is static provider knowledge, and `existing` is the
- * list a previous configure recorded, which the server may no longer match.
- */
-interface WireModelInventory {
-	models: string[];
-	source: "catalog" | "probe" | "cache" | "legacy" | "none";
-	/** Per-model load state when the probe reported it. */
-	modelStates?: Readonly<Record<string, ProbeModelStatus>> | undefined;
-}
-
-/**
- * Every id the runtime would resolve. LM Studio lists a loaded model under its
- * instance id and keeps the model key only in the state map, and the request
- * path accepts either, so both count as advertised.
- */
-function advertisedModelIds(inventory: Pick<WireModelInventory, "models" | "modelStates">): string[] {
-	const ids = [...inventory.models];
-	for (const id of Object.keys(inventory.modelStates ?? {})) if (!ids.includes(id)) ids.push(id);
-	return ids;
-}
-
-function residentModelIds(modelStates: WireModelInventory["modelStates"]): string[] {
-	return Object.entries(modelStates ?? {})
-		.filter(([, status]) => status.state === "loaded" || status.state === "loading")
-		.map(([id]) => id);
-}
-
-function liveInventoryFor(
-	target: Pick<TargetDescriptor, "id" | "url">,
-	inventory: WireModelInventory,
-): LiveModelInventory {
-	return {
-		targetId: target.id,
-		url: target.url,
-		models: advertisedModelIds(inventory),
-		resident: residentModelIds(inventory.modelStates),
-	};
-}
-
-async function resolveSupportedWireModels(
-	runtime: RuntimeDescriptor,
-	target: TargetDescriptor,
-	existing?: TargetDescriptor,
-	authToken?: string,
-): Promise<WireModelInventory> {
-	const known = listKnownModelsForRuntime(runtime.id);
-	if (known.length > 0) return { models: known, source: "catalog" };
-	if (runtime.kind === "http") {
-		// The full probe carries load state alongside the ids; a runtime that
-		// lists models only through probeModels still gets its ids checked.
-		const probe = await runtimeProbe(runtime, target, authToken);
-		if (probe?.ok && probe.models && probe.models.length > 0) {
-			recordTargetModelSnapshot(target, probe.models);
-			return { models: [...probe.models], source: "probe", modelStates: probe.modelStates };
-		}
-		const discovered = await runtimeProbeModels(runtime, target, authToken);
-		if (discovered.length > 0) {
-			recordTargetModelSnapshot(target, discovered);
-			return { models: discovered, source: "probe" };
-		}
-	}
-	const cached = readTargetModelSnapshot(target);
-	if (cached && cached.models.length > 0) return { models: [...cached.models], source: "cache" };
-	if (existing?.wireModels && existing.wireModels.length > 0) {
-		recordTargetModelSnapshot(target, existing.wireModels);
-		return { models: [...existing.wireModels], source: "legacy" };
-	}
-	return { models: [], source: "none" };
-}
-
 function resolveModelChoice(
 	answer: string,
 	wireModels: ReadonlyArray<string>,
@@ -819,6 +418,10 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 		printError("--agent-profile-model requires --agent-profile");
 		return 2;
 	}
+	if (args.bindAgent !== undefined && args.workerProfile === undefined) {
+		printError("--bind-agent requires --agent-profile");
+		return 2;
+	}
 	if (args.workerProfile !== undefined && args.workerProfile.trim().length === 0) {
 		printError("--agent-profile must be non-empty");
 		return 2;
@@ -889,13 +492,14 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 		...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
 		...(args.reasoning !== undefined ? { reasoning: args.reasoning } : {}),
 		...(existing?.lmstudio ? { lmstudio: existing.lmstudio } : {}),
+		...(existing?.litellm ? { litellm: existing.litellm } : {}),
 	});
 	const inventory = await resolveSupportedWireModels(runtime, seed, existing, args.apiKey);
 	const wireModels = inventory.models;
 	const model =
 		args.model ??
 		existing?.defaultModel ??
-		support.defaultModel ??
+		(inventory.source === "probe" ? wireModels[0] : support.defaultModel) ??
 		(support.modelSource === "catalog" ? undefined : wireModels[0]);
 	if (model === undefined && support.modelSource === "catalog") {
 		refuseCatalogSeededModel(runtime, support);
@@ -919,6 +523,7 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 		...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
 		...(args.reasoning !== undefined ? { reasoning: args.reasoning } : {}),
 		...(existing?.lmstudio ? { lmstudio: existing.lmstudio } : {}),
+		...(existing?.litellm ? { litellm: existing.litellm } : {}),
 	});
 	const setOrchestrator = args.setOrchestrator || args.orchestratorModel !== undefined;
 	const setBackground = args.setBackground || args.backgroundModel !== undefined;
@@ -958,6 +563,7 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 				descriptor,
 				args.workerProfileModel ?? descriptor.defaultModel ?? null,
 			);
+			if (args.bindAgent !== undefined) bindAgentProfileInSettings(target, args.bindAgent, args.workerProfile);
 		}
 	};
 	// Apply to the local snapshot for the summary below, then persist the same
@@ -966,7 +572,9 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 	applyConfiguration(settings);
 	updateSettings(applyConfiguration);
 	const probe = await runtimeProbe(runtime, descriptor);
-	if (probe?.ok && probe.models) recordTargetModelSnapshot(descriptor, probe.models);
+	if (probe?.ok && probe.models) {
+		recordTargetModelSnapshot(descriptor, probe.models, probe.modelLabels ? { modelLabels: probe.modelLabels } : {});
+	}
 	printSummary(settings, descriptor, probe);
 	if (
 		runtime.auth === "oauth" &&
@@ -1037,45 +645,6 @@ async function pickRuntimeFromEntries(
 	}
 }
 
-const LOCAL_APP_RUNTIME_IDS: ReadonlySet<string> = new Set(["ollama-native", "lmstudio"]);
-
-// Generic protocol-compatible runtimes. They are classified local-http (they
-// carry a probe and no cloud catalog entry), but a hosted endpoint such as
-// Inception/Mercury is exactly an OpenAI-compatible cloud API, so the wizard
-// also surfaces them under the Cloud API path.
-const PROTOCOL_COMPAT_RUNTIME_IDS: ReadonlySet<string> = new Set(["openai-compat", "anthropic-compat"]);
-
-function runtimesForCategory(
-	entries: ReadonlyArray<ProviderSupportEntry>,
-	category: ConfigureCategory,
-): ProviderSupportEntry[] {
-	switch (category) {
-		case "local-app":
-			return entries.filter((entry) => LOCAL_APP_RUNTIME_IDS.has(entry.runtimeId));
-		case "local-http":
-			return entries.filter((entry) => entry.group === "local-http" && !LOCAL_APP_RUNTIME_IDS.has(entry.runtimeId));
-		case "chatgpt":
-			return entries.filter((entry) => entry.runtimeId === "openai-codex");
-		case "cloud-api": {
-			const byLabel = (a: ProviderSupportEntry, b: ProviderSupportEntry) =>
-				a.label.localeCompare(b.label) || a.runtimeId.localeCompare(b.runtimeId);
-			const named = entries
-				.filter((entry) => entry.group === "cloud-api")
-				.slice()
-				.sort(byLabel);
-			// Surface the generic OpenAI/Anthropic-compatible runtimes here too,
-			// shown last and under the cloud heading rather than their native group.
-			const compat = entries
-				.filter((entry) => PROTOCOL_COMPAT_RUNTIME_IDS.has(entry.runtimeId))
-				.map((entry) => ({ ...entry, group: "cloud-api" as const }))
-				.sort(byLabel);
-			return [...named, ...compat];
-		}
-		case "all":
-			return entries.slice();
-	}
-}
-
 async function pickCategory(rl: ReturnType<typeof createInterface>): Promise<ConfigureCategory | null> {
 	process.stdout.write("\nHow will you connect Clio to a model?\n\n");
 	for (const line of formatCategoryMenu(terminalColumns())) process.stdout.write(`${line}\n`);
@@ -1143,16 +712,11 @@ async function maybeSteerToNativeRuntime(
 	return native;
 }
 
-async function runInteractive(
+async function runTargetSetupInteractive(
 	rl: ReturnType<typeof createInterface>,
-	preselectedRuntime: RuntimeDescriptor | null,
+	runtime: RuntimeDescriptor,
 	defaults: ParsedArgs,
 ): Promise<number> {
-	let runtime = preselectedRuntime ?? (await pickRuntimeViaCategory(rl));
-	if (!runtime) {
-		printError("configuration cancelled");
-		return 130;
-	}
 	const auth = openAuthStorage();
 	const settings = readSettings();
 	let support = buildProviderSupportEntry(runtime);
@@ -1289,9 +853,10 @@ async function runInteractive(
 		...(defaults.maxTokens !== undefined ? { maxTokens: defaults.maxTokens } : {}),
 		...(defaults.reasoning !== undefined ? { reasoning: defaults.reasoning } : {}),
 		...(existing?.lmstudio ? { lmstudio: existing.lmstudio } : {}),
+		...(existing?.litellm ? { litellm: existing.litellm } : {}),
 	});
 
-	if (runtime.kind === "http") {
+	if (runtime.kind === "http" || runtime.externalAgentLoop?.modelCatalog === "live-authoritative") {
 		inventory = await resolveSupportedWireModels(runtime, tentative, existing ?? undefined);
 	}
 	const wireModels = inventory.models;
@@ -1299,12 +864,21 @@ async function runInteractive(
 	// --model here the way the non-interactive path does. It does need to stop
 	// offering the alphabetically first id as though it were the recommended one.
 	const catalogOrdered = support.modelSource === "catalog";
-	model = model ?? existing?.defaultModel ?? support.defaultModel ?? (catalogOrdered ? undefined : wireModels[0]);
+	model =
+		model ??
+		existing?.defaultModel ??
+		(inventory.source === "probe" ? wireModels[0] : support.defaultModel) ??
+		(catalogOrdered ? undefined : wireModels[0]);
 	if (wireModels.length > 0) {
 		process.stdout.write("\nSelectable models:\n");
 		for (const [index, wireModel] of wireModels.entries()) {
-			process.stdout.write(`  ${index + 1}. ${wireModel}${wireModel === model ? "  [default]" : ""}\n`);
+			const label = inventory.labels?.[wireModel];
+			process.stdout.write(
+				`  ${index + 1}. ${wireModel}${label && label !== wireModel ? ` — ${label}` : ""}${wireModel === model ? "  [default]" : ""}\n`,
+			);
 		}
+		if (inventory.source === "cache") process.stdout.write("  cached model snapshot (not verified in this run)\n");
+		if (inventory.probeError) process.stdout.write(`  live probe unavailable: ${inventory.probeError}\n`);
 		if (!model && catalogOrdered) {
 			process.stdout.write(`  listed in provider catalog order, which recommends none of them; pick one.\n`);
 		}
@@ -1375,6 +949,7 @@ async function runInteractive(
 		...(defaults.maxTokens !== undefined ? { maxTokens: defaults.maxTokens } : {}),
 		...(reasoningChoice !== undefined ? { reasoning: reasoningChoice } : {}),
 		...(existing?.lmstudio ? { lmstudio: existing.lmstudio } : {}),
+		...(existing?.litellm ? { litellm: existing.litellm } : {}),
 	});
 	try {
 		assertOrchestratorReplacementEligible(settings, descriptor);
@@ -1460,7 +1035,7 @@ async function runInteractive(
 
 	printSummary(settings, descriptor, probe);
 	printOk(`target ${targetId} saved`);
-	await runInteropReview(rl);
+	await runInteropReview({ rl });
 	return 0;
 }
 
@@ -1510,7 +1085,980 @@ export function runTargetRename(oldId: string, newId: string): number {
 	return 0;
 }
 
-export async function runConfigureCommand(argv: ReadonlyArray<string>): Promise<number> {
+/**
+ * The runtime configuration screens.
+ *
+ * Every screen is one `SectionSpec`: a title, the values it shows, and the
+ * actions that change them. Rendering goes through the lifecycle presenter, so
+ * `configure` degrades on a pipe and under NO_COLOR exactly as `reset`,
+ * `upgrade`, and `uninstall` do. Navigation goes through `pickEntry`, which
+ * uses the arrow-key selector on a terminal and the numbered readline prompt
+ * everywhere else, so Escape leaves a screen without the screen having to teach
+ * a token for it, and a scripted run still has a way to answer.
+ */
+
+interface SectionIo {
+	rl: ReturnType<typeof createInterface>;
+	out: NodeJS.WritableStream;
+	/** Both ends of this run, for an action that opens a picker of its own. */
+	streams: ConfigureStreams;
+	/** Confirm one change on the transcript, in the presenter's voice. */
+	ok: (text: string) => void;
+}
+
+interface SectionAction {
+	label: string;
+	hint?: string;
+	run: (io: SectionIo) => Promise<void>;
+}
+
+interface SectionSpec {
+	/** Canonical `--section` name. */
+	id: string;
+	title: string;
+	/** What the main menu says this screen covers. */
+	summary: string;
+	/** Other spellings `--section` accepts. */
+	aliases?: ReadonlyArray<string>;
+	fields: () => Array<readonly [string, string]>;
+	actions: ReadonlyArray<SectionAction>;
+}
+
+const NONE = "(none)";
+const onOff = (value: boolean): string => (value ? "enabled" : "disabled");
+const listOr = (values: ReadonlyArray<string>, fallback = NONE): string =>
+	values.length > 0 ? values.join(", ") : fallback;
+
+/** Read a bounded integer, leaving the setting alone when the answer is not one. */
+async function askInteger(
+	io: SectionIo,
+	label: string,
+	current: number,
+	apply: (value: number) => void,
+	min = 0,
+): Promise<void> {
+	const answer = await ask(io.rl, label, String(current));
+	if (answer === null) return;
+	const parsed = Number(answer);
+	if (!Number.isFinite(parsed) || parsed < min) {
+		io.out.write(`  ${label} must be a number of at least ${min}; left at ${current}\n`);
+		return;
+	}
+	const value = Math.floor(parsed);
+	apply(value);
+	io.ok(`${label} set to ${value}`);
+}
+
+/** Read one of a fixed set of words, leaving the setting alone otherwise. */
+async function askChoice(
+	io: SectionIo,
+	label: string,
+	allowed: ReadonlyArray<string>,
+	current: string,
+	apply: (value: string) => void,
+): Promise<void> {
+	const answer = await ask(io.rl, `${label} [${allowed.join("|")}]`, current);
+	if (answer === null) return;
+	const value = answer.trim().toLowerCase();
+	if (!allowed.includes(value)) {
+		io.out.write(`  ${label} must be one of ${allowed.join(", ")}; left at ${current}\n`);
+		return;
+	}
+	apply(value);
+	io.ok(`${label} set to ${value}`);
+}
+
+const SECTIONS: ReadonlyArray<SectionSpec> = [
+	{
+		id: "targets",
+		title: "Targets & Auth",
+		summary: "providers, endpoints, credentials, models",
+		aliases: ["auth", "target", "providers"],
+		fields: () => {
+			const settings = readSettings();
+			const rows: Array<readonly [string, string]> = [
+				["Chat target", `${settings.chat.target ?? NONE} (model: ${settings.chat.model ?? "target default"})`],
+				[
+					"Fleet target",
+					`${settings.fleet.default.target ?? NONE} (model: ${settings.fleet.default.model ?? "target default"})`,
+				],
+			];
+			if (settings.targets.length === 0) rows.push(["Registered", "(no targets registered)"]);
+			else
+				for (const target of settings.targets) {
+					rows.push([
+						`  ${target.id}`,
+						`${target.runtime}, model ${target.defaultModel ?? "unset"}${
+							settings.chat.target === target.id ? " [chat]" : ""
+						}${settings.fleet.default.target === target.id ? " [fleet]" : ""}`,
+					]);
+				}
+			return rows;
+		},
+		actions: [
+			{
+				label: "Add a target",
+				hint: "register a provider endpoint",
+				run: async (io) => {
+					const runtime = await pickRuntimeViaCategory(io.rl);
+					if (runtime) await runTargetSetupInteractive(io.rl, runtime, emptyArgs());
+				},
+			},
+			{
+				label: "Set the chat target",
+				hint: "which target answers in chat",
+				run: async (io) => {
+					await assignTarget(io, "chat");
+				},
+			},
+			{
+				label: "Set the fleet default target",
+				hint: "which target dispatched workers use",
+				run: async (io) => {
+					await assignTarget(io, "fleet");
+				},
+			},
+			{
+				label: "Remove a target",
+				run: async (io) => {
+					const settings = readSettings();
+					const ids = settings.targets.map((target) => target.id);
+					if (ids.length === 0) {
+						io.out.write("  No targets to remove.\n");
+						return;
+					}
+					io.out.write(`  Registered: ${ids.join(", ")}\n`);
+					const chosen = await ask(io.rl, "Target id to remove");
+					if (chosen === null || !ids.includes(chosen)) return;
+					if (await askYesNo(io.rl, `Remove target '${chosen}'?`, false)) {
+						runTargetRemove(chosen);
+					}
+				},
+			},
+		],
+	},
+	{
+		id: "models",
+		title: "Models & Thinking",
+		summary: "default model, thinking level, favorites",
+		aliases: ["model", "thinking"],
+		fields: () => {
+			const settings = readSettings();
+			return [
+				["Chat model", settings.chat.model ?? "(target default)"],
+				["Chat thinking", settings.chat.thinkingLevel],
+				["Fleet thinking", settings.fleet.default.thinkingLevel],
+				["Favorites", listOr(settings.chat.modelPicker.favorites)],
+				["Cycle set (Alt+J/K)", listOr(settings.chat.modelPicker.cycleSet)],
+			];
+		},
+		actions: [
+			{
+				label: "Chat thinking level",
+				hint: THINKING_LEVELS.join(" | "),
+				run: async (io) => {
+					await askChoice(io, "Chat thinking level", THINKING_LEVELS, readSettings().chat.thinkingLevel, (value) => {
+						updateSettings((draft) => {
+							draft.chat.thinkingLevel = value as ThinkingLevel;
+						});
+					});
+				},
+			},
+			{
+				label: "Fleet thinking level",
+				hint: THINKING_LEVELS.join(" | "),
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Fleet thinking level",
+						THINKING_LEVELS,
+						readSettings().fleet.default.thinkingLevel,
+						(value) => {
+							updateSettings((draft) => {
+								draft.fleet.default.thinkingLevel = value as ThinkingLevel;
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Chat default model",
+				hint: "blank clears the override",
+				run: async (io) => {
+					const model = await ask(
+						io.rl,
+						"Chat default model (blank for the target default)",
+						readSettings().chat.model ?? "",
+					);
+					if (model === null) return;
+					updateSettings((draft) => {
+						draft.chat.model = model.length > 0 ? model : null;
+					});
+					io.ok(model.length > 0 ? `Chat default model set to ${model}` : "Chat default model cleared");
+				},
+			},
+			{
+				label: "Model favorites",
+				hint: "comma-separated",
+				run: async (io) => {
+					await askList(io, "Model favorites", readSettings().chat.modelPicker.favorites, (values) => {
+						updateSettings((draft) => {
+							draft.chat.modelPicker.favorites = values;
+						});
+					});
+				},
+			},
+			{
+				label: "Cycle set",
+				hint: "comma-separated, Alt+J/K walks it",
+				run: async (io) => {
+					await askList(io, "Cycle set", readSettings().chat.modelPicker.cycleSet, (values) => {
+						updateSettings((draft) => {
+							draft.chat.modelPicker.cycleSet = values;
+						});
+					});
+				},
+			},
+		],
+	},
+	{
+		id: "chat",
+		title: "Chat Defaults",
+		summary: "streaming, progress, compaction",
+		fields: () => {
+			const settings = readSettings();
+			return [
+				["Smooth streaming", settings.interface.smoothStreaming],
+				["Terminal progress", onOff(settings.interface.terminalProgress)],
+				[
+					"Max output tokens",
+					settings.chat.maxOutputTokens > 0 ? String(settings.chat.maxOutputTokens) : "(runtime default)",
+				],
+				["Prompt prewarm", onOff(settings.chat.prewarm)],
+				[
+					"Auto-compaction",
+					settings.context.compaction.auto
+						? `enabled at ${Math.round(settings.context.compaction.threshold * 100)}%`
+						: "disabled",
+				],
+				[
+					"Working-set eviction",
+					settings.context.workingSet.enabled ? `enabled (${settings.context.workingSet.policy})` : "disabled",
+				],
+			];
+		},
+		actions: [
+			{
+				label: "Smooth streaming",
+				hint: "off | auto | on",
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Smooth streaming",
+						["off", "auto", "on"],
+						readSettings().interface.smoothStreaming,
+						(value) => {
+							updateSettings((draft) => {
+								draft.interface.smoothStreaming = value as SmoothStreaming;
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Terminal progress indicator",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.interface.terminalProgress = !draft.interface.terminalProgress;
+						next = draft.interface.terminalProgress;
+					});
+					io.ok(`Terminal progress ${onOff(next)}`);
+				},
+			},
+			{
+				label: "Max output tokens",
+				hint: "0 for the runtime default",
+				run: async (io) => {
+					await askInteger(io, "Max output tokens", readSettings().chat.maxOutputTokens, (value) => {
+						updateSettings((draft) => {
+							draft.chat.maxOutputTokens = value;
+						});
+					});
+				},
+			},
+			{
+				label: "Prompt prewarm",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.chat.prewarm = !draft.chat.prewarm;
+						next = draft.chat.prewarm;
+					});
+					io.ok(`Prompt prewarm ${onOff(next)}`);
+				},
+			},
+			{
+				label: "Auto-compaction",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.context.compaction.auto = !draft.context.compaction.auto;
+						next = draft.context.compaction.auto;
+					});
+					io.ok(`Auto-compaction ${onOff(next)}`);
+				},
+			},
+		],
+	},
+	{
+		id: "fleet",
+		title: "Fleet",
+		summary: "concurrency, retries, worker timeouts",
+		fields: () => {
+			const settings = readSettings();
+			return [
+				["Concurrency limit", String(settings.fleet.concurrency)],
+				["Max retries", String(settings.fleet.retry.maxRetries)],
+				["Tool calls per run", String(settings.fleet.limits.toolCallsPerRun)],
+				["Run timeout", `${settings.fleet.limits.internalRunTimeoutMs / 1000}s`],
+				["Worker profiles", listOr(Object.keys(settings.fleet.profiles))],
+				[
+					"Subagent pins",
+					listOr(Object.entries(settings.fleet.agentProfiles).map(([agent, profile]) => `${agent} -> ${profile}`)),
+				],
+				["Remote nodes", listOr(settings.fleet.nodes.map((node) => node.id))],
+			];
+		},
+		actions: [
+			{
+				label: "Concurrency limit",
+				hint: "auto, or a positive integer",
+				run: async (io) => {
+					const current = String(readSettings().fleet.concurrency);
+					const answer = await ask(io.rl, "Concurrency limit [auto or a number]", current);
+					if (answer === null) return;
+					if (answer.trim().toLowerCase() === "auto") {
+						updateSettings((draft) => {
+							draft.fleet.concurrency = "auto";
+						});
+						io.ok("Concurrency limit set to auto");
+						return;
+					}
+					const parsed = Number(answer);
+					if (!Number.isFinite(parsed) || parsed < 1) {
+						io.out.write(`  Concurrency limit must be auto or at least 1; left at ${current}\n`);
+						return;
+					}
+					updateSettings((draft) => {
+						draft.fleet.concurrency = Math.floor(parsed);
+					});
+					io.ok(`Concurrency limit set to ${Math.floor(parsed)}`);
+				},
+			},
+			{
+				label: "Max retries",
+				run: async (io) => {
+					await askInteger(io, "Max retries", readSettings().fleet.retry.maxRetries, (value) => {
+						updateSettings((draft) => {
+							draft.fleet.retry.maxRetries = value;
+						});
+					});
+				},
+			},
+			{
+				label: "Tool calls per run",
+				run: async (io) => {
+					await askInteger(
+						io,
+						"Tool calls per run",
+						readSettings().fleet.limits.toolCallsPerRun,
+						(value) => {
+							updateSettings((draft) => {
+								draft.fleet.limits.toolCallsPerRun = value;
+							});
+						},
+						1,
+					);
+				},
+			},
+			{
+				label: "Run timeout",
+				hint: "seconds",
+				run: async (io) => {
+					const current = readSettings().fleet.limits.internalRunTimeoutMs / 1000;
+					const answer = await ask(io.rl, "Run timeout in seconds", String(current));
+					if (answer === null) return;
+					const parsed = Number(answer);
+					if (!Number.isFinite(parsed) || parsed < 1) {
+						io.out.write(`  Run timeout must be at least 1 second; left at ${current}s\n`);
+						return;
+					}
+					updateSettings((draft) => {
+						draft.fleet.limits.internalRunTimeoutMs = Math.floor(parsed * 1000);
+					});
+					io.ok(`Run timeout set to ${Math.floor(parsed)}s`);
+				},
+			},
+		],
+	},
+	{
+		id: "permissions",
+		title: "Permissions & Autonomy",
+		summary: "autonomy level, worker permissions, cost limits",
+		aliases: ["autonomy", "safety"],
+		fields: () => {
+			const settings = readSettings();
+			return [
+				["Autonomy level", settings.safety.autonomy],
+				["Worker permissions", settings.fleet.permissions.mode],
+				["Session cost limit", `$${settings.safety.limits.sessionCostUsd} USD`],
+				["Turn tool budget", String(settings.safety.limits.chatToolCallsPerTurn)],
+				["Review watchdog", onOff(settings.safety.review.enabled)],
+			];
+		},
+		actions: [
+			{
+				label: "Autonomy level",
+				hint: "interactive | assisted | auto-edit | full",
+				run: async (io) => {
+					io.out.write(
+						"  interactive prompts for everything, assisted auto-reads and confirms writes,\n  auto-edit confirms only bash, full runs unattended.\n",
+					);
+					await askChoice(
+						io,
+						"Autonomy level",
+						["interactive", "assisted", "auto-edit", "full"],
+						readSettings().safety.autonomy,
+						(value) => {
+							updateSettings((draft) => {
+								draft.safety.autonomy = value as AutonomyLevel;
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Worker permission mode",
+				hint: "deny | fail | escalate",
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Worker permission mode",
+						["deny", "fail", "escalate"],
+						readSettings().fleet.permissions.mode,
+						(value) => {
+							updateSettings((draft) => {
+								draft.fleet.permissions.mode = value as WorkerPermissionMode;
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Session cost limit",
+				hint: "USD",
+				run: async (io) => {
+					const current = readSettings().safety.limits.sessionCostUsd;
+					const answer = await ask(io.rl, "Session cost limit in USD", String(current));
+					if (answer === null) return;
+					const parsed = Number(answer);
+					if (!Number.isFinite(parsed) || parsed <= 0) {
+						io.out.write(`  Session cost limit must be greater than 0; left at $${current}\n`);
+						return;
+					}
+					updateSettings((draft) => {
+						draft.safety.limits.sessionCostUsd = parsed;
+					});
+					io.ok(`Session cost limit set to $${parsed} USD`);
+				},
+			},
+			{
+				label: "Turn tool budget",
+				run: async (io) => {
+					await askInteger(
+						io,
+						"Turn tool budget",
+						readSettings().safety.limits.chatToolCallsPerTurn,
+						(value) => {
+							updateSettings((draft) => {
+								draft.safety.limits.chatToolCallsPerTurn = value;
+							});
+						},
+						1,
+					);
+				},
+			},
+			{
+				label: "Turn-end review watchdog",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.safety.review.enabled = !draft.safety.review.enabled;
+						next = draft.safety.review.enabled;
+					});
+					io.ok(`Review watchdog ${onOff(next)}`);
+				},
+			},
+		],
+	},
+	{
+		id: "panes",
+		title: "Panes & Layout",
+		summary: "terminal panes, startup layout, display mode",
+		aliases: ["layout", "interface", "pane"],
+		fields: () => {
+			const settings = readSettings();
+			return [
+				["Panes capability", settings.interface.panes.enabled],
+				["Startup layout", settings.interface.panes.layout],
+				["TUI mode", settings.interface.mode],
+				["Output detail", settings.interface.outputDetail],
+				["Desktop notifications", onOff(settings.interface.desktopNotifications)],
+				["Git commit attribution", onOff(settings.integrations.git.commitAttribution)],
+			];
+		},
+		actions: [
+			{
+				label: "Panes capability",
+				hint: "off | auto | embedded",
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Panes capability",
+						["off", "auto", "embedded"],
+						readSettings().interface.panes.enabled,
+						(value) => {
+							updateSettings((draft) => {
+								draft.interface.panes.enabled = value as PanesSettings["enabled"];
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Startup layout",
+				hint: "off | workers | cockpit",
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Startup layout",
+						["off", "workers", "cockpit"],
+						readSettings().interface.panes.layout,
+						(value) => {
+							updateSettings((draft) => {
+								draft.interface.panes.layout = value as PanesSettings["layout"];
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "TUI mode",
+				hint: "regular | fullscreen",
+				run: async (io) => {
+					await askChoice(io, "TUI mode", ["regular", "fullscreen"], readSettings().interface.mode, (value) => {
+						updateSettings((draft) => {
+							draft.interface.mode = value as TuiMode;
+						});
+					});
+				},
+			},
+			{
+				label: "Output detail",
+				hint: "minimal | default | verbose",
+				run: async (io) => {
+					await askChoice(
+						io,
+						"Output detail",
+						["minimal", "default", "verbose"],
+						readSettings().interface.outputDetail,
+						(value) => {
+							updateSettings((draft) => {
+								draft.interface.outputDetail = value as OutputVerbosity;
+							});
+						},
+					);
+				},
+			},
+			{
+				label: "Desktop notifications",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.interface.desktopNotifications = !draft.interface.desktopNotifications;
+						next = draft.interface.desktopNotifications;
+					});
+					io.ok(`Desktop notifications ${onOff(next)}`);
+				},
+			},
+			{
+				label: "Git commit attribution",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.integrations.git.commitAttribution = !draft.integrations.git.commitAttribution;
+						next = draft.integrations.git.commitAttribution;
+					});
+					io.ok(`Git commit attribution ${onOff(next)}`);
+				},
+			},
+		],
+	},
+	{
+		id: "skills",
+		title: "Skills & Extensions",
+		summary: "project imports, ACP peers, plugins",
+		aliases: ["extensions", "skill", "interop"],
+		fields: () => {
+			const settings = readSettings();
+			const rows: Array<readonly [string, string]> = [
+				["Trust project imports", settings.integrations.projectResources.trustProjectImports ? "trusted" : "untrusted"],
+				["External ACP agents", String(settings.integrations.externalAgents.entries.length)],
+			];
+			for (const agent of settings.integrations.externalAgents.entries) {
+				rows.push([`  ${agent.id}`, `${agent.command} (governance: ${agent.toolGovernance ?? "default"})`]);
+			}
+			rows.push(
+				["Runtime plugins", listOr(settings.integrations.runtimePlugins)],
+				["Library remote sync", onOff(settings.integrations.library.sync)],
+			);
+			return rows;
+		},
+		actions: [
+			{
+				label: "Trust project imports",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.integrations.projectResources.trustProjectImports =
+							!draft.integrations.projectResources.trustProjectImports;
+						next = draft.integrations.projectResources.trustProjectImports;
+					});
+					io.ok(`Project imports ${next ? "trusted" : "untrusted"}`);
+				},
+			},
+			{
+				label: "Review external ACP agents",
+				hint: "runs the interop review",
+				run: async (io) => {
+					await runInteropReview({ rl: io.rl, streams: io.streams });
+				},
+			},
+			{
+				label: "Library remote sync",
+				hint: "toggle",
+				run: async (io) => {
+					let next = false;
+					updateSettings((draft) => {
+						draft.integrations.library.sync = !draft.integrations.library.sync;
+						next = draft.integrations.library.sync;
+					});
+					io.ok(`Library remote sync ${onOff(next)}`);
+				},
+			},
+		],
+	},
+	{
+		id: "diagnostics",
+		title: "Diagnostics",
+		summary: "version, directories, doctor, raw settings",
+		aliases: ["doctor", "diag"],
+		fields: () => {
+			const dirs = resolveClioDirs();
+			const info = getVersionInfo();
+			return [
+				["Clio Coder", info.clio],
+				["Node.js", info.node],
+				["Platform", info.platform],
+				["Config dir", shortenPath(dirs.config)],
+				["Data dir", shortenPath(dirs.data)],
+				["State dir", shortenPath(dirs.state)],
+				["Cache dir", shortenPath(dirs.cache)],
+			];
+		},
+		actions: [
+			{
+				label: "Run doctor",
+				hint: "read-only health check",
+				run: async () => {
+					const { runDoctorCommand } = await import("./doctor.js");
+					await runDoctorCommand([]);
+				},
+			},
+			{
+				label: "Show raw settings.yaml",
+				run: async (io) => {
+					const file = settingsPath();
+					if (!existsSync(file)) {
+						io.out.write("  settings.yaml does not exist yet.\n");
+						return;
+					}
+					io.out.write(`\n--- ${shortenPath(file)} ---\n${readFileSync(file, "utf8")}--- end ---\n`);
+				},
+			},
+		],
+	},
+];
+
+/** A `ParsedArgs` with nothing set, for the target wizard called from a section. */
+function emptyArgs(): ParsedArgs {
+	return {
+		positional: [],
+		help: false,
+		list: false,
+		all: false,
+		interop: false,
+		json: false,
+		force: false,
+		gateway: false,
+		setOrchestrator: false,
+		setBackground: false,
+		setWorkerDefault: false,
+	};
+}
+
+async function askList(
+	io: SectionIo,
+	label: string,
+	current: ReadonlyArray<string>,
+	apply: (values: string[]) => void,
+): Promise<void> {
+	const answer = await ask(io.rl, `${label} (comma-separated, blank clears)`, current.join(", "));
+	if (answer === null) return;
+	const values = answer
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+	apply(values);
+	io.ok(values.length === 0 ? `${label} cleared` : `${label} set to ${values.join(", ")}`);
+}
+
+async function assignTarget(io: SectionIo, role: "chat" | "fleet"): Promise<void> {
+	const settings = readSettings();
+	const ids = settings.targets.map((target) => target.id);
+	if (ids.length === 0) {
+		io.out.write("  No targets registered yet. Add one first.\n");
+		return;
+	}
+	io.out.write(`  Registered: ${ids.join(", ")}\n`);
+	const currentTarget = role === "chat" ? settings.chat.target : settings.fleet.default.target;
+	const chosen = await ask(io.rl, `${role === "chat" ? "Chat" : "Fleet"} target id`, currentTarget ?? ids[0] ?? "");
+	if (chosen === null) return;
+	if (!ids.includes(chosen)) {
+		io.out.write(`  ${chosen} is not a registered target; nothing changed.\n`);
+		return;
+	}
+	const target = settings.targets.find((entry) => entry.id === chosen);
+	const model = await ask(io.rl, "Model (blank for the target default)", target?.defaultModel ?? "");
+	if (model === null) return;
+	updateSettings((draft) => {
+		if (role === "chat") {
+			draft.chat.target = chosen;
+			draft.chat.model = model.length > 0 ? model : null;
+		} else {
+			draft.fleet.default.target = chosen;
+			draft.fleet.default.model = model.length > 0 ? model : null;
+		}
+	});
+	io.ok(`${role === "chat" ? "Chat" : "Fleet"} target set to ${chosen}`);
+}
+
+interface MenuEntry {
+	label: string;
+	hint?: string;
+}
+
+type MenuChoice = { kind: "index"; index: number } | { kind: "back" } | { kind: "quit" };
+
+/**
+ * Pick one entry, by arrow keys on a terminal and by number everywhere else.
+ * The numbered fallback is not a lesser path: it is what a recorded session, a
+ * pipe, and a dumb terminal get, and it accepts the same `b`/`q` tokens the rest
+ * of this CLI uses.
+ */
+async function pickEntry(
+	rl: ReturnType<typeof createInterface>,
+	io: ConfigureStreams,
+	entries: ReadonlyArray<MenuEntry>,
+	backLabel: string,
+	plain: boolean,
+): Promise<MenuChoice> {
+	const out = io.out;
+	if (canSelect(io.in as NodeJS.ReadStream, out as NodeJS.WriteStream)) {
+		const result = await promptSelect({
+			choices: entries.map((entry, index) => ({
+				value: index,
+				label: entry.label,
+				...(entry.hint === undefined ? {} : { hint: entry.hint }),
+			})),
+			railPrefix: railPrefix(plain),
+			backLabel,
+			input: io.in as NodeJS.ReadStream,
+			output: out as NodeJS.WriteStream,
+		});
+		if (result.kind === "selected") return { kind: "index", index: result.value };
+		return result.kind === "quit" ? { kind: "quit" } : { kind: "back" };
+	}
+
+	const rail = railPrefix(plain);
+	entries.forEach((entry, index) => {
+		out.write(`${rail}${index + 1}. ${entry.label}${entry.hint === undefined ? "" : `  (${entry.hint})`}\n`);
+	});
+	out.write(`${rail}b. ${backLabel}\n${rail}q. Quit\n`);
+	const answer = await ask(rl, "\nSelection", "b");
+	if (answer === null) return { kind: "quit" };
+	const trimmed = answer.trim().toLowerCase();
+	if (trimmed === "b" || trimmed === "back" || trimmed.length === 0) return { kind: "back" };
+	if (trimmed === "q" || trimmed === "quit") return { kind: "quit" };
+	const index = Number.parseInt(trimmed, 10) - 1;
+	if (Number.isInteger(index) && index >= 0 && index < entries.length) return { kind: "index", index };
+	out.write(`${rail}Not one of the choices: ${answer}\n`);
+	return { kind: "back" };
+}
+
+/** Header, source file, and current values for one screen. */
+function renderSection(spec: SectionSpec, out: NodeJS.WritableStream): LifecyclePresenter {
+	const presenter = createLifecyclePresenter({ stream: out });
+	presenter.header(spec.title, "configure");
+	presenter.note(`Source: ${shortenPath(settingsPath())}`);
+	presenter.fields(spec.fields());
+	return presenter;
+}
+
+/** Show one screen and stay on it until the operator leaves or quits. */
+async function runSection(
+	rl: ReturnType<typeof createInterface>,
+	streams: ConfigureStreams,
+	spec: SectionSpec,
+	backLabel: string,
+): Promise<"back" | "quit"> {
+	for (;;) {
+		const presenter = renderSection(spec, streams.out);
+		const io: SectionIo = {
+			rl,
+			out: streams.out,
+			streams,
+			ok: (text) => {
+				presenter.completedStep(text);
+			},
+		};
+		presenter.blank();
+		const choice = await pickEntry(rl, streams, spec.actions, backLabel, presenter.isPlain());
+		if (choice.kind !== "index") return choice.kind;
+		const action = spec.actions[choice.index];
+		if (action !== undefined) await action.run(io);
+	}
+}
+
+/** The top-level screen. Leaving it is an ordinary exit, not a cancellation. */
+async function runConfigSectionsMenu(
+	rl: ReturnType<typeof createInterface>,
+	streams: ConfigureStreams,
+): Promise<number> {
+	for (;;) {
+		const presenter = createLifecyclePresenter({ stream: streams.out });
+		presenter.header("Clio Coder Configuration", "configure");
+		presenter.note(`Source: ${shortenPath(settingsPath())}`);
+		presenter.blank();
+		const choice = await pickEntry(
+			rl,
+			streams,
+			SECTIONS.map((section) => ({ label: section.title, hint: section.summary })),
+			"quit",
+			presenter.isPlain(),
+		);
+		// Escape and q both leave the top screen, and leaving a settings menu you
+		// only looked at is not a failure: this used to exit 130 and print
+		// "error: configuration cancelled" over a run that did exactly what was
+		// asked. The first-run wizard still exits 130, because there a cancel
+		// really does leave Clio unconfigured.
+		if (choice.kind !== "index") return 0;
+		const spec = SECTIONS[choice.index];
+		if (spec === undefined) continue;
+		if ((await runSection(rl, streams, spec, "back")) === "quit") return 0;
+	}
+}
+
+/** Resolve a `--section` value to exactly one screen, by id or listed alias. */
+function findSection(name: string): SectionSpec | undefined {
+	const wanted = name.trim().toLowerCase();
+	return SECTIONS.find((section) => section.id === wanted || (section.aliases ?? []).includes(wanted));
+}
+
+const SECTION_IDS: ReadonlyArray<string> = SECTIONS.map((section) => section.id);
+
+/** The streams this run reads from and writes to, which the tests replace. */
+interface ConfigureStreams {
+	in: NodeJS.ReadableStream;
+	out: NodeJS.WritableStream;
+}
+
+async function runInteractive(
+	rl: ReturnType<typeof createInterface>,
+	preselectedRuntime: RuntimeDescriptor | null,
+	defaults: ParsedArgs,
+	streams: ConfigureStreams,
+): Promise<number> {
+	if (preselectedRuntime) {
+		return await runTargetSetupInteractive(rl, preselectedRuntime, defaults);
+	}
+
+	if (defaults.section !== undefined) {
+		const spec = findSection(defaults.section);
+		if (spec === undefined) {
+			printError(`unknown section: ${defaults.section}. Sections: ${SECTION_IDS.join(", ")}`);
+			return 2;
+		}
+		// Without a terminal there is nobody to answer, and printing a prompt into
+		// a pipe is a dead end that reads as a hang. The screen is still worth
+		// showing, so a scripted `configure --section fleet` is a read of that
+		// section rather than a refusal.
+		if ((streams.in as { isTTY?: boolean }).isTTY !== true) {
+			renderSection(spec, streams.out).done("Done");
+			return 0;
+		}
+		await runSection(rl, streams, spec, "quit");
+		return 0;
+	}
+
+	if (readSettings().targets.length === 0) {
+		// The first run is its own screen flow. It only exists where a keypress can
+		// be read; a pipe, a recorded session, and a dumb terminal keep the
+		// numbered readline path below, which is still the only way to answer them.
+		//
+		// The readline interface is closed first. Left open it stays subscribed to
+		// stdin's keypresses and echoes each one, which puts a stray line under
+		// every menu the wizard draws and breaks the erase that replaces the menu
+		// with its answer. The wizard opens its own where a browser sign-in needs
+		// one.
+		if (canRunOnboarding(streams)) {
+			rl.close();
+			return await runOnboardingWizard(streams);
+		}
+		const runtime = await pickRuntimeViaCategory(rl);
+		if (!runtime) {
+			printError("configuration cancelled");
+			return 130;
+		}
+		return await runTargetSetupInteractive(rl, runtime, defaults);
+	}
+
+	return await runConfigSectionsMenu(rl, streams);
+}
+
+export async function runConfigureCommand(
+	argv: ReadonlyArray<string>,
+	inStream: NodeJS.ReadableStream = input,
+	outStream: NodeJS.WritableStream = output,
+): Promise<number> {
 	let args: ParsedArgs;
 	try {
 		args = parseSetupArgs(argv);
@@ -1526,15 +2074,21 @@ export async function runConfigureCommand(argv: ReadonlyArray<string>): Promise<
 	initializeClioHome();
 	ensureRegistryPopulated();
 
+	if (args.json) {
+		const settings = readSettings();
+		outStream.write(`${JSON.stringify(settings, null, 2)}\n`);
+		return 0;
+	}
+
 	if (args.list) {
 		printRuntimeList(args.all);
 		return 0;
 	}
 	if (args.interop) {
-		if (!input.isTTY) return runInteropReview(null);
+		if (!input.isTTY) return runInteropReview({ rl: null });
 		const rl = createInterface({ input, output });
 		try {
-			return await runInteropReview(rl);
+			return await runInteropReview({ rl, streams: { in: input, out: output } });
 		} finally {
 			rl.close();
 		}
@@ -1595,9 +2149,9 @@ export async function runConfigureCommand(argv: ReadonlyArray<string>): Promise<
 		return 2;
 	}
 
-	const rl = createInterface({ input, output });
+	const rl = createInterface({ input: inStream, output: outStream });
 	try {
-		return await runInteractive(rl, runtime, args);
+		return await runInteractive(rl, runtime, args, { in: inStream, out: outStream });
 	} catch (err) {
 		printError(err instanceof Error ? err.message : String(err));
 		return 1;