docs: refresh settings reference

[ndycode]

Summary

• rewrite docs/reference/settings.md into a structured settings reference with defaults and effects
• align section headings with the actual settings menu labels and backend category names
• keep environment override sections clearly separated into stable versus advanced/internal overrides

Validation

• npm run test -- test/documentation.test.ts
• Manual QA: read back the rewritten settings reference and confirm the menu sections and backend headings are present

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this pr rewrites docs/reference/settings.md from a loose bullet-list inventory into a structured reference with per-key defaults and effect descriptions, split across dashboardDisplaySettings (account list view, summary line, menu behavior, color theme) and pluginConfig (backend controls), with stable vs. advanced env overrides clearly separated.

changes

• all four dashboard sections and all four backend subsections now have | key | default | effect | tables
• section headings aligned to actual settings menu labels and backend category names
• menuShowFetchStatus no longer duplicated across account list view and menu behavior (previous review concern addressed)
• stable environment overrides and advanced/internal overrides remain separated without the --- rule between them

issues found

• account list view and summary line sections still carry their original bullet-key lists directly above the new tables — every other section drops the bullets; these two are inconsistent and the lists are fully redundant with the tables
• retryAllAccountsMaxRetries default is documented as Infinity, which is not a valid json literal; users copying this into settings.json will get a parse error — needs to be quoted or replaced with the actual sentinel value the runtime accepts
• retryAllAccountsMaxWaitMs: 0 is ambiguous: without knowing whether 0 disables the cap or means zero-millisecond delay, the two combined defaults (maxWaitMs: 0, maxRetries: Infinity) look like a potential tight-retry loop to anyone reading the table cold
• no vitest coverage added for the new defaults — test/documentation.test.ts already covers docs parity; consider asserting that the defaults documented here match the runtime defaults in plugin-config.ts / dashboard-settings.ts

Confidence Score: 4/5

• safe to merge after clarifying the Infinity json validity issue; the other two are clean-up suggestions
• docs-only pr with no runtime changes. the previous duplicate-key concern is resolved. the Infinity default is the only issue that could actively mislead a user editing settings.json directly; fixing that (or confirming the runtime accepts the string) unblocks merge. redundant bullet lists and the maxWaitMs: 0 ambiguity are p2 cleanups that don't block anything.
• docs/reference/settings.md — confirm retryAllAccountsMaxRetries default value is valid json or document the string form explicitly

Important Files Changed

Filename	Overview
docs/reference/settings.md	settings reference rewritten with structured tables — minor issues: redundant bullet lists left in two sections, Infinity is not valid JSON for a settings.json default, and retryAllAccountsMaxWaitMs: 0 semantics are ambiguous

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["~/.codex/multi-auth/settings.json"] --> B{"top-level key?"}
    B -->|dashboardDisplaySettings| C[Account List View]
    B -->|dashboardDisplaySettings| D[Summary Line]
    B -->|dashboardDisplaySettings| E[Menu Behavior]
    B -->|dashboardDisplaySettings| F[Color Theme]
    B -->|pluginConfig| G[Session & Sync]
    B -->|pluginConfig| H[Rotation & Quota]
    B -->|pluginConfig| I[Refresh & Recovery]
    B -->|pluginConfig| J[Performance & Timeouts]
    K["env overrides (stable)"] -->|CODEX_MULTI_AUTH_DIR etc.| A
    L["env overrides (advanced)"] -->|CODEX_MULTI_AUTH_BYPASS etc.| A
    C & D & E & F --> M["TUI / settings-hub.ts"]
    G & H & I & J --> M

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/reference/settings.md
Line: 26-54

Comment:
**redundant bullet list left above account list view table**

the bullet list (lines 26–38) enumerates the exact same keys that the table immediately below it documents with defaults and effects. every other section in this pr — menu behavior, color theme, backend controls — drops the old bullets and keeps only the table. these two sections are the outliers.

the summary line section has the same pattern: `menuStatuslineFields` appears as a bullet then again in the table two lines later. suggest removing the bullet lists from both sections to match the cleaner pattern used everywhere else in the rewritten doc.

```suggestion
## Account List View

Controls account-row display and sort behavior.

| Key | Default | Effect |
| --- | --- | --- |
| `menuShowStatusBadge` | `true` | Show ready/cooldown/disabled status badges on account rows |
| `menuShowCurrentBadge` | `true` | Mark the current account row |
| `menuShowLastUsed` | `true` | Include last-used text in row details |
| `menuShowQuotaSummary` | `true` | Show compact quota usage summaries |
| `menuShowQuotaCooldown` | `true` | Show quota reset/cooldown details |
| `menuShowFetchStatus` | `true` | Show quota fetch/probe status text |
| `menuShowDetailsForUnselectedRows` | `false` | Expand details for unselected rows |
| `menuHighlightCurrentRow` | `true` | Emphasize the current account row |
| `menuSortEnabled` | `true` | Enable menu sorting |
| `menuSortMode` | `ready-first` | Sort rows by readiness/risk heuristic |
| `menuSortPinCurrent` | `false` | Keep the current account pinned while sorting |
| `menuSortQuickSwitchVisibleRow` | `true` | Keep quick-switch numbering aligned to visible sorted rows |
| `menuLayoutMode` | `compact-details` | Choose compact or expanded row layout |
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: docs/reference/settings.md
Line: 149

Comment:
**`Infinity` is not a valid JSON literal**

`settings.json` is a JSON file. `Infinity` is not a valid JSON number — a user who copies this value verbatim will get a parse error. if the runtime actually accepts the string `"Infinity"` and converts it, document the default as `"Infinity"` (quoted). if the intended meaning is "no cap" and the code treats `0` or `-1` as unlimited, use that numeric value instead and clarify the semantics in the effect column.

```suggestion
| `retryAllAccountsMaxRetries` | `"Infinity"` | Maximum retry attempts for all-accounts-rate-limited loops (string "Infinity" = no cap) |
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: docs/reference/settings.md
Line: 148

Comment:
**`0` for a max-wait budget is ambiguous**

with `retryAllAccountsRateLimited: true` and `retryAllAccountsMaxRetries: Infinity`, a `maxWaitMs` of `0` could mean "unlimited budget" (disabled cap) or "do not wait at all between retries" (tight loop). the effect column just says "maximum wait budget" without clarifying which interpretation `0` carries. if `0` disables the cap, say so explicitly; if it means no enforced delay, note that the exponential backoff in the retry path still applies.

```suggestion
| `retryAllAccountsMaxWaitMs` | `0` | Maximum cumulative wait for all-accounts-rate-limited retries (`0` = no cap) |
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "Deduplicate settings..."}

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🚫 Review skipped — only excluded labels are configured. (1)

• skip-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b0876ec6-d341-43b3-865c-29b512764fa2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/pr12-settings-reference-refresh-stacked

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/pr12-settings-reference-refresh-stacked

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}