# Nexus Phase 13 — Settings Consolidation

> Use `superpowers:test-driven-development`. Commit atomically per section.

**Goal:** Collapse the current Paperclip nested instance-settings tree (`/instance/settings/general`, `/instance/settings/integrations`, …) into a **single-column scroll page** at `/instance/settings/general` (the URL stays so existing bookmarks still work) with ~8 section cards per `docs/specs/2026-04-11-nexus-layout-overhaul.md` §8. Move the Skill Aggregator, Routines, Telegram bridge, and re-run onboarding link into section cards. Drop the nested sub-routes from App.tsx (they redirect to the single page).

**Source of truth:** spec §8 (Mode 4 — Settings). Phase 8 established the frame; the Settings destination in the IconRail already points at `/instance/settings/general`.

**Branch:** `nexus/design-system-migration`.

---

## Ownership boundaries

**You may create or modify ONLY:**

| Path | Action |
|---|---|
| `ui/src/pages/InstanceSettings.tsx` (or equivalent single page) | Major rewrite into single-column scroll |
| `ui/src/pages/instance/settings/**` or sub-pages | Modify — kill the child sub-pages, fold into sections |
| `ui/src/components/settings/**` | Create (new subdir for section cards) |
| `ui/src/App.tsx` | Routes may be removed (nested settings sub-routes) — see note |

**Exception on App.tsx:** Phase 13 is the one phase where routing changes ARE owned by the phase, because the instance-settings tree is being collapsed. You may remove nested `/instance/settings/integrations`, `/instance/settings/adapters`, etc. routes and replace them with `<Navigate to="/instance/settings/general" replace />` redirects so existing bookmarks still work. Do not touch any other App.tsx route.

**You MUST NOT touch:**

- `ui/src/pages/PersonalAssistant.tsx`, `ui/src/components/assistant/**` (Phase 9/12)
- `ui/src/pages/Projects.tsx`, `ui/src/pages/ProjectDetail.tsx`, `ui/src/components/projects/**` (Phase 11)
- `ui/src/pages/ContentStudio.tsx`, `ui/src/pages/StudioWorkshopDetail.tsx`, `ui/src/components/studio/**` (Phase 10)
- `ui/src/components/Layout.tsx`, `ui/src/components/frame/**` (Phase 8)
- Any backend code

---

## Scope (strictly)

### Section cards per spec §8.1

1. **WORKSPACE** — root directory, theme toggle (dark/light), re-run onboarding link
2. **LOCAL AI** — Hermes provider, Whisper STT model, Piper TTS voice
3. **CLOUD PROVIDERS** — Anthropic / OpenAI API keys (masked), Puter.js status
4. **SKILLS** — Skill Aggregator browse/install/assign (currently wherever it lives; Phase 13 folds it in)
5. **ROUTINES** — list of workspace routines with edit/pause (currently the top-level `/routines` route — folded in; that route stays for backwards compat)
6. **TELEGRAM BRIDGE** — bot token, allowed chat IDs
7. **ABOUT** — Nexus version, fork info, MIT license
8. **DANGER ZONE** — reset workspace, delete all conversations

Each card: 1px charcoal border, 8px radius, 24px padding, transparent fill. Uppercase 1.4px-tracked title in silver + hairline rule. Sections listed vertically with 24px gap.

### What to preserve from the existing nested pages

- All existing form state, field validation, save handlers
- The API endpoints each section uses (likely `instanceSettingsApi`, `skillsApi`, `routinesApi`, etc.)
- Access control checks (though single-user self-hosted, some checks may still exist)

### What to kill from the chrome

- The old left-rail `InstanceSidebar` that showed nested settings sub-links — already unmounted by Phase 8 but the component file may linger; delete it in Phase 13 along with its test file
- Any `/instance/settings/*` sub-routes other than `/general`

---

## File plan

| File | Action |
|---|---|
| `ui/src/pages/InstanceSettings.tsx` (or the existing main settings page file) | Rewrite into single-column scroll that renders 8 section cards |
| `ui/src/components/settings/WorkspaceSection.tsx` | Create |
| `ui/src/components/settings/LocalAISection.tsx` | Create |
| `ui/src/components/settings/CloudProvidersSection.tsx` | Create |
| `ui/src/components/settings/SkillsSection.tsx` | Create (embeds Skill Aggregator) |
| `ui/src/components/settings/RoutinesSection.tsx` | Create (reuses routines list components) |
| `ui/src/components/settings/TelegramSection.tsx` | Create |
| `ui/src/components/settings/AboutSection.tsx` | Create |
| `ui/src/components/settings/DangerZoneSection.tsx` | Create |
| Each section + `.test.tsx` for tests | Create tests |
| `ui/src/components/InstanceSidebar.tsx` | Delete (was a Phase 8 legacy candidate) |
| `ui/src/App.tsx` | Strip nested `/instance/settings/*` sub-routes except `/general`; add redirect stubs |

---

## Implementation notes

### Single-page layout

```tsx
export function InstanceSettings() {
  return (
    <div className="mx-auto w-full max-w-[960px] px-6 py-8 space-y-6">
      <h1 className="text-[14px] font-semibold uppercase tracking-[0.1em] text-primary">
        Settings
      </h1>
      <WorkspaceSection />
      <LocalAISection />
      <CloudProvidersSection />
      <SkillsSection />
      <RoutinesSection />
      <TelegramSection />
      <AboutSection />
      <DangerZoneSection />
    </div>
  );
}
```

### Section card skeleton

Every section uses the same shell:

```tsx
export function SettingsSection({ title, children }: { title: string; children: ReactNode }) {
  return (
    <section
      aria-label={title}
      className="rounded-[8px] border border-border bg-transparent p-6"
    >
      <header className="mb-4">
        <h2 className="text-[12px] font-semibold uppercase tracking-[0.14em] text-muted-foreground">
          {title}
        </h2>
        <hr className="mt-2 border-border" />
      </header>
      <div className="space-y-4">{children}</div>
    </section>
  );
}
```

Consider extracting `SettingsSection` as a shared primitive in `components/settings/SettingsSection.tsx` and importing it from all 8 section files — that's 9 files total but keeps each section shell 1-line and eliminates drift.

### Routines fold-in strategy

The existing `/routines` top-level route and its page stay. The Routines section in Settings either:
- (a) renders a compact read-only list of routines with an "open full routines page" link that navigates to `/routines`, OR
- (b) renders the full interactive routines UI inline

**Recommendation (a)** — single responsibility per page. Phase 16 decides whether to delete `/routines`.

### Skills fold-in

Same pattern: the Skills section embeds the Skill Aggregator UI inline (browse + installed count + assignments) OR links out to a Skill Aggregator page if one exists. Read the codebase to find where Skills currently live. If there's an existing route, link to it from the section; if it's unrouted, embed the component.

---

## Acceptance criteria

1. `/instance/settings/general` renders a single-column scroll page with 8 section cards
2. Any previous `/instance/settings/<sub>` URL (e.g., `/instance/settings/integrations`) redirects to `/instance/settings/general`
3. The theme toggle in the WORKSPACE section switches between light/dark and persists
4. API key fields mask their values and never log them
5. All new components have tests using the Phase 8 pattern
6. `npx vitest run src/components/settings/` passes
7. `npx tsc --noEmit 2>&1 | grep -E "(settings/|InstanceSettings\.tsx)"` clean
8. `InstanceSidebar.tsx` deleted (and any other dead settings chrome files)
9. No file outside declared ownership touched
10. Existing settings functionality preserved — nothing breaks

---

## Before you begin

Read:
- `ui/src/pages/InstanceSettings.tsx` (or whatever the main settings page is named)
- Any nested settings sub-pages (grep for `InstanceSettings*.tsx` or look under `ui/src/pages/instance/settings/`)
- `ui/src/api/instanceSettings.ts` for the API shape
- The current routines list component and skills aggregator UI locations

---

## Report format

- Status
- Commit SHAs
- Files created / modified / deleted
- Tests added / passing
- Typecheck result
- Nested sub-routes removed and their redirect targets
- Skill Aggregator fold-in strategy (inline vs link-out)
- Routines section strategy (compact list vs full inline)
- Concerns, deviations, self-review