# Phase 2 — Settings as a full-page grouped navigation

_One PR, after phase 1._

## Goal

Replace the horizontal `PageTabs` bar on `/settings` with a left navigation
grouped under small uppercase headings, one section per route, a search box
that filters sections, and consistent row primitives — the structure in
`reference/orca-settings1.png` / `orca-settings-agents.png` /
`orca-settings-scrolled.png`, in AgentHub's own tokens.

## Non-goals

- No new settings. Every control that exists today is kept, moved, and
  reachable from search. (One exception: the worktree-visibility toggles from
  phase 1 get their first proper home here.)
- No theme change. No new dependency.
- No change to any server setting route.

## 1. Routes

`App.tsx`: `settings` → `settings/:section?`. `SettingsHub.tsx` reads
`:section`; unknown or missing ⇒ redirect to `settings/general`. The old
`?tool=<id>` query is honoured for one release: `?tool=claude-code` ⇒
`/settings/agents/claude-code`, `?tool=ai-router` ⇒ `/settings/ai-router`, and
`#ai-tools` ⇒ `/settings/agents` with the catalog modal open. Every in-app link
that builds a settings URL (`AddLaneModal`'s AI Tools link, the Claude
tab's cross-links, `Sidebar` nav) is updated to the path form.

Section ids are stable strings (they are URLs and i18n keys):

| Group (i18n `settingsNav.group.*`) | Section id | Content = today's component |
| --- | --- | --- |
| **General** | `general` | `Settings.tsx` sections: `lanesSection` (renamed "Workspaces": housekeeping) + `data` (import, remote sources, clear data) + `about` |
| | `appearance` | `AppearanceSettings` |
| | `notifications` | `Settings.tsx` `notifications` + `alertsHub` (`AlertsNotifications`, `WebhookSettings`) |
| **Agents** | `agents` | `AiToolsSettings` inline (the modal's content as a page; `AiToolsModal` stays for the Add-workspace link) |
| | `agents/claude-code` | `CcConfig` (its own sub-tabs stay inside the page) |
| | `agents/codex` | `CodexConfig` |
| | `agents/<catalog id>` | `AiToolConfig toolId` — one entry per installed, enabled tool without a `launcher` (same rule as today's `catalogTabs`) |
| **Routing** | `ai-router` | `AiRouterConfig` |
| | `pricing` | `PricingSettings` with a vendor filter for *all* vendors (today it is embedded per tool; keep those embeds too — this page is the all-vendors view) |
| **Git** | `git-credentials` | `GitCredentialsConfig` |
| | `worktrees` | **new** `WorktreeVisibilitySettings`: "Show untracked worktrees" switch; per-source rows `.claude/worktrees/*` (Show/Hide), AgentHub-managed (`LANES_ROOT`) (Show/Hide); writes the phase-1 localStorage key |
| **Projects** | `projects/<encoded root>` | **new** `ProjectSettings`: read-only project card (root, main branch, worktree count), its workspaces (link to each), the per-project override of the worktree sources above (`hideSources` keyed by root), and "Forget all workspaces of this project" (loops `POST …/remove`, confirm modal listing them) |

A tool section is hidden while that tool is disabled (same `aiTools.byId(...).enabled` check as today).

## 2. Layout

```
┌ sidebar (app) ┬──────────────────────────────────────────────────────────┐
│               │ ← Back to Workspace                                       │
│               │ [🔍 Search settings            Ctrl+F]                     │
│               │                                                           │
│               │ GENERAL          │  General                                │
│               │  ⚙ General       │  Workspace housekeeping, data, about.   │
│               │  ◐ Appearance    │  ───────────────────────────────────── │
│               │  🔔 Notifications│  ┌ card ─────────────────────────────┐  │
│               │ AGENTS           │  │ Housekeeping                      │  │
│               │  ▣ AI tools      │  │ Run housekeeping     [Dry run][Run]│  │
│               │  ✳ Claude Code   │  ├───────────────────────────────────┤  │
│               │  ◎ Codex         │  │ Data                              │  │
│               │  ▲ Antigravity   │  │ Import history …                  │  │
│               │ ROUTING …        │  └───────────────────────────────────┘  │
│               │ PROJECTS         │                                         │
│               │  ◈ agenthub      │                                         │
└───────────────┴──────────────────┴─────────────────────────────────────────┘
```

- The settings nav is a second column **inside** the page (`w-56`, sticky,
  own scroll), not the app sidebar. The app sidebar stays as it is.
- "← Back to Workspace" is a plain link to `/workspace` (keeps `?ws` from
  localStorage).
- Content column: `max-w-3xl`, section title `text-2xl font-semibold`, one-line
  description `text-sm text-fg-muted`, hairline, then **one card per subsection**
  (`.card` as today). Do not nest cards.
- Mobile (`< md`): the nav becomes a `<select>` above the content.

## 3. Primitives (`client/src/components/settings/SettingsRow.tsx`)

```tsx
<SettingsSection title description>            // h3 + muted description inside a card
<SettingsRow label description control alignTop?>  // 2 columns: label+desc | control (shrink-0)
<SettingsSwitchRow label description checked onChange disabled? />
<SettingsSegmented options value onChange />  // role="radiogroup", existing button styles
```

Every control already in `Settings.tsx`, `AppearanceSettings.tsx`,
`ClaudeAgentHubSettings.tsx`, `CodexHooksSettings.tsx`,
`AntigravityHooksSettings.tsx`, `AiToolConfig.tsx` is re-wrapped in these
rows. `CcConfig.tsx` (172 KB) and `CodexConfig.tsx` keep their internal layout
in this phase — only their outer frame changes. Rows: `py-3` with a
description, `py-2` without; divider `border-b border-border/60` between
rows, none after the last.

## 4. Search

`client/src/lib/settingsSearch.ts`:

```ts
interface SettingsEntry { section: string; title: string; description?: string; keywords?: string[] }
rankSettings(query, entries): { section: string; score: number }[]
```

Scoring (lowercase; exact > prefix > substring): section title 900/850/800,
entry title 700/650/600, description 500/450/400, keywords 300/250/200. Each
section registers its entries in a static `SETTINGS_INDEX` array (one per
`SettingsRow` label at minimum; i18n-resolved at render). While the query is
non-empty the nav shows only matching sections (groups with no match hidden),
the first match is focused, Enter opens it; Esc clears. `Ctrl+F` / `Cmd+F`
focuses the box when the settings page has focus (do not steal it from a
terminal — `/settings` has none, so a plain keydown listener on the page root
is enough).

## 5. i18n

`settings.json`: `settingsNav.group.{general,agents,routing,git,projects}`,
`settingsNav.section.*` (title + description per id), `search.placeholder`,
`search.noMatch`, `back`, `worktrees.*`, `project.*`. Remove `tools.*` keys
that no longer render (keep `tools.label` if `AiToolsModal` still uses it).

## 6. Tests

- `SettingsHub.test.tsx`: route → section, legacy `?tool=` redirect, hidden
  tool section when disabled, mobile select.
- `settingsSearch.test.ts`: ranking order, empty query, no match.
- `WorktreeVisibilitySettings.test.tsx`: writes the phase-1 key, per-project
  override.
- Existing panel tests unchanged except their mount path.
- Snapshots: Settings screens regenerate once.

## 7. Docs

`docs/LANES.md` (worktree visibility, per-project settings), `README.md`
(settings tour), `client/README.md` (route list, primitives), `CLAUDE.md`
marker: "Settings is `/settings/:section` with a grouped nav; a tool's own
settings live under `agents/<id>`; the whole-page search index is
`SETTINGS_INDEX`".

## Acceptance

- Every control reachable before is reachable after (walk `Settings.tsx`'s
  section list and each tool tab, tick them off in the PR body).
- `/settings?tool=codex` lands on `/settings/agents/codex`.
- Typing "pricing" in search shows Routing → Pricing and the Claude/Codex
  pages (both embed the table); Enter opens the first.
- Keyboard: Tab order follows the visual order; `Ctrl+F` focuses search.
- Suites + headers + snapshots green; before/after screenshots.