AGENTS.md@packages/client/src/components/settings git:20260829.f96917dA

Immutable. This exact content is served forever at /api/v1/blob/19ac5e121e01fc44.

# DOX — packages/client/src/components/settings

Files in this directory. One row per source file. See change: fold-oversized-agents-directories.

| File | Purpose |
|------|---------|
| `CanvasTypesSettingsSection.tsx` | Canvas-type registry settings: 8 per-kind checkboxes + global/project scope switch. Toggle PATCHes the full 8-key map for the scope then refreshes. Project scope needs a session cwd (disabled with hint when none). See change: auto-canvas. |
| `DiagnosticsSection.tsx` | Settings → Diagnostics. Fetches `/api/doctor`. Groups by section in fixed order, omits empty sections (no n/a… → see `DiagnosticsSection.tsx.AGENTS.md` Also fetches the retained auto-naming outcomes on mount (`autoNameFetcher` injectable) and renders them under `auto-naming-diagnostics`; `starved` is labelled distinctly from `waiting` (output-cap truncation vs no nameable topic) because conflating them is the bug this readout exists to expose. Best-effort: a failed outcomes fetch never blocks the doctor report. See change: fix-auto-naming-reasoning-model. |
| `FirstLaunchDisplayModal.tsx` | One-shot preset picker (simple / standard / everything) shown when `/api/preferences/display.global ===… → see `FirstLaunchDisplayModal.tsx.AGENTS.md` |
| `ModelProxySection.tsx` | Settings panel section for model proxy. Exports `ModelProxySection`, `ModelProxyConfig`. → see `ModelProxySection.tsx.AGENTS.md` |
| `ModelSelector.tsx` | Variant C: grouped by provider, pinned ★ Favorites group, per-row star toggle, capability badges (🧠/👁… → see `ModelSelector.tsx.AGENTS.md` Footer refresh button + `refreshing` state REMOVED; `onRefresh` now fires on the dropdown open transition (sole trigger); new `refreshErrors?` prop renders a non-blocking footer notice (`data-testid model-refresh-errors`), never a toast. See change: upgrade-model-selector-primitives. |
| `PiRuntimeSection.tsx` | Settings → Developer "Pi runtime" section, mounted directly above `<ToolsSection />` (design D12 correction: Tools left General in `reorganize-settings-pages-and-descriptions`; adjacency is the load-bearing half of the rationale). Two consumer lanes (Sessions spawn = blue / Server imports = purple) over one candidate list with two selection columns. "Keep both in sync" is DERIVED from realpath'd package-dir equality and persisted NOWHERE — a stored flag would open "checked" on a pre-existing single-consumer pin and one click would clobber it. Apply issues ONE `POST /api/pi/runtime`; the confirm dialog restates a resulting mismatch BEFORE the write and does not claim one when the lanes agree. Below-floor rows disabled with the required minimum named; unknown-version rows warn but stay selectable. Restart offered only when the IMPORT consumer changed; running sessions on the previous version counted, unknown-runtime sessions reported separately. Collapses below 680px to metadata-over-two-cells with ≥44px hit areas. See change: select-pi-runtime-install. |
| `PluginSettingsPage.tsx` | Host-owned chrome for the per-plugin settings page `/settings/plugins/<id>`: identity, status pill, enable toggle, metadata chips, error + missing-requirement banners, then the plugin body via `SettingsSectionByPluginSlot`. No opt-out prop. Provides `PluginSettingsPageProvider` so draft sources file under `plugins/<id>`. Disabled plugin → chrome + disabled notice + re-enable, no body mount. Also exports `PluginNotFoundNotice`. See change: plugin-settings-pages. |
| `ProviderAuthSection.tsx` | Settings section for LLM provider auth. Exports `ProviderAuthSection`. → see `ProviderAuthSection.tsx.AGENTS.md` |
| `RetrySettingsSection.tsx` | Editor for pi's OWN retry policy — ALL SIX fields (`retry.{enabled,maxRetries,baseDelayMs}` + `retry.provider.{timeoutMs,maxRetries,maxRetryDelayMs}`) via `pi-retry-api`. Exports `RetrySettingsSection`; `load`/`save` props injectable for tests. Mounted in SettingsPanel **`sessions`** tab (turn-level fields dominate; the observable effect is on a session), section titled "Retry" — the body renders NO heading of its own. NO private Save button: registers via `useSettingsDraftSource({id:"pi-retry", page:"sessions", isDirty, commit, reset})` so the panel's unified Save commits it, the nav rail shows a Sessions dirty dot, and the leave guard covers it; `commit` THROWS on invalid input or a failed PUT so the host keeps it dirty and names it in `savePartialFail` (never a false success); `reset` restores the loaded policy for Discard. `isDirty` = string-compare vs the loaded snapshot, so an invalid in-progress edit still counts. Renders enabled toggle (off → greys the turn-level numerics), a live `SchedulePreview` (delay progression + total, since pi's delay is `baseDelayMs * 2^(n-1)` uncapped), a NON-BLOCKING long-tail warning above `LONG_TAIL_ATTEMPTS=20` (warned, never capped — a UI cap is bypassed by editing the file), a global-scope disclosure, the `retry.provider.*` trio under its own "Provider / SDK request controls" subhead with an invisible-wait warning (that layer emits no event → renders as ordinary streaming), and a status line reporting `reloadedSessions`. Blank `provider.timeoutMs` is OMITTED, never `0`/`null`. Client-side validation mirrors the server's. See change: retry-forever-with-stop-control, unify-settings-save-contract (draft-source rewiring + Sessions placement). |
| `SettingsPanel.tsx` | Settings UI: left-nav rail + page content… → see `SettingsPanel.tsx.AGENTS.md` Trusted Networks gains the unreachable-bind advisory (live region, above the block-event banner) with an inline `0.0.0.0` remediation and a Server-page link; the header Restart affordance signals a saved-but-unapplied `bindHost`; the Add Local Network dropdown renders deduped `suggestions`. See change: warn-unreachable-trusted-networks. Sessions page renders a `ThinkingLevelSelector` inside the Default Model `--severity-info-*` callout, bound to `config.defaultThinkingLevel`; levels derive from the selected model's `supportedThinkingLevels` (App threads it through `availableModels`), lock to `["off"]` (persistence no-op, field stays `""`) when no model is selected, and persist via the `PUT /api/config` partial. See change: add-default-thinking-level. The Sessions-page auto-name toggle carries `auto-name-model-pointer`, naming the `@naming` role (configured in the Roles panel) and its `@fast` fallback — the naming model has ONE source of truth (the roles map), so the toggle points at it rather than duplicating a selector. See change: fix-auto-naming-reasoning-model. Root is `flex-1 flex flex-col min-w-0 min-h-0` (NOT `h-full`) — the flush Dialog panel is a capped flex column with no definite height, and this root is shared with the MobileShell detail panel. See change: fix-flush-dialog-scroll-and-close-collision. Memory Limits gains a `replayWindowMode` SELECT, DISABLED (not hidden) at `maxReplayEvents: 0` with the dependency stated — hiding it would make the dependency invisible. Its hint carries both the tradeoff (opening messages omitted) and the SCOPE (affects every client of this server). `MemoryLimitsConfig` is no longer all-numeric, so the field-level diff writes through a `Record<string, unknown>` cast; the write stays FIELD-level, never whole-object. See change: add-tail-only-replay-window (D10). Chat display gains the `reasoningInlineFlow` toggle (inside the reasoning GatedGroup, visible-but-disabled when reasoning off) and the `customEntryFallback` toggle (immediately after Extension notifications). See change: render-inline-reasoning-and-custom-entries. |
| `ThemePicker.tsx` | Palette dropdown for theme selection. Lists `THEMES` with color swatches, flip-aware (`usePopoverFlip`), outside-click close. Reads/writes `useThemeContext`. Exports `ThemePicker`. See change: fix-popover-container-clip — documented structurally immune (no narrow offset `overflow` pane above it → keeps viewport measurement, no `boundaryRef`). See change: fix-popover-pane-bounded-height — applies BOTH `minHeight` and `maxHeight` (default 120 floor; 4 themes ≈ 112px content, so 260 would render dead space); immunity re-audited and CONFIRMED, correcting the stale "settings header" claim — its only mount is `SessionList.tsx` header bar, a sibling ABOVE that view's scroll list. |
| `ThemeProvider.tsx` | React context provider wrapping `useTheme` hook. Exports `ThemeProvider`, `useThemeContext` (throws outside provider). |
| `ThemeToggle.tsx` | Exports `ThemeToggle`. Three-button light/system/dark switcher; reads `preference`/`setPreference` from `useThemeContext`. Renders mdi icons, `data-testid="theme-toggle"`. |
| `ThinkingLevelSelector.tsx` | Thinking-level picker. Optional prop `supportedLevels` filters `THINKING_LEVELS` to supported set (canonical… → see `ThinkingLevelSelector.tsx.AGENTS.md` |
| `ToolsSection.tsx` | Settings → General → **Tools** section. One row per registered tool: status badge, source, truncated path,… → see `ToolsSection.tsx.AGENTS.md` |