@iowarp/clio-coder 0.4.5 → 0.4.6

package/docs/guide/installation-and-lifecycle.md

@@ -15,6 +15,29 @@ consumers install the built package and do not need the repository toolchain.
 This guide describes the default directories, file purposes, permissions, and
 lifecycle operations.
 
+### Start, change settings, or recover
+
+| Task | Command | Result |
+| --- | --- | --- |
+| Set up a new installation | `clio-coder configure` | Quick Connect: endpoint, key if needed, model, Connect; then start `clio-coder`. |
+| Change a connection | `clio-coder configure --section targets` | Add or edit endpoints, credentials, and models; choose role defaults. |
+| Change any setting or repair YAML | `clio-coder configure --edit` | Edit a draft, validate, and save with a backup. |
+| Diagnose the installation | `clio-coder doctor` | Read-only diagnosis. `clio-coder doctor --fix` repairs structure and permissions. |
+| Finish a package-manager update | `clio-coder upgrade --post-install` | Apply local migrations and installation checks. |
+| Start configuration over | `clio-coder reset --config` | Reset settings, preserve credentials and history, then run `clio-coder configure`. |
+| Emulate a fresh user | `clio-coder reset --all` | Remove all four user roots, recreate defaults, then run `clio-coder configure`. |
+| Remove user state | `clio-coder uninstall` | Remove the selected user roots; remove the package with the manager that installed it. |
+
+Reset and uninstall preview their scope and ask for confirmation. Use
+`--dry-run` to inspect without changing anything. A bare `reset` clears session
+state, so use `--config` when your intent is to start model setup over. Project
+`.clio-coder/` directories survive these user-level operations.
+
+The source installer prepares the launcher and directory structure, then points
+you to `clio-coder configure`. It does not ask you to configure delegation peers
+before your primary model is set up. Upgrading preserves settings and
+credentials; reinstalling the package alone does not reset them.
+
 ### Optional dependency: the Claude Agent SDK
 
 `@anthropic-ai/claude-agent-sdk` is an `optionalDependencies` entry, not a hard dependency. Its platform package carries a proprietary binary of roughly 224MB per platform, and only the `claude-sdk` runtime uses it. Skip it with:
@@ -296,7 +319,7 @@ Key lifecycle and operational updates in v0.3.7:
 - Fullscreen TUI mode (`interface.mode`, `interface.fullscreenScrollbar`) is
   available through `/settings interface` and requires a restart. Adaptive
   presentation pacing is the live `interface.smoothStreaming` setting; it
-  defaults to `off`, with conservative `auto` and explicit `on` available from
+  defaults to conservative `auto`, with `off` and explicit `on` available from
   the same area.
 - Interactive launch paints a measured Stage 0 shell on the same terminal and editor that Stage 1 hydrates. Typing, queued submits, resize, and Ctrl+C remain live during hydration; set `CLIO_CODER_INSTANT_SHELL=0` for the legacy fully hydrated first-frame path.
 - Turn settlement is enforced on `/new`, `/resume`, `/tree`, and `/fork` to cleanly commit in-flight streams before session writer replacement (#114).
@@ -408,18 +431,20 @@ or release the handle, then run the identical command again and it resumes from
 whatever is left. A partial delete never reports global success.
 
 ### E. Interactive Configuration (`clio-coder configure`)
-`clio-coder configure` provides a structured, multi-section configuration wizard
-for model targets, runtime defaults, fleet limits, permissions, panes, and
-integrations:
+
+The interactive launcher starts with **Quick Connect**, followed by **Settings**
+and **Diagnostics**. Quick Connect asks for an endpoint URL, a key when needed,
+and a model when several are available. Review and **Connect**; the recommended
+defaults handle the rest. An unconfigured interactive `clio-coder` opens this
+same launcher and continues into chat after a successful setup.
 
 ```bash
-clio-coder configure [--section <name>] [--json] [--interop] [--list] [--all]
+clio-coder configure
+clio-coder configure --quick
+clio-coder configure --settings
 ```
 
-When run against an unconfigured home (or when launched interactively with no
-model target), it routes immediately to the target category selection menu. Once
-targets are configured, launching `clio-coder configure` presents the 8 top-level
-runtime sections:
+**Settings** contains the nine advanced sections:
 
 1. **Targets & Auth**: manage providers, endpoints, credentials, and models.
 2. **Models & Thinking**: default models, thinking levels, model favorites, cycle set.
@@ -429,14 +454,22 @@ runtime sections:
 6. **Panes & Layout**: terminal panes capability, dock layout, TUI display mode, notifications.
 7. **Skills & Extensions**: trust project imports, external ACP agents, plugins, library sync.
 8. **Diagnostics**: version information, resolved directories, doctor check, raw settings inspection.
+9. **All Settings**: validated file editor for the complete settings schema.
 
 Every section header indicates the exact settings file path being modified
 (`Source: ~/.config/clio-coder/settings.yaml`), prints the current active values,
-and provides a safe back/exit option (`b` or `q`).
+and provides arrow-key navigation with Escape to go back and `q` to quit. The
+parent menu remembers your selected row. Dumb terminals use numbered menus
+with `b` for Back and `q` to quit.
 
 The `--section <name>` flag jumps directly into any section (e.g.,
 `clio-coder configure --section models` or `clio-coder configure --section fleet`).
-The `--json` flag emits the active settings in formatted JSON for scripting.
+The `--json` flag emits user settings with defaults in formatted JSON for scripting.
+`--edit` opens a temporary settings draft in `VISUAL`/`EDITOR`, validates it before
+saving, and keeps the previous file as `settings.yaml.bak`. It can repair a file
+that is too malformed to open the regular menu. See the
+[configuration guide](configuration-and-targets.md#first-run-flow) for the complete
+new-user, add-target, edit-target, and cancellation paths.
 
 ---
 

package/docs/process/development-pipeline.md

@@ -59,7 +59,7 @@ closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skil
    `refs/heads/main`; every survivor needs an owner and purpose.
 
 Maintainer release candidates are local-only and use a compact branch name
-that cannot collide with their tag: branch `v043`, tag `v0.4.3`. Gate the exact
+that cannot collide with their tag: branch `v046`, tag `v0.4.6`. Gate the exact
 candidate, require fetched `origin/main` to be its ancestor, fast-forward local
 `main`, fetch again, and push only `refs/heads/main:refs/heads/main` with
 explicit authorization. After CI passes, push only the fully qualified

package/docs/process/documentation-coverage.md

@@ -56,7 +56,7 @@ preserves that audit-time state.
 | `guide/exit-codes-and-output.md` | `src/cli/**`; `src/entry/**`; CLI smoke tests | `html/exit_codes_blueprint.html` | The JSON event table is described too broadly; full mode can pass additional `clio_coder_*` tool, permission, and plan frames. Core process exit codes are correct. |
 | `guide/extensions-and-sharing.md` | `src/domains/extensions/**`; `src/domains/resources/**`; `src/domains/share/**`; extension and share CLIs | `html/extensions_blueprint.html` | Extensions discover skills, prompts, agents, fleets, and reserved themes, not only prompts and skills. Judge eval arms are not full-auto. Share archives use `clio-coder-share-archive`, `clio-coder.share.v1`, and `clioCoderVersion`; old names are compatibility inputs. The exported settings fragment contains current v2 leaves rather than the documented old scope. |
 | `process/fleet-demo-runbook.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; `src/cli/doctor.ts` | No; parity gap. | Current receipts use integrity v20, not v16, and older versions are retired rather than universally failing verification. |
-| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Tool expansion provenance uses `clio-coder.tool.expand`, not `clio.tool.expand`. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
+| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Output styles use `clio-coder.output.cycle`; worker previews follow the same preset regardless of origin. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
 | `process/git-commit-provenance.md` | `src/core/commit-attribution.ts`; `src/core/git-commit-attribution.ts`; `src/core/defaults.ts`; dispatch attribution tests | No; parity gap. | Canonical configuration is `integrations.git.commitAttribution`; `attribution.gitCommits` is migration-only. Commit trailers recognize and emit `receipt-v20`, not v19. |
 | `guide/glossary.md` | Owning types in `src/domains/dispatch/**`, `src/domains/session/**`, `src/domains/context/**`, and `src/tools/**` | `html/glossary_blueprint.html` | Receipt integrity is v20. Dispatch run and session IDs are 12-character random base36 identifiers, while session turn and entry IDs use UUIDv7. Route candidates contain more identity and policy fields than the four-field definition. Council is a current topology. `internal` is a dispatch request origin, not a worker run origin. Context ledger buckets are incomplete. |
 | `guide/installation-and-lifecycle.md` | `src/cli/upgrade.ts`; `src/cli/doctor.ts`; `src/cli/reset.ts`; `src/cli/uninstall.ts`; `src/domains/lifecycle/**`; `src/core/xdg.ts` | `html/lifecycle_blueprint.html` | Install metadata omits `repairedAt` and overgeneralizes preexisting-home detection beyond config, data, and state. The upgrade section presents a stale 0.3.x sequence as current and claims one migration, while the current registry has five migrations and 0.4.2 emits a generic notice. |

package/docs/process/release-cut-checklist.md

@@ -13,18 +13,21 @@ canonical remote state or publishes immutable packages.
 ## Part 1: Candidate Preparation on a Local Compact Branch
 
 Maintainers prepare release candidates on a local-only compact branch named after
-the version without punctuation, such as `v044` for version `0.4.4`. Dotted branch
-names like `v0.4.4` are forbidden because dotted names belong exclusively to immutable
+the version without punctuation, such as `v046` for version `0.4.6`. Dotted branch
+names like `v0.4.6` are forbidden because dotted names belong exclusively to immutable
 tags. The canonical repository hosts only `main`, and no release candidate branch is
 ever pushed to canonical origin.
 
 1. Ensure the working tree is clean and updated from canonical origin:
 
    ```bash
-   git checkout -b v044 origin/main
+   git checkout -b v046 origin/main
    ```
 
-2. Update `version` in `package.json` to the release version.
+2. Update `version` in `package.json` and `assets/acp-registry/agent.json` to the
+   release version. Update the README's source-install tag and remove any
+   development-only notices. Keep historical release records, protocol schema
+   versions, dependency versions, and migration fixtures unchanged.
 
 3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
    `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
@@ -112,7 +115,7 @@ an immutable package. Do not execute any of them without explicit maintainer aut
 
    ```bash
    git checkout main
-   git merge --ff-only v044
+   git merge --ff-only v046
    ```
 
 4. Verify that local `main` matches the reviewed candidate SHA exactly.
@@ -150,6 +153,15 @@ an immutable package. Do not execute any of them without explicit maintainer aut
 
 5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
 
+6. Reconcile the release milestone against the tagged commits and each ticket's
+   acceptance evidence. `Fixes #123` or `Resolves #123` in a commit closes that
+   ticket when the commit reaches default-branch `main`; a bare `#123`, changelog
+   mention, tag, or GitHub release does not. Verify the resulting issue state.
+   Explicitly close completed tickets missed by automatic closure and retain
+   their implementing commit and validation references. Carry incomplete work
+   forward with its remaining criteria, then close the reconciled milestone.
+   Never infer completion from a release-note mention alone.
+
 ## Part 6: Package Publication to npm
 
 Publishing to npm is a manual maintainer step performed from the tagged commit.
@@ -195,7 +207,7 @@ Publishing to npm is a manual maintainer step performed from the tagged commit.
 3. Remove the local compact candidate branch:
 
    ```bash
-   git branch -d v044
+   git branch -d v046
    ```
 
    The canonical repository remains in its steady state containing only `main` and immutable tags.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.5",
+	"version": "0.4.6",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",

package/src/cli/ask.ts

@@ -1,10 +1,13 @@
 import type { createInterface } from "node:readline/promises";
 
-export async function ask(
-	rl: ReturnType<typeof createInterface>,
-	label: string,
-	defaultValue?: string,
-): Promise<string | null> {
+type QuestionReader = Pick<ReturnType<typeof createInterface>, "question"> & {
+	interactive?: boolean;
+	text?: (label: string, initial?: string) => Promise<string>;
+	choose?: (label: string, choices: ReadonlyArray<string>, current: string) => Promise<string>;
+};
+
+export async function ask(rl: QuestionReader, label: string, defaultValue?: string): Promise<string | null> {
+	if (rl.text) return rl.text(label, defaultValue);
 	const suffix = defaultValue && defaultValue.length > 0 ? ` [${defaultValue}]` : "";
 	try {
 		const answer = (await rl.question(`${label}${suffix}: `)).trim();
@@ -16,11 +19,8 @@ export async function ask(
 	}
 }
 
-export async function askYesNo(
-	rl: ReturnType<typeof createInterface>,
-	label: string,
-	defaultValue: boolean,
-): Promise<boolean> {
+export async function askYesNo(rl: QuestionReader, label: string, defaultValue: boolean): Promise<boolean> {
+	if (rl.choose && rl.interactive) return (await rl.choose(label, ["yes", "no"], defaultValue ? "yes" : "no")) === "yes";
 	const marker = defaultValue ? "Y/n" : "y/N";
 	for (;;) {
 		const answer = await ask(rl, `${label} [${marker}]`);

package/src/cli/configure-editor.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "yaml";
+import { SettingsValidationError, settingsPath, validateSettings, withSettingsLock } from "../core/config.js";
+import { DEFAULT_SETTINGS_YAML } from "../core/defaults.js";
+import { editTextExternally, resolveExternalEditor } from "../core/external-editor.js";
+import { safeResourceWrite } from "../core/safe-resource-write.js";
+import type { ConfigurePrompts } from "./configure-prompts.js";
+
+/** Edit a draft, validate it, then replace the file only if it has not changed meanwhile. */
+export async function editSettings(prompts: ConfigurePrompts): Promise<boolean> {
+	const file = settingsPath();
+	const original = existsSync(file) ? readFileSync(file, "utf8") : null;
+	let draft = original ?? DEFAULT_SETTINGS_YAML;
+	const editor = resolveExternalEditor();
+	for (;;) {
+		const result = editTextExternally(draft, editor, ".yaml");
+		if (!result.ok || result.text === undefined) throw new Error(result.error ?? "Editor did not return a draft");
+		draft = `${result.text}\n`;
+		if (draft === original) {
+			prompts.output.write("Settings unchanged.\n");
+			return false;
+		}
+		try {
+			const validated = validateSettings(parse(draft));
+			if (validated.issues.length) throw new SettingsValidationError(validated.issues);
+		} catch (error) {
+			prompts.output.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			if (
+				(await prompts.choose("Invalid draft", ["Return to editor", "Discard draft"], "Return to editor")) ===
+				"Return to editor"
+			)
+				continue;
+			return false;
+		}
+		const choice = await prompts.choose(
+			"Save validated settings?",
+			["Save", "Return to editor", "Discard draft"],
+			"Save",
+		);
+		if (choice === "Return to editor") continue;
+		if (choice !== "Save") return false;
+		withSettingsLock(() => {
+			const current = existsSync(file) ? readFileSync(file, "utf8") : null;
+			if (current !== original)
+				throw new Error("Settings changed while the editor was open. Reopen the editor to keep those changes.");
+			safeResourceWrite(file, draft, { encoding: "utf8", mode: 0o644, backup: original !== null });
+		});
+		prompts.output.write(`Settings saved to ${file}${original === null ? "" : `; previous file: ${file}.bak`}\n`);
+		return true;
+	}
+}

package/src/cli/configure-interop.ts

@@ -48,7 +48,7 @@ export interface InteropReviewStreams {
 
 export interface InteropReviewIo {
 	/** Readline interface for the numbered fallback. Null means nothing can answer. */
-	rl: ReturnType<typeof createInterface> | null;
+	rl: Pick<ReturnType<typeof createInterface>, "question"> | null;
 	streams?: InteropReviewStreams;
 	/** Rail to draw on when the caller already owns one. */
 	presenter?: LifecyclePresenter;

package/src/cli/configure-oauth.ts

@@ -15,7 +15,7 @@ import { promptOAuthSelection } from "./oauth-select.js";
 import { credentialWriteFailed, printError, printOk } from "./shared.js";
 
 export async function loginOAuthRuntime(
-	rl: ReturnType<typeof createInterface>,
+	rl: Pick<ReturnType<typeof createInterface>, "question">,
 	runtime: RuntimeDescriptor,
 ): Promise<boolean> {
 	const auth = openAuthStorage();