Add plans for palette, branding, and themes

Updates the planning overview with a new third wave (plans 26–28) and adds three detailed roadmap docs: Command Palette v2, purple phone brand identity rollout, and Appearance v2 theming/tokens/white-label work. Each plan captures dependencies, phased delivery, design decisions, and definition-of-done criteria aligned with prior plans.

Author: jhd3197

docs/plans/00-overview.md

@@ -46,6 +46,17 @@ in their plans — places DeviceKit would lead rather than follow.
 | 24 | [Fleet health & remediation](24-fleet-health-and-remediation.md) | `fleet_sweep` bounded fan-out + doctor/repair allowlist + drift + z-score anomaly + regression forecast (finishes Phase 22); reframes "scale" as discipline not multi-node | 05, 07, 08, 06 |
 | 25 | [Agent lifecycle & backup/DR](25-agent-lifecycle-and-backup.md) | Agent-enforced read-only primitive allowlist, capability negotiation, **OTA agent updates** (greenfield), onboarding state machine, agent-plugin contract, backup + **restore drills** | 07, 05, 08 |
 
+### Third wave (26–28) — palette parity & visual identity
+
+Plans 10 and 12 shipped the first-generation command palette and theming; ServerKit's have
+since grown past them, and DeviceKit never had a real logo. These close both gaps.
+
+| # | Plan | What it borrows | Depends on |
+|---|------|-----------------|------------|
+| 26 | [Command palette v2](26-command-palette-v2.md) | `F1`/`Ctrl+Shift+P` bindings, settings-card index + deep-link flash, frecency ranking, backend `/search` omnisearch (extends 10) | 10, 12, 20 |
+| 27 | [Brand identity: purple phone logo](27-brand-identity-purple-phone.md) | Master-SVG pipeline (squircle + indigo gradient), accent-tinted JSX logo, favicon redraw, Android adaptive-icon alignment, purple default accent | 12, 25 (soft) |
+| 28 | [Appearance v2: themes & tokens](28-appearance-v2-themes-and-tokens.md) | One CSS-token sheet, dark/light/system via `data-theme` + `matchMedia`, 8-preset + custom accent picker, white-label (extends 12) | 12, 27 |
+
 ## Executing a plan
 
 - A local **plan-executor prompt** (`docs/plans/prompt.md`, git-ignored because it

docs/plans/26-command-palette-v2.md

@@ -0,0 +1,117 @@
+# Plan 26 — Command Palette v2: F1, Omnisearch & Settings Deep-Links
+
+**Status:** 📝 planned
+**Inspired by:** ServerKit's current palette stack — `layouts/DashboardLayout.jsx` (three
+open bindings), `components/CommandPalette.jsx` (prefix modes, category weights),
+`data/settingsIndex.js` + `hooks/useSettingFocus.js` (settings deep-links that *flash* the
+card), `utils/paletteFrecency.js` (frecency ranking), and `backend/app/services/search_service.py`
+(a real `/search` entity omnisearch).
+**Depends on:** 10 (✅ shipped — this plan **extends** it, not a rewrite), 12 (settings shell),
+20 (RBAC — gating admin-only results), 16 (docs suite, soft — `?` docs mode)
+
+## Problem
+
+Plan 10 shipped a solid `Ctrl/Cmd+K` palette (cmdk 1.1.1, fuzzy scorer, pages + devices +
+automations + actions + extension entries + FQL `>` mode). Since then ServerKit's palette
+grew four things DeviceKit's lacks, and the user's number-one ask is the first:
+
+1. **More open bindings** — `F1` and `Ctrl/Cmd+Shift+P` (VS Code muscle memory), not just `Ctrl+K`.
+2. **Settings omnisearch** — every settings *card* is indexed; selecting one deep-links to
+   `/settings/<tab>?focus=setting:<id>` and the card scrolls into view and flashes.
+3. **Frecency** — DeviceKit keeps "last 6 recents"; ServerKit ranks by frequency+recency with
+   a 14-day exponential half-life, and blends that score into live ranking.
+4. **Backend `/search`** — entities are fetched via one authz-scoped omnisearch endpoint
+   instead of client-side fetch-all-on-open (which stops scaling past a few dozen devices).
+
+## How ServerKit does it (the parts worth porting)
+
+- **Bindings** live in one `document` keydown in the layout: `cmdK || cmdShiftP || f1` toggles;
+  `e.preventDefault()` on F1 is required (stops browser help).
+- **Prefix modes:** bare = everything, `>` = actions only, `?` = docs only; footer advertises
+  `↵ open · > actions · ? docs · esc close`. *(DeviceKit already uses `>` for FQL — keep that;
+  see Decisions.)*
+- **Settings index:** a flat registry `{ id, label, description, keywords, tab, adminOnly }` →
+  path `/settings/<tab>?focus=setting:<id>`; a `useSettingFocus()` hook on the settings page
+  registers cards by id, scrolls the target into view, and applies a 2 s ring/wash keyframe.
+  A lint script (`scripts/check-settings-index.mjs`) fails CI if a settings tab has zero entries.
+- **Ranking:** cmdk's filter disabled (`shouldFilter={false}`); hand scorer (substring
+  fast-path + prefix/word-boundary bonuses, else ordered subsequence) — DeviceKit already
+  ported this in plan 10. New: final score = `fuzzy + CATEGORY_WEIGHT + min(frecency, 10)`,
+  fixed `GROUP_ORDER`, `PER_GROUP_CAP = 6`, `OVERALL_CAP = 30`.
+- **Backend omnisearch:** `SearchService.search(user, term, workspace)` returns rows
+  `{type, label, sublabel, path}` across all entity tables, authz-scoped; frontend debounces
+  200 ms, min 2 chars, maps `type → category`.
+
+## Design for DeviceKit
+
+### Part 1 — Bindings + frecency (client-only)
+
+- Add `F1` and `Ctrl/Cmd+Shift+P` alongside `Ctrl/Cmd+K` in `CommandPalette.jsx:141-152`
+  (the listener already exists there; keep it there rather than a new hook).
+- Replace the `devicekit_palette_recents` last-6 list with `utils/paletteFrecency.js`
+  (copy ServerKit's ~40-line util: exponential decay, 14-day half-life, `recordUse` /
+  `recentIds(8)` / `frecencyScore`). Key: `devicekit:palette:frecency`.
+- Footer hint row: `↵ open · > query fleet · ? docs · esc`.
+
+### Part 2 — Settings index + deep-link flash + authz
+
+- `data/settingsIndex.js`: one entry per settings *card* across the ~14 panes in
+  `components/settings/` (General, ApiAccess, Security, Users, ApiKeysPane, Workspaces,
+  Vault, AuditLog, AiSettings, Streaming, Bundles, Notifications, Appearance, About).
+- `hooks/useSettingFocus.js` + an `.is-setting-focused` keyframe in `index.css`; Settings
+  panes spread `register(id)` onto each card container.
+- `usePaletteAuthz()`: drop `adminOnly` entries for non-admins (`useAuth().isAdmin`) and
+  respect workspace nav visibility — the palette must never surface a page the sidebar hides.
+- Optional but cheap: a `scripts/check-settings-index.mjs` lint mirroring ServerKit's.
+
+### Part 3 — Backend `/search` omnisearch
+
+- `SearchMixin` (`backend/devicekit/mixins/search.py`, composed before `ApiAppMixin` per the
+  house pattern) + `GET /search?q=` blueprint. Entities: **devices** (name/serial/model),
+  **automations**, **profiles**, **fleet groups**, **extensions**, **jobs** (recent),
+  **users/workspaces** (admin only). Each row `{type, label, sublabel, path}`; scope by the
+  caller's workspace + role (plan 20's `scope_query`).
+- Frontend: in `all` mode, ≥2 chars, debounce 200 ms; replaces the fetch-everything-on-open
+  device/automation providers. Map `type → category` (Devices, Automations, Profiles, Groups,
+  Extensions, Jobs) with lucide icons and category weights (Settings=6, Pages/Actions=4,
+  entities=1); entity hits floor at score 0 so a serial fragment always shows.
+
+## Phases
+
+| Phase | Delivers | Proves |
+|---|---|---|
+| 1 | F1 + Ctrl/Cmd+Shift+P bindings, frecency ranking replacing recents, footer hints | `F1` from any view opens the palette; most-used items float to the top of the empty screen |
+| 2 | Settings card index + `?focus=setting:` deep-link flash + authz gating | typing "retention" → enter lands on `/settings/bundles` with the retention card flashing; non-admins never see Vault/Users entries |
+| 3 | `SearchMixin` + `GET /search`, async entity provider with weights/caps | with 200 devices, typing 3 chars of a serial returns in one debounced request instead of pre-fetching every table |
+
+Phases are independent; 1 is a one-sitting win and should land first since it's the direct ask.
+
+## Decisions to make while executing (log, don't stop)
+
+- **`>` prefix collision:** DeviceKit's `>` is FQL (plan 10's differentiator); ServerKit's is
+  actions-only. **Keep `>` = FQL**, leave actions in the bare mode, add `?` = docs. Log it.
+- **Docs mode targets:** plan 16's docs suite if routable in-app, else external repo links.
+  Hide the category if neither exists yet.
+- **`/search` vs `/api/v1`:** ship as an internal panel route first; mirroring into the public
+  API (plan 21) is follow-up.
+
+## Definition of done
+
+From any view, **F1** (or `Ctrl+K`, or `Ctrl+Shift+P`) opens the palette; typing part of a
+device serial hits `/search` and enter lands on `/node/<id>`; typing part of a settings card
+name lands on the right tab with the card flashing; items you use daily rank above things you
+touched once; `> battery < 20` still runs FQL exactly as plan 10 shipped it.
+
+## Out of scope
+
+- **Cross-device frecency sync.** localStorage-only, like ServerKit.
+- **Palette theming.** Visual refresh rides plans 27/28.
+
+## ServerKit source map (for implementers)
+
+- Bindings: `frontend/src/layouts/DashboardLayout.jsx`
+- Orchestrator + weights/caps/modes: `frontend/src/components/CommandPalette.jsx`
+- Registries: `frontend/src/data/palettePages.js`, `data/commandActions.js`, `data/settingsIndex.js`
+- Utils/hooks: `utils/paletteScore.js`, `utils/paletteFrecency.js`, `hooks/usePaletteAuthz.js`, `hooks/useSettingFocus.js`
+- Backend: `backend/app/api/search.py`, `backend/app/services/search_service.py`
+- Styling: `styles/components/_command-palette.scss`, `styles/components/_ui.scss` (~728–856)

docs/plans/27-brand-identity-purple-phone.md

@@ -0,0 +1,150 @@
+# Plan 27 — Brand Identity: the Purple Phone Logo, Everywhere
+
+**Status:** 📝 planned
+**Inspired by:** ServerKit's branding pipeline — one master SVG
+(`frontend/src/assets/ServerKitLogo.svg`: 2048 viewBox, white squircle tile, diagonal
+indigo gradient `#6366f1 → #4f46e5`), a JSX twin (`components/ServerKitLogo.jsx`) whose
+gradient reads **CSS accent variables** so the mark re-tints with the user's accent (unique
+gradient id per instance via `useId()` — shared ids collide and paint nothing), a
+hand-simplified 32×32 stroke favicon, and `serverkit-agent/packaging/icons/generate_icons.py`
+rasterizing the master into `.ico`/tray icons.
+**Depends on:** 12 (accent CSS vars — the JSX logo tints from them), 25 (soft — OTA can
+ship the re-branded APK fleet-wide once phase 3 rebuilds it)
+
+## Problem
+
+DeviceKit has **three different marks and two different brand colors**:
+
+- Web sidebar + login: the lucide `Layers` glyph in a white square (`App.jsx:145-149`,
+  `auth/Login.jsx:16-21`) — no `Logo` component exists.
+- Web favicon: a *different* custom phone-outline SVG, emerald `#10b981` on `#050505`.
+- **Android agent: already the target identity** — adaptive icon with solid indigo
+  `#6366F1` background + white phone glyph (`ic_launcher_background.xml` /
+  `ic_launcher_foreground.xml`), app theme `colorPrimary #6366F1`, dark purple surfaces
+  (`#0F0D1A` / `#1E1B2E`).
+
+The "og logo" ask = make the agent's purple-tile-with-phone the canonical mark, draw it
+properly as one master SVG in ServerKit's style, and roll it out to every surface.
+
+## Design for DeviceKit
+
+### Part 1 — The master asset + Logo component
+
+- `frontend/src/assets/DeviceKitLogo.svg` — ServerKit's geometry (white inset tile
+  `x/y=150, 1748², rx=150`; gradient squircle ring; glyph in `brandGradient
+  #6366f1 → #4f46e5` diagonal) with the server shelves replaced by a **phone**: rounded
+  body, white screen cutout, speaker slot, home indicator, and the green `#3ddc97` status
+  LED kept for family continuity. Starting draft (refine proportions during execution):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2048 2048">
+  <defs>
+    <linearGradient id="brandGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#6366f1"/>
+      <stop offset="100%" stop-color="#4f46e5"/>
+    </linearGradient>
+  </defs>
+  <rect x="150" y="150" width="1748" height="1748" rx="150" fill="white"/>
+  <!-- outer squircle ring -->
+  <path fill="url(#brandGradient)" fill-rule="evenodd" d="M378,70 H1670 A308,308 0 0 1 1978,378 V1670 A308,308 0 0 1 1670,1978 H378 A308,308 0 0 1 70,1670 V378 A308,308 0 0 1 378,70 Z M450,220 A230,230 0 0 0 220,450 V1598 A230,230 0 0 0 450,1828 H1598 A230,230 0 0 0 1828,1598 V450 A230,230 0 0 0 1598,220 Z"/>
+  <!-- phone body with screen cutout -->
+  <path fill="url(#brandGradient)" fill-rule="evenodd" d="M804,434 H1244 A100,100 0 0 1 1344,534 V1514 A100,100 0 0 1 1244,1614 H804 A100,100 0 0 1 704,1514 V534 A100,100 0 0 1 804,434 Z M794,560 A30,30 0 0 0 764,590 V1390 A30,30 0 0 0 794,1420 H1254 A30,30 0 0 0 1284,1390 V590 A30,30 0 0 0 1254,560 Z"/>
+  <rect x="944" y="481" width="160" height="32" rx="16" fill="white"/>
+  <rect x="924" y="1501" width="200" height="32" rx="16" fill="white"/>
+  <circle cx="1216" cy="628" r="28" fill="#3ddc97"/>
+</svg>
+```
+
+- `frontend/src/components/Logo.jsx` — same paths, gradient stops wired to the accent ramp
+  so the mark follows the user's accent. **Gotcha:** plan 12 stores accent vars as
+  space-separated `R G B` triplets for Tailwind alpha, so stops must be
+  `stopColor="rgb(var(--accent-hover, 90 103 232))"` etc., and the gradient id must come
+  from `useId()` (ServerKit's collision lesson). Props: `size`, `className`.
+
+### Part 2 — Web rollout
+
+- Sidebar header (`App.jsx`) and Login/invite card (`auth/Login.jsx`): swap the white
+  `Layers` square for `<Logo size={…}/>`. About pane gets a 64px one.
+- **Favicon:** replace `frontend/public/favicon.svg` with a 32×32 stroke redraw in
+  ServerKit's favicon style — gradient tile `#6d7cff → #5a67e8`, white 2px stroke phone,
+  green `#3ddc97` LED:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <defs>
+    <linearGradient id="dkFavTile" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#6d7cff"/><stop offset="1" stop-color="#5a67e8"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="7" fill="url(#dkFavTile)"/>
+  <g fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="10.5" y="5" width="11" height="22" rx="2.5"/>
+    <line x1="14.5" y1="23.5" x2="17.5" y2="23.5"/>
+  </g>
+  <circle cx="23" cy="8" r="2.5" fill="#3ddc97"/>
+</svg>
+```
+
+- `index.html`: icon links (svg + ico/png rasters if practical), title stays `DeviceKit`.
+  Add `public/manifest.json` (name `DeviceKit`, `theme_color #4f46e5`,
+  `background_color #000000`, icon `/favicon.svg` maskable) if absent.
+
+### Part 3 — Brand color: purple becomes the default accent
+
+- `theme.js`: `DEFAULT_ACCENT` `#10b981` → **`#6d7cff`** (ServerKit's live periwinkle;
+  the static logo asset keeps the deeper `#6366f1/#4f46e5` pair — same two-purples split
+  ServerKit uses). Add Periwinkle/Indigo to `ACCENT_PRESETS`; update the
+  `appearance.accent` default in `SETTINGS_DEFAULTS`.
+- **Semantic emerald is untouched** — plan 12's rule stands: online/pass/success stays
+  `#10b981`; only brand chrome rides the accent ramp. Users with a stored accent keep it
+  (settings row wins); only the default changes.
+
+### Part 4 — Android agent alignment
+
+- `ic_launcher_background.xml`: solid `#6366F1` → the diagonal gradient (VectorDrawable
+  `<gradient>` inside the adaptive background, API 26+ — already the minimum for
+  `mipmap-anydpi-v26`). Align `ic_launcher_foreground.xml`'s phone glyph with the master's
+  proportions; touch `ic_notification.xml` if it drifts. App label stays `DeviceKit Agent`.
+- Rebuild via the `build-agent-apk` skill; distribute through plan 25's OTA channel once
+  live (until then, hand-flash — same as every agent change today).
+
+## Phases
+
+| Phase | Delivers | Proves |
+|---|---|---|
+| 1 | Master SVG + `Logo.jsx` + sidebar/login/About swap + favicon + manifest | one mark everywhere on web; changing the accent re-tints the sidebar logo live |
+| 2 | Purple default accent (`#6d7cff`), presets updated, settings default | a fresh install boots purple; an existing user's chosen accent survives |
+| 3 | Android adaptive-icon gradient + glyph alignment + APK rebuild | the launcher icon on a real device matches the web favicon family |
+
+## Decisions to make while executing (log, don't stop)
+
+- **Sidebar tile treatment:** full `<Logo/>` mark vs ServerKit's sidebar pattern (lucide
+  glyph in a small accent-gradient tile). Recommend the real `<Logo/>` at 26–32px — DeviceKit
+  finally has a mark; use it.
+- **Raster favicons** (`.ico`, 16/32 png): generate if a quick tool is at hand
+  (sharp/cairosvg one-liner); the SVG link alone covers modern browsers — don't block on it.
+- **`index.html` title** currently `DeviceKit Pro | SamanLabs` — normalize to `DeviceKit`
+  (PageTitle already overrides at runtime).
+
+## Definition of done
+
+Sidebar, login, About, browser tab, and the Android launcher all show the same purple
+phone-in-squircle family; the web mark re-tints when the accent changes; no `Layers`-as-logo
+usage remains (grep `Layers` in App.jsx/Login.jsx); phase 3's APK on a physical device shows
+the gradient icon.
+
+## Out of scope
+
+- **Light/system theme + white-label** — plan 28 (white-label will let users *replace* this
+  logo; it needs `Logo.jsx` to exist first).
+- **Desktop/tray icon pipeline** (ServerKit's `generate_icons.py`) — DeviceKit has no desktop
+  agent; revisit if one appears.
+
+## ServerKit source map (for implementers)
+
+- Master SVG: `frontend/src/assets/ServerKitLogo.svg` (geometry to clone)
+- JSX twin + useId gotcha: `frontend/src/components/ServerKitLogo.jsx`
+- Favicon style: `frontend/public/favicon.svg`; manifest: `frontend/public/manifest.json`
+- Sidebar tile alternative: `components/Sidebar.jsx:325-330` + `styles/components/_sidebar.scss:179`
+- Icon rasterization reference: `serverkit-agent/packaging/icons/generate_icons.py`