pi-soly 2.1.4 → 2.2.0

package/built-in-rules/temp-files.md

@@ -0,0 +1,173 @@
+# Temporary Files Rule
+
+> **OS-aware temp paths.** Never hardcode `/tmp` — it's wrong on Windows
+> (`%TEMP%` resolves to `C:\Users\<user>\AppData\Local\Temp`, not `/tmp`),
+> wrong on macOS (`$TMPDIR` is per-user, e.g. `/var/folders/xx/yy/T/`),
+> and fragile in multi-tenant / CI scenarios. Always resolve the
+> OS-correct temp dir at runtime and put files under a project-scoped
+> subfolder.
+
+## The rule
+
+When creating temporary files — intermediate build artifacts, scratch
+data, debug dumps, test fixtures, atomic-write staging, anything that
+isn't meant to outlive the process:
+
+1. **Resolve the OS temp dir at runtime.** Never hardcode `/tmp`,
+   `/var/folders`, `C:\Temp`, `~/tmp`, or any other literal path.
+2. **Use a project-scoped subfolder** like `<tempdir>/<project>-<hash>/`
+   so multiple projects don't collide and cleanup is easy.
+3. **Clean up after yourself** — when the work is done, remove the
+   directory (or use `try`/`finally` / `trap EXIT` / `defer`).
+4. **Prefer atomic-write patterns** for files that will be renamed into
+   place: write to a temp file in the **same directory** as the target,
+   `fsync` if durability matters, then rename. Avoids half-written
+   files on crash and avoids cross-device rename failures.
+
+## How to get the temp dir per runtime
+
+| Runtime       | API                          | Notes                              |
+|---------------|------------------------------|------------------------------------|
+| Node.js / Bun | `os.tmpdir()`                | already OS-aware; returns absolute |
+| Python        | `tempfile.gettempdir()`      | stdlib                             |
+| Go            | `os.TempDir()`               | stdlib                             |
+| Rust          | `std::env::temp_dir()`       | stdlib; returns `PathBuf`          |
+| .NET          | `Path.GetTempPath()`         | returns trailing slash              |
+| Java          | `System.getProperty("java.io.tmpdir")` | JVM-resolved            |
+| Bash (POSIX)  | `${TMPDIR:-/tmp}`            | fallback only if env unset          |
+| PowerShell    | `$env:TEMP`                  | Windows                            |
+| cmd.exe       | `%TEMP%`                     | Windows                            |
+
+**Do not** `cd /tmp && touch foo`. Use the API for the runtime you're in.
+
+## Why this matters
+
+- **Windows**: `C:\Temp` may not exist or be writable; the real temp is
+  `C:\Users\<user>\AppData\Local\Temp`. Hardcoding `/tmp` either fails
+  outright or pollutes the wrong location.
+- **macOS**: `$TMPDIR` is per-user and changes per reboot. `/tmp` is a
+  shared system directory, not appropriate for app scratch data.
+- **Linux / multi-user**: `/tmp` is shared across users on the host.
+  Mixing files across users is a data-leak / collision risk.
+- **CI/CD**: runners typically wipe `/tmp` between jobs but leave the
+  per-user temp dir intact, so using the right dir keeps artifacts
+  available for inspection post-run.
+- **Sandboxing**: macOS sandbox and certain Linux sandboxes redirect
+  `/tmp` to a per-process private dir. The runtime API follows these
+  redirects; hardcoded `/tmp` does not.
+
+## Examples
+
+### Node.js / Bun
+
+```ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const projectId = "pi-soly"; // or hash(repoUrl) for uniqueness
+const scratchDir = path.join(os.tmpdir(), `${projectId}-${process.pid}`);
+fs.mkdirSync(scratchDir, { recursive: true });
+
+try {
+  // ... use scratchDir for intermediate files ...
+} finally {
+  fs.rmSync(scratchDir, { recursive: true, force: true });
+}
+```
+
+For atomic writes to a target file:
+
+```ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+function atomicWrite(target: string, data: string | Uint8Array): void {
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.${path.basename(target)}.${process.pid}.tmp`);
+  const fh = fs.openSync(tmp, "w");
+  try {
+    fs.writeSync(fh, data);
+    fs.fsyncSync(fh);
+  } finally {
+    fs.closeSync(fh);
+  }
+  fs.renameSync(tmp, target); // atomic on same filesystem
+}
+```
+
+### Python
+
+```python
+import shutil
+import tempfile
+
+scratch = tempfile.mkdtemp(prefix="myproject-")
+try:
+    # ... use scratch ...
+    pass
+finally:
+    shutil.rmtree(scratch, ignore_errors=True)
+
+# Atomic write:
+import os
+def atomic_write(path: str, data: bytes) -> None:
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "wb") as f:
+        f.write(data)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+```
+
+### Bash (POSIX: Linux / macOS)
+
+```bash
+SCRATCH="${TMPDIR:-/tmp}/myproject-$$"
+mkdir -p "$SCRATCH"
+trap 'rm -rf "$SCRATCH"' EXIT
+# ... work in "$SCRATCH" ...
+```
+
+### PowerShell (Windows)
+
+```powershell
+$scratch = Join-Path $env:TEMP "myproject-$PID"
+New-Item -ItemType Directory -Path $scratch -Force | Out-Null
+try {
+    # ... work in $scratch ...
+} finally {
+    Remove-Item -Recurse -Force $scratch -ErrorAction SilentlyContinue
+}
+```
+
+## Forbidden patterns
+
+```ts
+// ❌ Hardcoded path — breaks on Windows, breaks sandboxing
+const dir = "/tmp/myapp";
+const dir = "C:\\Temp\\myapp";
+const dir = path.join("/tmp", "myapp");
+
+// ❌ mkdir without cleanup — leaks across runs
+fs.mkdirSync("/tmp/myapp", { recursive: true });
+// ... no rmSync ...
+
+// ❌ Atomic write to /tmp when target is elsewhere — cross-device rename fails
+const tmp = `/tmp/${path.basename(target)}`;
+fs.writeFileSync(tmp, data);
+fs.renameSync(tmp, target); // EXDEV on different filesystems
+
+// ✓ Correct: resolve temp dir at runtime, project-scoped, cleaned up
+const dir = path.join(os.tmpdir(), `${projectId}-${process.pid}`);
+fs.mkdirSync(dir, { recursive: true });
+try { /* work */ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+```
+
+## Override
+
+This rule is **built-in to the soly extension** and ships with every
+install. It has highest priority and cannot be overridden by user rules.
+If you need a different convention, name your rule differently
+(e.g., `temp-files-windows-only.md` so the paths don't collide).

package/commands.ts

@@ -44,7 +44,8 @@ import {
 } from "./intent.ts";
 import type { SolyConfig } from "./config.ts";
 import { initSolyProject } from "./init.js";
-import { ListPanel, type ListItem, type ListAction } from "./visual/list-panel.ts";
+import { ListPanel, type ListItem, type ListAction, type ListGroup } from "./visual/list-panel.ts";
+import { openSettingsUI } from "./workflows/settings-ui.ts";
 import { getArtifactServer, ensureArtifactServer, artifactDir } from "./artifact/session.ts";
 import { parseSolyCommand, type SolyCommand, type WorkflowVerb } from "./workflows/parser.ts";
 import { buildNewTransform } from "./workflows/new.ts";
@@ -69,16 +70,17 @@ export interface CommandsDeps {
 	refreshState: () => void;
 	updateStatus: (ui: CommandUI) => void;
 	getConfig: () => SolyConfig;
+	reloadConfig: () => void;
 	getIntentDocs: () => IntentDoc[];
 }
 
-/** Open a focused list modal (overlay) for the given items + actions. */
+/** Open a focused list modal (overlay) for the given grouped items. */
 async function openListPanel(
 	ctx: ExtensionCommandContext,
 	spec: {
 		title: string;
 		headerRight?: string;
-		build: () => ListItem[];
+		build: () => ListGroup[];
 		actions?: ListAction[];
 		onSelect?: (item: ListItem) => void;
 	},
@@ -92,7 +94,7 @@ async function openListPanel(
 				done: () => done(),
 				title: spec.title,
 				headerRight: spec.headerRight,
-				items: spec.build(),
+				groups: spec.build(),
 				actions: spec.actions,
 				refresh: spec.build,
 				onSelect: spec.onSelect,
@@ -180,7 +182,9 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 					await openListPanel(ctx, {
 						title: "soly · rules",
 						headerRight: `${getRules().length} rules · ${formatTok(analytics.totalTokens)} · ${analytics.contextBudgetPct.toFixed(1)}%`,
-						build: () => getRules().map(ruleItem),
+						build: () => [
+							{ id: "rules", title: "Rules", icon: "▤", items: getRules().map(ruleItem) },
+						],
 						actions: [
 							{ key: "e", hint: "enable", run: (it) => { const r = getRules().find((x) => x.relPath === it.id); if (r) r.enabled = true; } },
 							{ key: "d", hint: "disable", run: (it) => { const r = getRules().find((x) => x.relPath === it.id); if (r) r.enabled = false; } },
@@ -458,14 +462,20 @@ What must the LLM do?
 					await openListPanel(ctx, {
 						title: "soly · docs",
 						headerRight: `${docs.length} docs · ${formatTok(total)}`,
-						build: () =>
-							getIntentDocs().map((d) => ({
-								id: d.relPath,
-								marker: "○",
-								label: d.title || d.relPath,
-								meta: `${d.kind} · ${formatTok(d.tokens)} tok${d.oversized ? " · oversized" : ""}`,
-								body: d.preview,
-							})),
+						build: () => [
+							{
+								id: "docs",
+								title: "Docs",
+								icon: "☖",
+								items: getIntentDocs().map((d) => ({
+									id: d.relPath,
+									marker: "○",
+									label: d.title || d.relPath,
+									meta: `${d.kind} · ${formatTok(d.tokens)} tok${d.oversized ? " · oversized" : ""}`,
+									body: d.preview,
+								})),
+							},
+						],
 					});
 					return;
 				}
@@ -488,10 +498,7 @@ What must the LLM do?
 	// /soly  (also hosts `/soly init` — see the early dispatch in the handler)
 	// ============================================================================
 
-	pi.registerCommand("soly", {
-		description:
-			"soly: project state inspection (position, plan, state, phases, etc.) — type 'help' for subcommand picker",
-		handler: async (args, ctx) => {
+	const solyBody = async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
 			const ui: CommandUI = {
 				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
 				select: async (label, options) => {
@@ -860,6 +867,25 @@ What must the LLM do?
 					description: "one-shot: import .agents/phases/<NN>-<slug>/plans/PLAN.md as plan branches",
 					run: () => runWorkflow("migrate", [], ctx, ui),
 				},
+				where: {
+					description: "alias for `position` — current position + progress",
+					run: (parts) => {
+						const p = subcommands.position;
+						if (p) void p.run(parts);
+					},
+				},
+				settings: {
+					description: "interactive config editor (toggles, enums, numbers)",
+					run: () => {
+						openSettingsUI({
+							ctx,
+							ui,
+							solyDir: state.solyDir,
+							getConfig,
+							reloadConfig: deps.reloadConfig,
+						});
+					},
+				},
 			};
 
 			// Single-width BMP glyphs only — astral/VS16 emoji are mis-measured by
@@ -869,6 +895,7 @@ What must the LLM do?
 				research: "⊙", roadmap: "≣", progress: "▰",
 				phases: "▭", tasks: "✓", task: "◍",
 				features: "★", milestone: "◈", reload: "↻", config: "▣",
+				settings: "⚙", where: "◎",
 			};
 
 			// Short live preview shown in the modal's preview pane per subcommand.
@@ -878,6 +905,7 @@ What must the LLM do?
 				const phaseFile = (suffix: string) =>
 					s.currentPhase ? readIfExists(path.join(s.currentPhase.dir, `${s.currentPhase.slug}-${suffix}.md`)) : null;
 				switch (name) {
+					case "where": return s.position ? `${s.position.phase} · ${s.position.plan} · ${s.position.status} · ${s.progress.percent}%` : `${s.milestone} — no position set`;
 					case "position": return s.position ? `${s.position.phase} · ${s.position.plan} · ${s.position.status} · ${s.progress.percent}%` : `${s.milestone} — no position set`;
 					case "progress": return `${s.progress.percent}% · ${s.progress.completedPhases}/${s.progress.totalPhases} phases · ${s.progress.completedPlans}/${s.progress.totalPlans} plans`;
 					case "phases": return s.phases.length ? s.phases.map((p) => `${p.number}.${p.name}`).join(" · ") : "no phases";
@@ -889,20 +917,55 @@ What must the LLM do?
 					case "plan": return s.currentPlanPath ? teaser(readIfExists(s.currentPlanPath)) : "no current plan";
 					case "context": return s.currentPhase ? teaser(phaseFile("CONTEXT")) || "CONTEXT.md not found" : "no current phase";
 					case "research": return s.currentPhase ? teaser(phaseFile("RESEARCH")) || "RESEARCH.md not found" : "no current phase";
-					case "config": return "merged config — press ⏎ to view the JSON";
+					case "settings": return "interactive config editor — toggles, enums, numbers";
+					case "config": return "merged config JSON (read-only view)";
 					case "reload": return "re-read project state from disk";
 					default: return subcommands[name]?.description ?? "";
 				}
 			};
 
-			const solyItems = (): ListItem[] =>
-				Object.keys(subcommands).map((name) => ({
-					id: name,
-					marker: ICONS[name] ?? "▸",
-					label: name,
-					meta: subcommands[name]!.description,
-					body: previewFor(name),
-				}));
+			// Top-to-bottom group order in the /soly modal. Items in
+			// `items[]` show in declaration order; subcommands not listed here
+			// still work via `/soly <name>` directly but don't appear in the picker.
+			const SOLY_GROUP_ORDER = ["status", "inspect", "manage"] as const;
+			const SOLY_GROUPS: Record<string, { id: string; title: string; icon: string; items: string[] }> = {
+				status: {
+					id: "status",
+					title: "Status",
+					icon: "▰",
+					items: ["where", "progress"],
+				},
+				inspect: {
+					id: "inspect",
+					title: "Inspect",
+					icon: "▤",
+					items: ["plan", "state", "roadmap", "context", "phases", "tasks", "milestone"],
+				},
+				manage: {
+					id: "manage",
+					title: "Manage",
+					icon: "⚙",
+					items: ["settings", "reload", "config"],
+				},
+			};
+
+			const solyGroups = (): ListGroup[] =>
+				SOLY_GROUP_ORDER.map((gid) => {
+					const def = SOLY_GROUPS[gid]!;
+					const items: ListItem[] = [];
+					for (const name of def.items) {
+						const spec = subcommands[name];
+						if (!spec) continue;
+						items.push({
+							id: name,
+							marker: ICONS[name] ?? "▸",
+							label: name,
+							meta: spec.description,
+							body: previewFor(name),
+						});
+					}
+					return { id: def.id, title: def.title, icon: def.icon, items };
+				}).filter((g) => g.items.length > 0);
 
 			// Plain-select fallback for non-TUI (RPC/print) modes.
 			const picker = async (label: string) => {
@@ -920,8 +983,8 @@ What must the LLM do?
 				const s = getState();
 				await openListPanel(ctx, {
 					title: "soly · state",
-					headerRight: `${s.phases.length} phases · ${s.progress.percent}%`,
-					build: solyItems,
+					headerRight: `${s.phases.length} phases · ${s.progress.percent}% · /sly /s`,
+					build: solyGroups,
 					onSelect: (it) => {
 						void subcommands[it.id]?.run([it.id]);
 					},
@@ -942,7 +1005,21 @@ What must the LLM do?
 			}
 
 			await subcommands[sub].run(parts);
-		},
+	};
+	pi.registerCommand("soly", {
+		description:
+			"soly: project state inspection (position, plan, state, phases, etc.) — type 'help' for subcommand picker",
+		handler: solyBody,
+	});
+	// Short aliases — same body, three names. /sly is the typing-friendly form;
+	// /s is the speed-freak form.
+	pi.registerCommand("sly", {
+		description: "alias for /soly",
+		handler: solyBody,
+	});
+	pi.registerCommand("s", {
+		description: "alias for /soly",
+		handler: solyBody,
 	});
 	// ============================================================================
 	// /artifacts — browse this session's html_artifact gallery
@@ -990,14 +1067,20 @@ What must the LLM do?
 					title: "soly · artifacts",
 					// BMP-only header (no long URL — it overflowed the bar). Count only.
 					headerRight: `${server.count} artifact${server.count === 1 ? "" : "s"}`,
-					build: () =>
-						(getArtifactServer()?.list() ?? []).map((a) => ({
-							id: a.id,
-							marker: "▦", // BMP glyph — an astral emoji (🖼) breaks ListPanel width
-							label: a.title,
-							meta: new Date(a.createdAt).toLocaleTimeString(),
-							body: a.url,
-						})),
+					build: () => [
+						{
+							id: "artifacts",
+							title: "Artifacts",
+							icon: "▦",
+							items: (getArtifactServer()?.list() ?? []).map((a) => ({
+								id: a.id,
+								marker: "▦", // BMP glyph — an astral emoji (🖼) breaks ListPanel width
+								label: a.title,
+								meta: new Date(a.createdAt).toLocaleTimeString(),
+								body: a.url,
+							})),
+						},
+					],
 					onSelect: (it) => {
 						const a = getArtifactServer()?.list().find((x) => x.id === it.id);
 						if (a) void openExternally(pi, a.url);

package/core.ts

@@ -573,17 +573,26 @@ export function buildRulesSection(
     if (r.interactiveOnly) interactive.push(r.relPath);
   }
 
+  // Split into built-in (shipped with soly) vs project/user rules. The two
+  // groups render in two distinct sections so the LLM can see the priority
+  // structure at a glance: vendor rules at the top (cannot be overridden),
+  // user rules below (can be edited locally).
+  const builtInRules = applicable.filter((r) => r.source === "built-in");
+  const userRules = applicable.filter((r) => r.source !== "built-in");
+
   // Optional grouping: phase rules in their own group, then everything else.
-  let blocks: string[];
+  // Phase grouping only applies to user rules — built-in rules are always
+  // always-on and don't move with phases.
+  let userBlocks: string[];
   let headerHint: string;
   if (options?.groupByPhase) {
     const phase = options.phaseNumber;
-    const phaseRules = applicable.filter((r) => r.phaseNumber === phase);
-    const otherRules = applicable.filter((r) => r.phaseNumber !== phase);
-    blocks = [...phaseRules.map(render), ...otherRules.map(render)];
+    const phaseRules = userRules.filter((r) => r.phaseNumber === phase);
+    const otherRules = userRules.filter((r) => r.phaseNumber !== phase);
+    userBlocks = [...phaseRules.map(render), ...otherRules.map(render)];
     headerHint = `Phase ${phase} rules are loaded for the currently active phase; all other rules are always-on. Inline @see references are resolved recursively.`;
   } else {
-    blocks = applicable.map(render);
+    userBlocks = userRules.map(render);
     headerHint = `The following rules are loaded from \`.agents/rules/\` and \`~/.agents/rules/\` and are mandatory. Follow them strictly. Inline @see references are resolved recursively.`;
   }
 
@@ -593,7 +602,26 @@ export function buildRulesSection(
         .join(", ")}_`
     : "";
 
-  const section = `
+  // Built-in section (shipped with soly, cannot be overridden).
+  // Renders ABOVE the MANDATORY project-rules section so the LLM sees the
+  // vendor content first, with a stronger "this is system-managed" framing.
+  const builtInSection = builtInRules.length
+    ? `
+
+## 🔒 Built-in rules (shipped with soly)
+
+**The following rules ship with the soly extension and apply to every
+session.** They are the highest-priority rules and cannot be overridden
+by user rules in \`.agents/rules/\` or \`~/.agents/rules/\` (a user rule
+at the same relPath is dropped silently). Follow them strictly.
+
+${builtInRules.map(render).join("\n\n---\n\n")}
+`
+    : "";
+
+  // Project/user rules section (the existing MANDATORY contract).
+  const projectSection = userBlocks.length
+    ? `
 
 ## ⚠️ MANDATORY: soly project rules
 
@@ -601,8 +629,11 @@ export function buildRulesSection(
 
 ${headerHint}
 
-${blocks.join("\n\n---\n\n")}${skippedNote}
-`;
+${userBlocks.join("\n\n---\n\n")}${skippedNote}
+`
+    : "";
+
+  const section = builtInSection + projectSection;
 
   return { section, loaded: applicable.map(ruleKey), interactive };
 }

package/index.ts

@@ -375,6 +375,15 @@ export default function solyExtension(pi: ExtensionAPI) {
 		refreshState: () => refreshState(),
 		updateStatus: (ui) => updateStatus(ui),
 		getConfig: getActiveConfig,
+		reloadConfig: () => {
+			if (!sessionCwd) return;
+			const cfgResult = loadConfig(sessionCwd);
+			activeConfig = cfgResult.config;
+			// Re-warn about config drift (mirrors the warnings at session_start).
+			for (const w of cfgResult.warnings) {
+				pi.sendUserMessage?.(`soly: ${w}`, { deliverAs: "followUp" });
+			}
+		},
 		getIntentDocs: () => intentDocs,
 	});
 

package/mcp/mcp-panel.ts

@@ -1,5 +1,5 @@
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "./panel-keys.ts";
+import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "../visual/panel-keys.ts";
 import { isToolExcluded } from "./types.ts";
 import type { McpConfig, McpPanelCallbacks, McpPanelResult, ServerProvenance } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";

package/mcp/mcp-setup-panel.ts

@@ -1,5 +1,5 @@
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "./panel-keys.ts";
+import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "../visual/panel-keys.ts";
 import type { ImportKind } from "./types.ts";
 import type { ConfigWritePreview, McpDiscoverySummary } from "./config.ts";
 import type { McpOnboardingState } from "./onboarding-state.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives the workflow inline via the soly_workflow tool — no external subagent plugin.",
   "type": "module",
   "main": "index.ts",
@@ -60,7 +60,8 @@
     "init.ts",
     "codemap.ts",
     "state.ts",
-    "hotreload.ts"
+    "hotreload.ts",
+    "built-in-rules"
   ],
   "keywords": [
     "pi",

package/visual/list-panel.ts

@@ -15,26 +15,42 @@
 import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "../mcp/panel-keys.ts";
+import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "./panel-keys.ts";
+// (PanelKeybindings re-exported by re-export side below.)
 
 /** One row in the panel. `body` is shown in the preview pane when selected. */
 export type ListItem = { id: string; marker: string; label: string; meta?: string; body?: string };
 
+/** A logical group within the panel (rendered as a labelled separator). */
+export type ListGroup = {
+	id: string;
+	/** Single glyph + short title shown on the separator row (e.g. "📊 Status"). */
+	title: string;
+	icon: string;
+	items: ListItem[];
+};
+
 /** A key-triggered action over the selected item (e.g. enable/disable/reload). */
 export type ListAction = { key: string; hint: string; run: (item: ListItem) => void };
 
+// Re-export PanelKeybindings so consumers don't need to know about the
+// internal ./panel-keys.ts module.
+export type { PanelKeybindings, PanelKeys };
+
 export type ListPanelProps = {
 	tui: TUI;
 	theme: Theme;
 	keybindings?: PanelKeybindings;
+	// (Above prop is the public re-export anchor.)
 	done: () => void;
 	title: string;
 	/** Right-aligned header text (e.g. counts / token budget). */
 	headerRight?: string;
-	items: ListItem[];
+	/** Items, grouped. A single group is fine. Cursor skips group headers. */
+	groups: ListGroup[];
 	actions?: ListAction[];
 	/** Re-read items after an action mutates state. */
-	refresh?: () => ListItem[];
+	refresh?: () => ListGroup[];
 	/** Fired on Enter for the selected item; the panel then closes. When set,
 	 *  the footer shows an "⏎ open" hint. */
 	onSelect?: (item: ListItem) => void;
@@ -54,17 +70,20 @@ function fuzzyScore(query: string, text: string): number {
 	return qi === q.length ? 1 : 0;
 }
 
+/** Index into `flatRows` (mixed item + group header rows). */
+type RowIndex = number;
+
 export class ListPanel implements Component {
 	private readonly p: ListPanelProps;
 	private readonly keys: PanelKeys;
-	private items: ListItem[];
+	private groups: ListGroup[];
 	private query = "";
 	private searching = false;
-	private selected = 0;
+	private selected: RowIndex = 0;
 
 	constructor(props: ListPanelProps) {
 		this.p = props;
-		this.items = props.items;
+		this.groups = props.groups;
 		this.keys = createPanelKeys(props.keybindings);
 	}
 
@@ -72,22 +91,65 @@ export class ListPanel implements Component {
 		/* stateless cache */
 	}
 
-	private filtered(): ListItem[] {
-		if (!this.query) return this.items;
-		return this.items
-			.map((it) => ({ it, s: fuzzyScore(this.query, `${it.label} ${it.meta ?? ""}`) }))
-			.filter((x) => x.s > 0)
-			.sort((a, b) => b.s - a.s)
-			.map((x) => x.it);
+	/** Flatten groups into rows (items + header separators). Headers carry a
+	 *  `group` reference for rendering; cursor skips them. */
+	private flatRows(): Array<{ kind: "item"; item: ListItem; group: ListGroup } | { kind: "header"; group: ListGroup }> {
+		const out: Array<{ kind: "item"; item: ListItem; group: ListGroup } | { kind: "header"; group: ListGroup }> = [];
+		for (const g of this.groups) {
+			// Skip groups that have no items — no point showing an empty separator.
+			if (g.items.length === 0) continue;
+			out.push({ kind: "header", group: g });
+			for (const item of g.items) out.push({ kind: "item", item, group: g });
+		}
+		return out;
 	}
 
-	private clamp(list: ListItem[]): void {
-		if (this.selected >= list.length) this.selected = Math.max(0, list.length - 1);
+	/** Apply fuzzy filter; when searching, group headers are still shown but
+	 *  only groups that contain at least one matching item survive, and
+	 *  within those groups only matching items are returned. */
+	private filteredRows(): Array<{ kind: "item"; item: ListItem; group: ListGroup } | { kind: "header"; group: ListGroup }> {
+		if (!this.query) return this.flatRows();
+		const q = this.query.toLowerCase();
+		const matchedByGroup = new Map<ListGroup, Set<ListItem>>();
+		for (const g of this.groups) {
+			const matched = new Set<ListItem>();
+			for (const it of g.items) {
+				if (fuzzyScore(q, `${it.label} ${it.meta ?? ""}`) > 0) matched.add(it);
+			}
+			if (matched.size > 0) matchedByGroup.set(g, matched);
+		}
+		const out: Array<{ kind: "item"; item: ListItem; group: ListGroup } | { kind: "header"; group: ListGroup }> = [];
+		for (const g of this.groups) {
+			const matched = matchedByGroup.get(g);
+			if (!matched) continue;
+			out.push({ kind: "header", group: g });
+			for (const it of g.items) if (matched.has(it)) out.push({ kind: "item", item: it, group: g });
+		}
+		return out;
+	}
+
+	private clamp(list: { kind: "item" | "header" }[]): void {
+		if (list.length === 0) {
+			this.selected = 0;
+			return;
+		}
+		// First clamp into valid range.
+		if (this.selected >= list.length) this.selected = list.length - 1;
 		if (this.selected < 0) this.selected = 0;
+		// Then walk to the nearest non-header row — prefer forward (visual
+		// scan direction), fall back to backward.
+		if (list[this.selected]?.kind === "header") {
+			for (let i = this.selected; i < list.length; i++) {
+				if (list[i]?.kind === "item") { this.selected = i; return; }
+			}
+			for (let i = this.selected; i >= 0; i--) {
+				if (list[i]?.kind === "item") { this.selected = i; return; }
+			}
+		}
 	}
 
 	handleInput(data: string): void {
-		const list = this.filtered();
+		const list = this.filteredRows();
 		this.clamp(list);
 
 		if (this.searching) {
@@ -109,23 +171,28 @@ export class ListPanel implements Component {
 		}
 		if (this.keys.selectUp(data)) {
 			this.selected = Math.max(0, this.selected - 1);
+			// Skip group headers when moving up.
+			while (this.selected > 0 && list[this.selected]?.kind === "header") this.selected--;
 		} else if (this.keys.selectDown(data)) {
 			this.selected = Math.min(list.length - 1, this.selected + 1);
+			// Skip group headers when moving down.
+			while (this.selected < list.length - 1 && list[this.selected]?.kind === "header") this.selected++;
 		} else if (data === "/") {
 			this.searching = true;
 		} else if (matchesKey(data, "return")) {
 			const current = list[this.selected];
-			if (this.p.onSelect && current) {
-				this.p.onSelect(current);
+			// Headers are not selectable — ignore Enter on them.
+			if (current && current.kind === "item" && this.p.onSelect) {
+				this.p.onSelect(current.item);
 				this.p.done();
 				return;
 			}
 		} else {
 			const action = this.p.actions?.find((a) => a.key === data);
 			const current = list[this.selected];
-			if (action && current) {
-				action.run(current);
-				if (this.p.refresh) this.items = this.p.refresh();
+			if (action && current && current.kind === "item") {
+				action.run(current.item);
+				if (this.p.refresh) this.groups = this.p.refresh();
 			}
 		}
 		this.p.tui.requestRender();
@@ -136,7 +203,7 @@ export class ListPanel implements Component {
 		const dim = (s: string) => theme.fg("dim", s);
 		const muted = (s: string) => theme.fg("muted", s);
 		const inner = Math.max(20, width - 4);
-		const list = this.filtered();
+		const list = this.filteredRows();
 		this.clamp(list);
 
 		const out: string[] = [];
@@ -144,19 +211,39 @@ export class ListPanel implements Component {
 		out.push(this.searchLine(inner, dim, muted));
 		out.push(this.frame("", inner, dim));
 
-		// Windowed list around the selection.
+		// Windowed view around the selection.
+		const selectedRow = list[this.selected];
 		const start = Math.max(0, Math.min(this.selected - Math.floor(MAX_ROWS / 2), Math.max(0, list.length - MAX_ROWS)));
 		const window = list.slice(start, start + MAX_ROWS);
 		if (window.length === 0) out.push(this.frame(dim("  (no matches)"), inner, dim));
-		for (let i = 0; i < window.length; i++) out.push(this.rowLine(window[i] as ListItem, start + i === this.selected, inner, dim, muted));
+		for (let i = 0; i < window.length; i++) {
+			const r = window[i];
+			if (!r) continue;
+			const absoluteIdx = start + i;
+			if (r.kind === "header") {
+				out.push(this.groupHeaderLine(r.group, inner, dim, muted));
+			} else {
+				const sel = absoluteIdx === this.selected && selectedRow?.kind === "item";
+				out.push(this.rowLine(r.item, sel, inner, dim, muted));
+			}
+		}
 
+		// Preview shows the selected item only — headers have no preview.
 		out.push(this.ruleLine("preview", inner, dim));
-		for (const line of this.previewLines(list[this.selected], inner)) out.push(this.frame("  " + muted(line), inner, dim));
+		const previewItem = selectedRow?.kind === "item" ? selectedRow.item : undefined;
+		for (const line of this.previewLines(previewItem, inner)) out.push(this.frame("  " + muted(line), inner, dim));
 
 		out.push(this.footerLine(inner, dim));
 		return out;
 	}
 
+	/** Full-width separator row: `📊 Status ─────────`. */
+	private groupHeaderLine(g: ListGroup, inner: number, dim: (s: string) => string, muted: (s: string) => string): string {
+		const head = ` ${dim(g.icon)} ${muted(g.title)} `;
+		const dashes = Math.max(0, inner - visibleWidth(head));
+		return dim(`│${head}${"─".repeat(dashes)} │`);
+	}
+
 	private frame(content: string, inner: number, dim: (s: string) => string): string {
 		const pad = Math.max(0, inner - visibleWidth(content));
 		return dim("│ ") + content + " ".repeat(pad) + dim(" │");

package/workflows/settings-ui.ts

@@ -0,0 +1,466 @@
+// =============================================================================
+// workflows/settings-ui.ts — interactive soly settings editor
+// =============================================================================
+//
+// Modal that lets the user toggle/cycle/± soly config values instead of
+// reading a JSON dump in chat. Lives as a focused overlay panel built on
+// the ListPanel primitive (same shape as the /soly and /rules pickers).
+//
+// Settings shape:
+//   - bool   : row marker flips ◉/○ on Enter; current value shown in meta
+//   - enum   : row marker shows the current value; Enter cycles to next
+//   - number : row marker shows current value; + / - (also ← / →) step by 1
+//
+// Saving: each change is committed in-memory. On panel close (Esc), the
+// full diff vs the original is written to `<solyDir>/soly.json` (the
+// per-project config file). Global overrides at `~/.agents/soly.json`
+// are left alone — pass `--scope global` in a future iteration to target
+// that path; today the editor is project-scoped only.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { ListPanel, type ListItem, type ListAction, type ListGroup, type PanelKeybindings } from "../visual/list-panel.ts";
+
+import { DEFAULT_CONFIG, type SolyConfig } from "../config.ts";
+
+// ---------------------------------------------------------------------------
+// Setting descriptors
+// ---------------------------------------------------------------------------
+
+type BoolSetting = {
+	kind: "bool";
+	key: string;
+	label: string;
+	description: string;
+	get: (c: SolyConfig) => boolean;
+	set: (c: SolyConfig, v: boolean) => void;
+};
+
+type EnumSetting = {
+	kind: "enum";
+	key: string;
+	label: string;
+	description: string;
+	get: (c: SolyConfig) => string;
+	set: (c: SolyConfig, v: string) => void;
+	values: readonly string[];
+};
+
+type NumberSetting = {
+	kind: "number";
+	key: string;
+	label: string;
+	description: string;
+	get: (c: SolyConfig) => number;
+	set: (c: SolyConfig, v: number) => void;
+	min: number;
+	max: number;
+	step?: number;
+};
+
+export type Setting = BoolSetting | EnumSetting | NumberSetting;
+
+function getPath(c: SolyConfig, keys: string[]): unknown {
+	let cur: unknown = c;
+	for (const k of keys) {
+		if (cur == null || typeof cur !== "object") return undefined;
+		cur = (cur as Record<string, unknown>)[k];
+	}
+	return cur;
+}
+
+function setPath<T extends object>(target: T, keys: string[], value: unknown): T {
+	const next: T = { ...target };
+	let cur: Record<string, unknown> = next as Record<string, unknown>;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const k = keys[i]!;
+		const inner = cur[k];
+		cur[k] = { ...(typeof inner === "object" && inner !== null ? inner : {}) };
+		cur = cur[k] as Record<string, unknown>;
+	}
+	cur[keys[keys.length - 1]!] = value;
+	return next;
+}
+
+/** Ordered list of user-editable settings shown in the modal. Complex
+ *  values (arrays, regex patterns) are intentionally omitted — see the
+ *  comments in the descriptors. */
+export const SETTINGS: Setting[] = [
+	// ---- iteration ----
+	{
+		kind: "number",
+		key: "iteration.retentionDays",
+		label: "Iteration retention",
+		description: "auto-prune iteration files older than N days (0 = keep forever)",
+		get: (c) => c.iteration.retentionDays,
+		set: (c, v) => { c.iteration = { ...c.iteration, retentionDays: v }; },
+		min: 0, max: 365,
+	},
+	{
+		kind: "bool",
+		key: "iteration.includeResearch",
+		label: "Include RESEARCH in bundle",
+		description: "add RESEARCH.md sections to the per-iteration context bundle",
+		get: (c) => c.iteration.includeResearch,
+		set: (c, v) => { c.iteration = { ...c.iteration, includeResearch: v }; },
+	},
+	{
+		kind: "bool",
+		key: "iteration.includeAntiPatterns",
+		label: "Include Anti-Patterns in bundle",
+		description: "add the Anti-Patterns table from .continue-here.md to the bundle",
+		get: (c) => c.iteration.includeAntiPatterns,
+		set: (c, v) => { c.iteration = { ...c.iteration, includeAntiPatterns: v }; },
+	},
+
+	// ---- agent ----
+	{
+		kind: "bool",
+		key: "agent.preferAskPro",
+		label: "Prefer ask_pro over picker",
+		description: "use the ask_pro multi-question tool instead of soly's built-in picker in discuss flow",
+		get: (c) => c.agent.preferAskPro,
+		set: (c, v) => { c.agent = { ...c.agent, preferAskPro: v }; },
+	},
+	{
+		kind: "bool",
+		key: "agent.toolHints",
+		label: "Per-turn tool hints",
+		description: "inject context-aware affordance hints (examples → html_artifact, options → decision_deck, …)",
+		get: (c) => c.agent.toolHints,
+		set: (c, v) => { c.agent = { ...c.agent, toolHints: v }; },
+	},
+	{
+		kind: "enum",
+		key: "agent.confirmBeforeCode",
+		label: "Confirm-before-code gate",
+		description: "before non-trivial coding, make the LLM batch decisions via ask_pro",
+		get: (c) => c.agent.confirmBeforeCode as string,
+		set: (c, v) => {
+			c.agent = { ...c.agent, confirmBeforeCode: v as SolyConfig["agent"]["confirmBeforeCode"] };
+		},
+		values: ["off", "ask", "scope"],
+	},
+
+	// ---- display ----
+	{
+		kind: "bool",
+		key: "display.defaultRecommendedFirst",
+		label: "Default to ⭐ first",
+		description: "always show the recommended option as the first row in pickers",
+		get: (c) => c.display.defaultRecommendedFirst,
+		set: (c, v) => { c.display = { ...c.display, defaultRecommendedFirst: v }; },
+	},
+	{
+		kind: "number",
+		key: "display.maxPhasesInStatus",
+		label: "Max phases in status",
+		description: "cap on how many phases appear in /soly status",
+		get: (c) => c.display.maxPhasesInStatus,
+		set: (c, v) => { c.display = { ...c.display, maxPhasesInStatus: v }; },
+		min: 1, max: 50,
+	},
+	{
+		kind: "number",
+		key: "display.maxDecisionsInLog",
+		label: "Max decisions in log",
+		description: "cap on how many decisions appear in soly log default",
+		get: (c) => c.display.maxDecisionsInLog,
+		set: (c, v) => { c.display = { ...c.display, maxDecisionsInLog: v }; },
+		min: 1, max: 500,
+	},
+
+	// ---- hotReload ----
+	{
+		kind: "number",
+		key: "hotReload.pollMs",
+		label: "Hot-reload poll interval (ms)",
+		description: "how often to check for rule changes (lower = snappier, higher = less disk I/O)",
+		get: (c) => c.hotReload.pollMs,
+		set: (c, v) => { c.hotReload = { ...c.hotReload, pollMs: v }; },
+		min: 250, max: 60_000, step: 250,
+	},
+	{
+		kind: "bool",
+		key: "hotReload.notifyOnRuleChange",
+		label: "Notify on rule changes",
+		description: "show a notify when rule files change on disk",
+		get: (c) => c.hotReload.notifyOnRuleChange,
+		set: (c, v) => { c.hotReload = { ...c.hotReload, notifyOnRuleChange: v }; },
+	},
+
+	// ---- chrome ----
+	{
+		kind: "bool",
+		key: "chrome.enabled",
+		label: "Chrome (top bar + footer)",
+		description: "install soly's status chrome (top bar + custom footer + spinner)",
+		get: (c) => c.chrome.enabled,
+		set: (c, v) => { c.chrome = { ...c.chrome, enabled: v }; },
+	},
+	{
+		kind: "bool",
+		key: "chrome.ascii",
+		label: "ASCII fallbacks (no glyphs)",
+		description: "use BMP glyphs instead of Nerd-Font icons (for terminals without font support)",
+		get: (c) => c.chrome.ascii,
+		set: (c, v) => { c.chrome = { ...c.chrome, ascii: v }; },
+	},
+	{
+		kind: "bool",
+		key: "chrome.telemetry",
+		label: "Working telemetry",
+		description: "show live elapsed · ↑↓ tokens · tok/s next to the working spinner",
+		get: (c) => c.chrome.telemetry,
+		set: (c, v) => { c.chrome = { ...c.chrome, telemetry: v }; },
+	},
+	{
+		kind: "number",
+		key: "chrome.spinnerIntervalMs",
+		label: "Spinner frame interval (ms)",
+		description: "how fast the working spinner animates",
+		get: (c) => c.chrome.spinnerIntervalMs,
+		set: (c, v) => { c.chrome = { ...c.chrome, spinnerIntervalMs: v }; },
+		min: 50, max: 1000, step: 25,
+	},
+
+	// ---- verify ----
+	{
+		kind: "bool",
+		key: "verify.freshContext",
+		label: "Fresh-context review",
+		description: "strip prior review iterations from context each pass (re-review with truly fresh eyes)",
+		get: (c) => c.verify.freshContext,
+		set: (c, v) => { c.verify = { ...c.verify, freshContext: v }; },
+	},
+	{
+		kind: "number",
+		key: "verify.maxIterations",
+		label: "Verify max iterations",
+		description: "max self-review passes before the loop stops on its own",
+		get: (c) => c.verify.maxIterations,
+		set: (c, v) => { c.verify = { ...c.verify, maxIterations: v }; },
+		min: 1, max: 20,
+	},
+
+	// ---- editor ----
+	{
+		kind: "enum",
+		key: "editor.command",
+		label: "$EDITOR command",
+		description: "command used for `/open` and edit-redirect (e.g. code, vim, code-insiders)",
+		get: (c) => c.editor.command,
+		set: (c, v) => { c.editor = { ...c.editor, command: v }; },
+		values: ["code", "code-insiders", "cursor", "vim", "nvim", "nano", "emacs", "subl", "xed"],
+	},
+];
+
+// ---------------------------------------------------------------------------
+// Modal
+// ---------------------------------------------------------------------------
+
+export type Notifier = {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+};
+
+/** Marker tokens for the row glyph. Bool: ●/○ ; enum/number: shows value. */
+function markerFor(s: Setting, value: unknown): string {
+	if (s.kind === "bool") return value ? "◉" : "○";
+	if (s.kind === "enum") {
+		const idx = s.values.indexOf(value as string);
+		return idx >= 0 ? String(idx + 1) : "?";
+	}
+	// number — show value with arrow hints
+	return String(value);
+}
+
+function displayValue(s: Setting, value: unknown): string {
+	if (s.kind === "bool") return value ? "ON" : "OFF";
+	if (s.kind === "enum") return String(value);
+	if (s.kind === "number") return String(value);
+	return String(value);
+}
+
+/** Convert a fully-resolved SolyConfig to a plain JSON-serializable object,
+ *  diffing against `DEFAULT_CONFIG` so we only persist user overrides. */
+function diffVsDefaults(c: SolyConfig): SolyConfig {
+	// We treat SolyConfig as Record<string, unknown> for the recursion since
+	// TS won't let us declare `out` as both. The fields we touch are all
+	// JSON-serializable primitives or nested objects of the same shape.
+	const out = JSON.parse(JSON.stringify(DEFAULT_CONFIG)) as unknown as Record<string, unknown>;
+	const walk = (target: Record<string, unknown>, source: Record<string, unknown>): void => {
+		for (const k of Object.keys(source)) {
+			const sv = source[k];
+			if (sv && typeof sv === "object" && !Array.isArray(sv)) {
+				if (!target[k] || typeof target[k] !== "object") target[k] = {};
+				walk(target[k] as Record<string, unknown>, sv as Record<string, unknown>);
+			} else if (!deepEqual(target[k], sv)) {
+				target[k] = sv;
+			}
+		}
+	};
+	walk(out, c as unknown as Record<string, unknown>);
+	// Strip any keys that ended up at default (empty walks leave them).
+	const prune = (target: Record<string, unknown>, source: Record<string, unknown>): void => {
+		for (const k of Object.keys(target)) {
+			const tv = target[k];
+			const sv = source[k];
+			if (tv && typeof tv === "object" && !Array.isArray(tv) && sv && typeof sv === "object") {
+				prune(tv as Record<string, unknown>, sv as Record<string, unknown>);
+				if (Object.keys(tv).length === 0) delete target[k];
+			} else if (deepEqual(tv, sv)) {
+				delete target[k];
+			}
+		}
+	};
+	prune(out, DEFAULT_CONFIG as unknown as Record<string, unknown>);
+	return out as unknown as SolyConfig;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (a === null || b === null) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (typeof a === "object") {
+		const ak = Object.keys(a as object);
+		const bk = Object.keys(b as object);
+		if (ak.length !== bk.length) return false;
+		for (const k of ak) if (!deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false;
+		return true;
+	}
+	return false;
+}
+
+/** Write `data` to `<solyDir>/soly.json`, preserving any existing top-level
+ *  keys the user has set but soly doesn't know about. */
+function saveConfigFile(solyDir: string, data: SolyConfig): void {
+	const target = path.join(solyDir, "soly.json");
+	let merged = data as unknown as Record<string, unknown>;
+	if (fs.existsSync(target)) {
+		try {
+			const raw = fs.readFileSync(target, "utf-8");
+			const existing = JSON.parse(raw) as Record<string, unknown>;
+			// Carry over unknown keys (forward-compat with future fields).
+			for (const k of Object.keys(existing)) {
+				if (!(k in merged)) merged[k] = existing[k];
+			}
+		} catch { /* corrupt file → overwrite is fine */ }
+	}
+	const mergedTyped: SolyConfig = merged as unknown as SolyConfig;
+	fs.mkdirSync(solyDir, { recursive: true });
+	fs.writeFileSync(target, JSON.stringify(mergedTyped, null, 2) + "\n", "utf-8");
+}
+
+export type SettingsUIDeps = {
+	ctx: { ui: { custom: <T>(factory: (tui: TUI, theme: Theme, keybindings: PanelKeybindings, done: (result?: T) => void) => Component & { dispose?: () => void } | Promise<Component & { dispose?: () => void }>, opts?: { overlay?: boolean } | undefined) => Promise<T | undefined> } };
+	ui: Notifier;
+	/** Where to write `<solyDir>/soly.json` (typically `state.solyDir`). */
+	solyDir: string;
+	/** Live config snapshot — re-read on every call so we pick up writes
+	 *  done by other panels in the same session. */
+	getConfig: () => SolyConfig;
+	/** Reload the live config from disk after we wrote the file. */
+	reloadConfig: () => void;
+};
+
+/** Open the interactive settings modal. Mutates `working` in memory, then
+ *  writes the diff to `<solyDir>/soly.json` on close. */
+export function openSettingsUI(deps: SettingsUIDeps): void {
+	const { ctx, ui, solyDir, getConfig, reloadConfig } = deps;
+
+	// Take a deep copy so we can mutate freely; on close, diff vs defaults
+	// and persist the override file.
+	const working: SolyConfig = JSON.parse(JSON.stringify(getConfig()));
+	const originalJson = JSON.stringify(working);
+
+	const itemFor = (s: Setting): ListItem => {
+		const v = s.get(working);
+		return {
+			id: s.key,
+			marker: markerFor(s, v),
+			label: s.label,
+			meta: displayValue(s, v),
+			body: `${s.description}\n\nkey: ${s.key}${s.kind === "enum" ? `\nvalues: ${s.values.join(" / ")}` : ""}${s.kind === "number" ? `\nrange: ${s.min}..${s.max}${s.step ? ` step ${s.step}` : ""}` : ""}`,
+		};
+	};
+
+	const buildGroups = (): ListGroup[] => [
+		{ id: "iteration", title: "Iteration", icon: "↻", items: SETTINGS.filter((s) => s.key.startsWith("iteration.")).map(itemFor) },
+		{ id: "agent", title: "Agent", icon: "◉", items: SETTINGS.filter((s) => s.key.startsWith("agent.")).map(itemFor) },
+		{ id: "display", title: "Display", icon: "▤", items: SETTINGS.filter((s) => s.key.startsWith("display.")).map(itemFor) },
+		{ id: "reload", title: "Hot reload", icon: "↺", items: SETTINGS.filter((s) => s.key.startsWith("hotReload.")).map(itemFor) },
+		{ id: "chrome", title: "Chrome", icon: "▰", items: SETTINGS.filter((s) => s.key.startsWith("chrome.")).map(itemFor) },
+		{ id: "verify", title: "Verify", icon: "✓", items: SETTINGS.filter((s) => s.key.startsWith("verify.")).map(itemFor) },
+		{ id: "editor", title: "Editor", icon: "▥", items: SETTINGS.filter((s) => s.key.startsWith("editor.")).map(itemFor) },
+	].filter((g) => g.items.length > 0);
+
+	const findSetting = (key: string): Setting | undefined => SETTINGS.find((s) => s.key === key);
+
+	const applyToggle = (item: ListItem): void => {
+		const s = findSetting(item.id);
+		if (!s) return;
+		if (s.kind === "bool") {
+			const cur = s.get(working);
+			s.set(working, !cur);
+		} else if (s.kind === "enum") {
+			const cur = s.get(working) as string;
+			const idx = s.values.indexOf(cur);
+			const next = s.values[(idx + 1) % s.values.length]!;
+			s.set(working, next);
+		} else if (s.kind === "number") {
+			const cur = s.get(working);
+			const step = s.step ?? 1;
+			const next = Math.min(s.max, Math.max(s.min, cur + step));
+			s.set(working, next);
+		}
+	};
+
+	ctx.ui.custom<void>(
+		(tui: TUI, theme: Theme, keybindings: PanelKeybindings, done: () => void) => {
+			const stepDown = (item: ListItem): void => {
+				const s = findSetting(item.id);
+				if (!s || s.kind !== "number") return;
+				const step = s.step ?? 1;
+				const cur = s.get(working);
+				s.set(working, Math.max(s.min, cur - step));
+			};
+
+			return new ListPanel({
+				tui,
+				theme,
+				keybindings,
+				done: () => {
+					// Persist changes if the in-memory copy diverged from the
+					// original. Reads include both default-fills and global
+					// overrides — we only store the diff vs defaults.
+					if (JSON.stringify(working) !== originalJson) {
+						try {
+							const diff = diffVsDefaults(working);
+							saveConfigFile(solyDir, diff);
+							ui.notify(`settings saved → ${path.basename(solyDir)}/soly.json`, "info");
+							// Re-read the config from disk so the active config matches
+							// what we just wrote.
+							reloadConfig();
+						} catch (e) {
+							ui.notify(`save failed: ${(e as Error).message}`, "error");
+						}
+					}
+					done();
+				},
+				title: "soly · settings",
+				headerRight: `save on Esc → soly.json`,
+				groups: buildGroups(),
+				onSelect: (it) => applyToggle(it),
+				actions: [
+					{ key: "-", hint: "−1", run: stepDown },
+				],
+			});
+		},
+		{ overlay: true },
+	);
+}