06. Settings Information Architecture

1. Settings root (Codex full-page shell)

Settings is a full-window page that replaces the app sidebar + main chrome (Codex electron behavior):

• Left settings rail only (sidebar surface #f4f4f4 light / #000 dark), ~275px (Codex gold at 1200-wide)
• Top of rail: traffic-light clearance, Back to app (返回应用), pill Search settings…
• The 46px top band across both the rail and content pane is a native window drag region; interactive controls remain explicitly non-draggable
• A compact navigation directory with icons, in this exact order:
  1. Basics — Lucide SlidersHorizontal (appearance, defaults)
  2. 全局 AI / AI — Lucide Sparkles (permissions, context management)
  3. Shortcuts — Lucide Keyboard (keyboard shortcuts)
  4. Instructions — Lucide FileText (global and project instruction files)
  5. Model configuration — Lucide Bot (providers and default model)
  6. Import — Lucide Download (bring sessions in from other tools)
  7. Project archive — Lucide Archive (durable project index)
  8. Info — Lucide Info (versions, logs, updates, developer) Icons are decorative (aria-hidden via the SVG default) and stay monochrome with the rail label; do not reuse refresh/rotate glyphs here.
• No additional settings destinations or placeholder navigation rows are shown
• Main content pane on primary surface with large section title + elevated rounded cards of rows. Its content uses the full width available after the fixed rail and pane gutters, and resizes continuously with the window.

2. Section contents

Basics

• Appearance card:
  • Theme: three selectable preview cards (System / Light / Dark, System first) with a live mini-window mockup, a per-option description, and a selected check badge; selection updates settings.theme
  • Language: three selectable preview cards (Auto / 简体中文 / English) with a sample-text preview, a per-option description, and a selected check badge; selection updates settings.language
  • Auto language detection resolves the OS locale through the main process (app.getLocale()) rather than the renderer's navigator.language, and the Auto card shows the detected language inline (e.g. "当前：简体中文")
  • native select triggers and their opened option lists use the active theme's readable foreground/background pairing on macOS, Windows, and Linux; the shared native-select contract applies to every app surface
• Defaults card retains the host-backed default mode and Enter-to-send controls.
• File-open target, menu-bar behavior, and bottom-panel behavior are not rendered until their host-backed settings schemas and runtime effects exist.

全局 AI (ai tab)

• Permissions card: the global permission-mode control (ask / accept-edits / auto) that governs how autonomously the agent acts.
• Command shell card: the host-discovered catalog of native PowerShell, cmd, Git Bash, and Bash with IDs windows-powershell, cmd, git-bash, and bash where supported. The selected defaultCommandShell persists across restart; writes reject unavailable or wrong-platform IDs. If a persisted choice later becomes unavailable, the first available platform shell is used and the fallback state is shown. A Bash turn verifies its pinned ID/dialect before execution.
• Context management has no card and no controls (D200 / ADR 0061, kept by D203 / ADR 0064). Automatic protection is always on and its budgets and retention limits are derived from the active model's window, so there is nothing a user could tune from here — the reference implementation does not expose these values either. Settings search indexes no compaction keys. Manual /compact remains available from the command palette for an idle session; the transcript shows where each compaction happened and the context usage inspector shows whether a checkpoint is installed.

Shortcuts (shortcuts tab)

• Keyboard shortcuts card:
  • lists navigation, agent, and window actions from one shared shortcut map
  • renders platform-native modifier labels (⌘ on macOS, Ctrl on Windows/Linux) and the platform-specific full-screen default
  • clicking a binding records the next modifier chord or F1–F12; Escape cancels recording
  • duplicate application bindings and operating-system/editor-reserved chords are rejected with an inline error
  • each override can be restored independently and all overrides can be restored together
  • overrides persist in optional AppSettings.keybindings; macOS native-menu accelerators and renderer-owned shortcuts update from the same map
  • the plugin launcher defaults to Option + Space on macOS and Alt + Space on Windows/Linux; its native global registration follows the same override, while the focused frameless window retains an Alt + Space fallback

Model configuration (agent tab)

• Studio hero: provider count, ready count, and current default provider/model summary
• Defaults card:
  • default operating mode via segmented control (Agent / Plan / Goal), with Agent selected for new sessions and new scheduled tasks
  • persisted legacy Chat default values are displayed and stored as Plan
  • default model id
  • Enter to send as a switch (local preference; not on Codex General gold)
• Providers studio:
  • OpenAI-compatible add-provider dialog (opened from Add provider / empty-state CTA)
  • provider cards with avatar initials, host, default model, secret status, and test / make-default / delete actions
  • the add/edit dialog configures connection identity only (name, endpoint, API style, model id, and secret); model parameters come from pi-ai and are not editable here
  • empty state with primary add action
  • API keys are never shown raw after save

The permission-mode selector remains available in the composer while the session is in Agent, Plan, or Goal. In Plan and Goal it controls Bash confirmation only: Ask and Accept edits prompt, while Auto may run a mutating Bash command without confirmation. The Defaults card must describe that both contract modes are intent boundaries, not strict read-only security profiles.

Instructions (instructions tab)

• Edit the global instruction Markdown used by every PI-Desktop Agent session.
• Show the resolved instruction-file path and save through the host-backed instruction API; project instructions remain managed from the active project menu and are resolved after the global layer.

Import

• Scan supported local agent stores and review candidates through SessionImportPanel
• Source and project-path grouping behavior follows 08-component-spec §18

Project archive

• Reuses the durable Projects index as a settings-scale management surface
• Always includes archived records; archived rows are grouped, never hidden, so the destination still has no visibility toggle
• Supports project search, add, activate, project-session expansion, pin, archive/restore, and close
• Layout is three stacked bands (D168):
  1. Overview banner — one sentence of intent, the primary Add project action, and four live counters (projects, open, archived, sessions) whose totals are derived from the same pass that builds the list below
  2. Toolbar — search field with a clear affordance and a match count while searching, plus a two-option sort segmented control (Recent, Name)
  3. Grouped index — always-visible sections in the order Pinned, All projects, Archived; each section shows its label and row count and renders its rows inside one settings panel with hairline separators. Empty sections are omitted
• Row anatomy: disclosure control, color glyph, project name with state tags (Active, Open, pinned glyph, Archived), one meta line carrying the shortened monospace path, branch, and session count, a relative last-active time, and a hover/focus-revealed action pair (New task, row menu)
• The row menu groups create/edit actions above pin, archive/restore, and the destructive Close action, and closes on Escape or any outside press
• Project search also matches session titles. Matching a session retains and expands its owning project; expanded sessions are ordered by latest activity, show a count and relative update time, and reveal additional rows in batches of eight rather than silently truncating the history
• Activating a project or project session returns to chat; archive and close actions keep Project archive open even when the active workspace changes

Info

• app/host/protocol versions + open logs
• Updates row with the current delivery state and one applicable action: Check for updates, View release, or Restart to update
• Developer card:
  • developer mode is off unless the optional persisted AppSettings.developerMode value is true
  • the developer mode switch unlocks the Open console button, F12 on every platform, Ctrl+Shift+I on Windows/Linux, and the macOS View-menu developer tools item
  • disabling developer mode closes an open console and disables or removes every entry point; Settings search indexes the card, switch, and console action
• The Updates row always exposes a Release notes action. It opens a modal containing the complete shipped stable changelog in newest-first order, localized to the product language and marking the current and available versions when present
• When an update is available, downloading, or downloaded and Main attached dual-locale product notes, the Updates row shows a compact "What's new" list under the status text (same notes as the ambient banner; D164). The full-history modal remains available when the app is up to date or update checks are disabled in development

3. Navigation rules

• Profile footer / command palette open Settings full page (default Basics)
• Composer model menu and provider setup actions deep-link to the Providers card inside Agent
• Plugin management remains available from the app shell's independent Plugins destination, including load, enable, disable, and uninstall; it is not duplicated in Settings
• Project archive is indexed by Settings search and is not duplicated as a home sidebar destination or standalone global-search page
• Back to app returns to chat shell

4. Acceptance

1. Opening Settings hides the coding app sidebar (full-page takeover)
2. Rail shows search + back and exactly Basics, 全局 AI/AI, Shortcuts, Instructions, Model configuration, Import, Project archive, and Info in that order
3. Appearance is part of Basics and has no standalone rail destination
4. Providers is part of Agent and has no standalone rail destination
5. Plugins has no Settings destination; the app-shell Plugins page supports load, enable, disable, and uninstall
6. Basics shows host-backed Appearance and Defaults cards only; the AI destination shows Permissions and Command shell; the Shortcuts destination shows the Keyboard shortcuts card; Info shows the Developer card. No additional settings destinations are rendered
7. Provider secrets never display raw key values
8. Model configuration shows the provider studio (hero + defaults + add dialog + cards) rather than a dense always-on form dump
9. Row descriptions use semantic secondary text and maintain at least 4.5:1 contrast against their card surface in both light and dark themes
10. Dragging the empty top band from either side of Settings moves the native window without blocking Back, search, or navigation controls
11. Resizing the window expands or contracts the content cards with the available content pane; the fixed rail and pane gutters remain intact and the page does not gain horizontal overflow
12. Project archive always exposes archived records and can restore them without duplicating the index in the app shell
13. Project archive renders the overview counters, search + sort toolbar, and the Pinned / All projects / Archived sections; the counters agree with the rendered row counts, sorting reorders rows inside every section without hiding any, and clearing the search restores the complete index
14. Info renders disabled, checking, up-to-date, available, downloading, downloaded, and error update states without adding another destination
15. Native select option lists remain readable in both light and dark themes, including when Chromium delegates the opened list surface to Windows; the same global rule covers non-Settings native selects
16. Shortcut recording rejects modifier-free non-function keys, reserved editor/OS chords, and conflicts; successful overrides immediately drive app behavior and macOS menu accelerators and survive restart
17. Developer tools remain unavailable by default; enabling developer mode unlocks the localized Settings action and platform shortcuts, persists across restart, and disabling it closes an open console
18. Context management exposes no settings at all; protection is always on and its budgets scale with the active model's context window, so no persisted value can leave a small-window model uncompactable or the guard disabled
19. The default operating-mode selector contains Agent, Plan, and Goal; legacy Chat values migrate to Plan and do not reappear as a selectable option
20. Command shell selection persists a platform-valid catalog ID, exposes unavailable/fallback status, and never authorizes a stale ID/dialect

5. Basics chrome metrics

The shell retains the Codex gold chrome while allowing the content pane to use the current window width:

Token	Value
Rail width	~275px
Rail light bg	#f4f4f4
Active nav pill	denser 6px/10px pad, ~8px radius, gray mix on rail
Section title	28px / 560, first baseline ~y70
Content width	Full available pane width after rail and gutters
Card radius	~14px elevated stroke
Toggle	32×20 thumb 16, neutral accent on (not green)
Open-target pill	leading VS Code glyph