feat(settings): productize stable and advanced controls

Author: ndycode

docs/reference/settings.md

@@ -1,6 +1,6 @@
 # Settings Reference
 
-Reference for dashboard and backend settings available from `codex auth login` -> `Settings`.
+Reference for the settings surface available from `codex auth login` -> `Settings`.
 
 ---
 
@@ -19,7 +19,11 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.
 
 ---
 
-## Account List View
+## Everyday Settings
+
+The top-level settings flow separates everyday dashboard preferences from advanced operator controls.
+
+### List Appearance
 
 Controls account-row display and sorting behavior:
 
@@ -37,7 +41,7 @@ Controls account-row display and sorting behavior:
 - `menuSortQuickSwitchVisibleRow`
 - `menuLayoutMode`
 
-## Summary Line
+### Details Line
 
 Controls detail-line fields and order:
 
@@ -46,7 +50,7 @@ Controls detail-line fields and order:
 - `limits`
 - `status`
 
-## Menu Behavior
+### Results & Refresh
 
 Controls result-screen and fetch behavior:
 
@@ -56,17 +60,21 @@ Controls result-screen and fetch behavior:
 - `menuShowFetchStatus`
 - `menuQuotaTtlMs`
 
-## Color Theme
+### Colors
 
 Controls display style:
 
 - `uiThemePreset`
 - `uiAccentColor`
 - `menuFocusStyle`
 
-## Sync Center
+---
+
+## Advanced and Operator Controls
+
+### Codex CLI Sync
 
-The settings hub includes a preview-first sync center for Codex CLI account sync.
+The advanced section includes a preview-first sync center for Codex CLI account sync.
 See [upgrade notes](../upgrade.md) for sync workflow changes.
 
 Before applying sync, it shows:
@@ -84,9 +92,7 @@ Validation:
 - `npm run build`
 - `npm test`
 
----
-
-## Experimental
+### Experimental
 
 Experimental currently hosts:
 
@@ -108,7 +114,11 @@ Named backup behavior:
 - rejects separators, traversal (`..`), `.rotate.`, `.tmp`, and `.wal` suffixes
 - fails safely on collisions instead of overwriting by default
 
-## Backend Controls
+### Advanced Backend Controls
+
+Expert backend controls stay available without changing the saved settings schema. They are grouped into categories so the default path can stay simpler for day-to-day use.
+
+## Backend Categories
 
 ### Session & Sync
 

lib/cli.ts

@@ -225,6 +225,14 @@ async function promptLoginModeFallback(
 				}
 				return { mode: "reset" };
 			}
+			if (
+				normalized === "u" ||
+				normalized === "restore" ||
+				normalized === "backup" ||
+				normalized === "restore-backup"
+			) {
+				return { mode: "restore-backup" };
+			}
 			if (normalized === "c" || normalized === "check")
 				return { mode: "check" };
 			if (normalized === "d" || normalized === "deep") {

lib/codex-manager/settings-hub.ts

@@ -3294,40 +3294,51 @@ async function promptSettingsHub(
 		},
 		{
 			label: UI_COPY.settings.accountList,
+			hint: UI_COPY.settings.accountListHint,
 			value: { type: "account-list" },
 			color: "green",
 		},
-		{
-			label: UI_COPY.settings.syncCenter,
-			value: { type: "sync-center" },
-			color: "green",
-		},
 		{
 			label: UI_COPY.settings.summaryFields,
+			hint: UI_COPY.settings.summaryFieldsHint,
 			value: { type: "summary-fields" },
 			color: "green",
 		},
 		{
 			label: UI_COPY.settings.behavior,
+			hint: UI_COPY.settings.behaviorHint,
 			value: { type: "behavior" },
 			color: "green",
 		},
-		{ label: UI_COPY.settings.theme, value: { type: "theme" }, color: "green" },
+		{
+			label: UI_COPY.settings.theme,
+			hint: UI_COPY.settings.themeHint,
+			value: { type: "theme" },
+			color: "green",
+		},
 		{ label: "", value: { type: "back" }, separator: true },
 		{
 			label: UI_COPY.settings.advancedTitle,
 			value: { type: "back" },
 			kind: "heading",
 		},
+		{
+			label: UI_COPY.settings.syncCenter,
+			hint: UI_COPY.settings.syncCenterHint,
+			value: { type: "sync-center" },
+			color: "yellow",
+		},
 		{
 			label: UI_COPY.settings.experimental,
+			hint: UI_COPY.settings.experimentalHint,
 			value: { type: "experimental" },
 			color: "yellow",
 		},
 		{
 			label: UI_COPY.settings.backend,
+			hint: UI_COPY.settings.backendHint,
 			value: { type: "backend" },
-			color: "green",
+			color: "yellow",
 		},
 		{ label: "", value: { type: "back" }, separator: true },
 		{

lib/ui/copy.ts

@@ -62,17 +62,28 @@ export const UI_COPY = {
 	},
 	settings: {
 		title: "Settings",
-		subtitle: "Customize menu, behavior, backend, and experiments",
+		subtitle:
+			"Start with everyday dashboard settings. Advanced operator controls stay separate.",
 		help: "↑↓ Move | Enter Select | Q Back",
-		sectionTitle: "Basic",
-		advancedTitle: "Advanced",
+		sectionTitle: "Everyday Settings",
+		advancedTitle: "Advanced & Operator",
 		exitTitle: "Back",
-		accountList: "Account List View",
-		syncCenter: "Sync Center",
-		summaryFields: "Summary Line",
-		behavior: "Menu Behavior",
-		theme: "Color Theme",
+		accountList: "List Appearance",
+		accountListHint:
+			"Show badges, sorting, and how much detail each account row shows.",
+		syncCenter: "Codex CLI Sync",
+		syncCenterHint:
+			"Preview and apply one-way sync from Codex CLI account files.",
+		summaryFields: "Details Line",
+		summaryFieldsHint: "Choose which details appear under each account row.",
+		behavior: "Results & Refresh",
+		behaviorHint:
+			"Control auto-return timing and background limit refresh behavior.",
+		theme: "Colors",
+		themeHint: "Pick the base palette and accent color.",
 		experimental: "Experimental",
+		experimentalHint:
+			"Preview sync and backup actions before they become stable.",
 		experimentalTitle: "Experimental",
 		experimentalSubtitle: "Preview sync and backup actions before they become stable",
 		experimentalHelpMenu: "Enter Select | Q Back",
@@ -86,35 +97,37 @@ export const UI_COPY = {
 		experimentalRefreshInterval: "Refresh Guard Interval",
 		experimentalDecreaseInterval: "Decrease Refresh Interval",
 		experimentalIncreaseInterval: "Increase Refresh Interval",
-		backend: "Backend Controls",
+		backend: "Advanced Backend Controls",
+		backendHint: "Tune retry, quota, sync, recovery, and timeout internals.",
 		back: "Back",
 		previewHeading: "Live Preview",
 		displayHeading: "Options",
 		resetDefault: "Reset to Default",
 		saveAndBack: "Save and Back",
 		backNoSave: "Back Without Saving",
-		accountListTitle: "Account List View",
-		accountListSubtitle: "Choose row details and optional smart sorting",
+		accountListTitle: "List Appearance",
+		accountListSubtitle: "Choose badges, sorting, and row layout",
 		accountListHelp:
 			"Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)",
-		summaryTitle: "Account Details Row",
-		summarySubtitle: "Choose and order detail fields",
+		summaryTitle: "Details Line",
+		summarySubtitle: "Choose and order the details shown under each account",
 		summaryHelp:
 			"Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)",
-		behaviorTitle: "Return Behavior",
-		behaviorSubtitle: "Control how result screens return",
+		behaviorTitle: "Results & Refresh",
+		behaviorSubtitle: "Control auto-return and limit refresh behavior",
 		behaviorHelp:
 			"Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)",
-		themeTitle: "Color Theme",
-		themeSubtitle: "Pick base color and accent",
+		themeTitle: "Colors",
+		themeSubtitle: "Pick the base palette and accent color",
 		themeHelp: "Enter Select | 1-2 Base | S Save | Q Back (No Save)",
-		backendTitle: "Backend Controls",
-		backendSubtitle: "Tune sync, retry, and limit behavior",
+		backendTitle: "Advanced Backend Controls",
+		backendSubtitle:
+			"Expert settings for sync, retry, quota, and timeout behavior",
 		backendHelp:
 			"Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)",
-		syncCenterTitle: "Sync Center",
+		syncCenterTitle: "Codex CLI Sync",
 		syncCenterSubtitle:
-			"Inspect source paths, watcher status, and one-way preview semantics before applying sync",
+			"Inspect source files and preview one-way sync before applying it",
 		syncCenterHelp: "Enter Select | A Apply | R Refresh | Q Back",
 		syncCenterOverviewHeading: "Sync Overview",
 		syncCenterActionsHeading: "Actions",

test/codex-manager-cli.test.ts

@@ -396,10 +396,10 @@ type SettingsHubMenuItem = {
 
 const SETTINGS_HUB_MENU_ORDER = [
 	"account-list",
-	"sync-center",
 	"summary-fields",
 	"behavior",
 	"theme",
+	"sync-center",
 	"experimental",
 	"backend",
 ] as const;
@@ -4104,7 +4104,7 @@ describe("codex manager cli commands", () => {
 		);
 	});
 
-	it("shows experimental settings in the settings hub", async () => {
+	it("shows productized everyday and advanced settings in the hub", async () => {
 		const now = Date.now();
 		setupInteractiveSettingsLogin(createSettingsStorage(now));
 		queueSettingsSelectSequence([{ type: "back" }]);
@@ -4114,6 +4114,44 @@ describe("codex manager cli commands", () => {
 
 		expect(exitCode).toBe(0);
 		expect(readSettingsHubPanelContract()).toEqual(SETTINGS_HUB_MENU_ORDER);
+		const firstMenuItems = (selectMock.mock.calls[0]?.[0] ?? []) as Array<{
+			label?: string;
+			hint?: string;
+		}>;
+		const firstMenuOptions = selectMock.mock.calls[0]?.[1] as
+			| {
+					message?: string;
+					subtitle?: string;
+			  }
+			| undefined;
+		expect(firstMenuOptions?.message).toBe("Settings");
+		expect(firstMenuOptions?.subtitle).toContain(
+			"everyday dashboard settings",
+		);
+		const menuText = firstMenuItems
+			.map((item) => `${item.label ?? ""}\n${item.hint ?? ""}`)
+			.join("\n");
+		expect(menuText).toContain("Everyday Settings");
+		expect(menuText).toContain("List Appearance");
+		expect(menuText).toContain("Details Line");
+		expect(menuText).toContain("Results & Refresh");
+		expect(menuText).toContain("Colors");
+		expect(menuText).toContain("Advanced & Operator");
+		expect(menuText).toContain("Codex CLI Sync");
+		expect(menuText).toContain("Experimental");
+		expect(menuText).toContain("Advanced Backend Controls");
+		expect(menuText).toContain(
+			"Show badges, sorting, and how much detail each account row shows.",
+		);
+		expect(menuText).toContain(
+			"Preview and apply one-way sync from Codex CLI account files.",
+		);
+		expect(menuText).toContain(
+			"Preview sync and backup actions before they become stable.",
+		);
+		expect(menuText).toContain(
+			"Tune retry, quota, sync, recovery, and timeout internals.",
+		);
 	});
 
 	it("runs experimental oc sync with mandatory preview before apply", async () => {

test/documentation.test.ts

@@ -288,15 +288,37 @@ describe("Documentation Integrity", () => {
 	it("locks the current Experimental settings menu labels and help text", () => {
 		expect(UI_COPY.settings.title).toBe("Settings");
 		expect(UI_COPY.settings.subtitle).toBe(
-			"Customize menu, behavior, backend, and experiments",
+			"Start with everyday dashboard settings. Advanced operator controls stay separate.",
 		);
 		expect(UI_COPY.settings.help).toBe("↑↓ Move | Enter Select | Q Back");
-		expect(UI_COPY.settings.accountList).toBe("Account List View");
-		expect(UI_COPY.settings.summaryFields).toBe("Summary Line");
-		expect(UI_COPY.settings.behavior).toBe("Menu Behavior");
-		expect(UI_COPY.settings.theme).toBe("Color Theme");
+		expect(UI_COPY.settings.accountList).toBe("List Appearance");
+		expect(UI_COPY.settings.accountListHint).toBe(
+			"Show badges, sorting, and how much detail each account row shows.",
+		);
+		expect(UI_COPY.settings.syncCenter).toBe("Codex CLI Sync");
+		expect(UI_COPY.settings.syncCenterHint).toBe(
+			"Preview and apply one-way sync from Codex CLI account files.",
+		);
+		expect(UI_COPY.settings.summaryFields).toBe("Details Line");
+		expect(UI_COPY.settings.summaryFieldsHint).toBe(
+			"Choose which details appear under each account row.",
+		);
+		expect(UI_COPY.settings.behavior).toBe("Results & Refresh");
+		expect(UI_COPY.settings.behaviorHint).toBe(
+			"Control auto-return timing and background limit refresh behavior.",
+		);
+		expect(UI_COPY.settings.theme).toBe("Colors");
+		expect(UI_COPY.settings.themeHint).toBe(
+			"Pick the base palette and accent color.",
+		);
 		expect(UI_COPY.settings.experimental).toBe("Experimental");
-		expect(UI_COPY.settings.backend).toBe("Backend Controls");
+		expect(UI_COPY.settings.experimentalHint).toBe(
+			"Preview sync and backup actions before they become stable.",
+		);
+		expect(UI_COPY.settings.backend).toBe("Advanced Backend Controls");
+		expect(UI_COPY.settings.backendHint).toBe(
+			"Tune retry, quota, sync, recovery, and timeout internals.",
+		);
 		expect(UI_COPY.settings.accountListHelp).toBe(
 			"Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)",
 		);
@@ -317,12 +339,16 @@ describe("Documentation Integrity", () => {
 	it("keeps settings reference sections aligned with current menu labels and backend categories", () => {
 		const settingsRef = read("docs/reference/settings.md");
 
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.accountList}`);
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.summaryFields}`);
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.behavior}`);
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.theme}`);
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.experimental}`);
-		expect(settingsRef).toContain(`## ${UI_COPY.settings.backend}`);
+		expect(settingsRef).toContain("## Everyday Settings");
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.accountList}`);
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.summaryFields}`);
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.behavior}`);
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.theme}`);
+		expect(settingsRef).toContain("## Advanced and Operator Controls");
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.syncCenter}`);
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.experimental}`);
+		expect(settingsRef).toContain(`### ${UI_COPY.settings.backend}`);
+		expect(settingsRef).toContain("## Backend Categories");
 		expect(settingsRef).toContain("### Session & Sync");
 		expect(settingsRef).toContain("### Rotation & Quota");
 		expect(settingsRef).toContain("### Refresh & Recovery");