feat(cloud-frontend): visual review harness + dashboard redesign + palette purge

Loop 1+2 of the cloud-frontend UI review grind. Adds the manual-review
protocol that any UI-touching agent must follow, extends the audit spec
to 53 routes × 2 viewports with rest+hover screenshots and palette
violation detection, redesigns the dashboard home, and removes blue
from the entire user-facing surface.

Harness + protocol
- packages/cloud-frontend/AGENTS.md — manual visual review protocol
  (run command, output layout, per-page review markdown rules, 5-loop
  discipline, checklist template).
- packages/cloud-frontend/tests/e2e/aesthetic-audit.spec.ts — expanded
  from ~30 to 53 routes (every path in src/App.tsx incl. parameterized
  routes via e2e-fixture id); captures <slug>--hover.png after hovering
  the first primary button; detects orange<->black hover transitions,
  neutral->orange hover destinations, and any blue color; auto-stubs
  manual-review/<slug>.md for every route; H1/H2/H3 fixes (anon-mode
  for public routes, mocked API endpoints for auth routes, networkidle
  wait so loading skeletons don't get captured).
- packages/cloud-frontend/package.json — audit:cloud script.
- CLAUDE.md — points at the new protocol.
- packages/cloud-frontend/aesthetic-audit-output/LOOP_1_TRIAGE.md —
  loop-1 baseline findings.

E2E expansion
- tests/e2e/_helpers/siwe-session.ts — reusable
  loginWithInjectedEthereum helper extracted from siwe-flow.spec.ts.
- tests/e2e/blue-banned.spec.ts — source-grep + runtime HSL-bucket
  enforcement of the no-blue rule across 8 key pages.
- tests/e2e/focus-rings.spec.ts — tabs through each page asserting
  visible focus outline/box-shadow/border.
- docs/E2E_COVERAGE_GAPS.md — per-page enumeration of untested
  interactive surfaces with concrete test recipes.

Dashboard redesign
- src/dashboard/Page.tsx — new IA: greeting, credit balance + top-up
  CTA, 4-up stat row (agents/containers/apps/keys), agents grid,
  secondary cards (earnings/affiliates/docs), deep-link pills. Reuses
  existing hooks; no new endpoints; replaces DashboardActionCards
  (which mixed blue + orange->black hover).
- docs/DASHBOARD_REDESIGN.md — design rationale.

Color/hover system
- docs/HOVER_SYSTEM.md — palette rules (orange-rest hovers
  orange-darker; neutral-rest hovers neutral; blue banned).
- 70 blue Tailwind classes removed across 35 source files.
- packages/ui/src/styles/theme.css — --brand-blue remapped to neutral;
  --status-success → green; --status-info → neutral.
- packages/ui/src/cloud-ui/components/connection-card.tsx — tone="blue"
  callout remapped to neutral.
- docs/BLUE_FOLLOWUP.md — documents remaining blue in @elizaos/ui
  cloud-ui components (out of this session's scope).

Loops 3-5 (visual layout polish, a11y, mobile, designer-eye sign-off)
require running `bun run --cwd packages/cloud-frontend audit:cloud` and
filling in each manual-review/<slug>.md verdict — that's the iterative
loop the new infrastructure enables.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Shaw

packages/cloud-frontend/AGENTS.md

@@ -0,0 +1,105 @@
+# Cloud Frontend — Manual Visual Review Protocol
+
+Any coding agent that touches UI in `packages/cloud-frontend/` MUST follow this
+protocol before declaring work complete. The protocol exists because automated
+e2e specs catch only what they assert — hover-state regressions, palette drift,
+broken empty states, and mobile layout breaks slip through. A visual audit +
+human-style page-by-page review is the only reliable gate.
+
+## Run the audit
+
+```bash
+bun run --cwd packages/cloud-frontend audit:cloud
+```
+
+This runs `tests/e2e/aesthetic-audit.spec.ts` headless against the local
+preview server and opens `aesthetic-audit-output/contact-sheet.html` in your
+default browser when finished.
+
+The audit walks every route in `src/App.tsx` (public + dashboard, including
+parameterized routes hit with an invalid `e2e-fixture` id so the empty/error
+state is captured) at desktop (1440x900) and mobile (390x844) viewports.
+
+## Where outputs land
+
+```
+packages/cloud-frontend/aesthetic-audit-output/
+  desktop/<slug>.png            full-page screenshot at rest
+  desktop/<slug>--hover.png     full-page screenshot with first primary button hovered
+  mobile/<slug>.png
+  mobile/<slug>--hover.png
+  manual-review/<slug>.md       human-authored review notes (REQUIRED for every route)
+  contact-sheet.html            grid view of every screenshot + flagged issues
+  report.json                   machine-readable per-page audit data
+```
+
+Stub `manual-review/<slug>.md` files are auto-generated for every route the
+first time the audit runs. Existing files are never overwritten — the human
+notes are the source of truth.
+
+## The manual review loop
+
+For every UI change, run this loop until verdict is `good` for every page you
+touched (and every page your change can reach transitively — global header,
+footer, layout, theme, button primitives, etc.):
+
+1. Run `bun run --cwd packages/cloud-frontend audit:cloud`.
+2. Open `aesthetic-audit-output/contact-sheet.html`. Walk every page that
+   could be affected.
+3. For each affected page, open `manual-review/<slug>.md` and fill in:
+   - **Visual issues** — anything that looks wrong, broken, or off-brand.
+   - **Color / hover violations** — quote the element + rest/hover colors.
+     Project rules: brand orange (#ff8a00-ish) is accent only, never a hover
+     destination from neutral; orange<->black hover transitions are banned;
+     blue is banned from the palette entirely.
+   - **Layout breaks** — viewport + element.
+   - **Interaction targets to add to e2e** — buttons/links that should have
+     automated coverage.
+   - **Verdict** — `good`, `needs-work`, or `broken`.
+4. Fix the issues.
+5. Commit screenshots + manual-review markdown + code fixes together (one
+   commit per loop iteration is fine).
+6. Re-run the audit and repeat. Allow up to 5 loops per page. If a page is
+   still not `good` after 5 loops, escalate — do not declare done.
+
+## Rules
+
+- **Every page must have a screenshot AND a `manual-review/<slug>.md`** with
+  a verdict checked into the repo. A page with no review markdown is a page
+  that was never reviewed.
+- **Do not mark a UI task complete with any page at verdict `needs-work` or
+  `broken`.** Either fix it or document why it is acceptable in the markdown.
+- **Never overwrite an existing `manual-review/<slug>.md`** — the human notes
+  are load-bearing. The audit only writes stubs for new routes.
+- **The contact sheet is not the review.** It is the index. The review lives
+  in the per-page markdown.
+
+## Checklist template (mirrored in every stub)
+
+- [ ] Header / nav present and aligned
+- [ ] Logo size + nav padding match other pages
+- [ ] No blue colors anywhere (banned)
+- [ ] Hover states do not transition orange<->black on the same element
+- [ ] Focus ring visible on every interactive element (tab through)
+- [ ] Empty state renders cleanly
+- [ ] Loading state renders cleanly (no layout jump)
+- [ ] Mobile layout: no horizontal scroll, tap targets >= 44px
+- [ ] Text contrast meets WCAG AA
+- [ ] Border radius is 3px (xs) or pill — no other values
+- [ ] No console errors at rest
+- [ ] No 5xx network requests
+
+## What the spec auto-flags
+
+You don't need to eyeball these — the spec already detects them and lists
+them on each contact-sheet card and in `report.json`:
+
+- console errors and `pageerror` events
+- non-401/403/404 failed network responses
+- border-radius values outside {0, 3px, pill}
+- palette violations: orange<->black hover transitions, neutral->orange
+  hover destinations, any blue color on buttons (rest, hover, or focus ring)
+
+Your job in the manual review is to catch what the spec can't: spacing,
+typography rhythm, contrast, empty/loading state quality, mobile breaks,
+keyboard navigation, and overall brand fit.

packages/cloud-frontend/aesthetic-audit-output/LOOP_1_TRIAGE.md

@@ -0,0 +1,126 @@
+# Loop 1 — baseline triage of existing screenshots
+
+Generated 2026-05-21 from `aesthetic-audit-output/desktop/*.png` (last run
+before wave-1 changes). Per-page reviews will land under
+`manual-review/<slug>.md` once that directory exists; this file is the
+roll-up so loop 2 can act on it.
+
+## Cross-cutting harness bugs (block accurate evaluation)
+
+These must be fixed in `tests/e2e/aesthetic-audit.spec.ts` BEFORE
+remaining loops produce trustworthy artifacts. Loop-2 prereqs.
+
+### H1. `landing.png` captures the dashboard, not `/`
+The harness runs with `VITE_PLAYWRIGHT_TEST_AUTH=true` which keeps the
+mock session active. When visiting `/`, the app redirects authed users
+to `/dashboard`. Result: `landing.png` shows the dashboard (Instances
+empty state with "No agents yet"), not the marketing landing page.
+
+**Fix:** Split the audit into two passes — a public pass (no test-auth
+cookie cleared) and an authed pass. Routes listed `auth: false` should
+run with the session cleared via `await context.clearCookies()` and a
+fresh storageState.
+
+### H2. `dashboard-api-keys.png`, `dashboard-containers.png` render "Something went wrong / Unauthorized"
+Test-auth mode passes the UI gate (JWT decoded), but the API treats the
+mock token as unauthorized for these endpoints. Result: the
+audit captures the error boundary, not the page content.
+
+**Fix:** Either (a) extend the test-auth backend stub to honour these
+endpoints, or (b) intercept API calls inside the audit spec with
+`page.route(...)` to return canned fixtures per route. Option (b) is
+strictly local and won't require backend changes.
+
+### H3. `dashboard-billing.png`, `dashboard-settings.png` captured during loading skeleton
+Empty header (no "Billing" / "Settings" title), four placeholder
+rectangles, no real content. The audit fires the screenshot before
+content settles.
+
+**Fix:** Add per-route "ready" waits. Easiest: wait for a
+`[data-testid="<slug>-ready"]` element on each page; add the testid in
+source where the page mounts its real content. Backup: wait until
+`networkidle` AND no `[aria-busy="true"]` element in the main region.
+
+### H4. No hover-state screenshots yet
+Subagent A is adding `<slug>--hover.png` for the primary button — once
+that lands, re-run.
+
+### H5. No mobile screenshots reviewed yet
+The mobile screenshots are in `aesthetic-audit-output/mobile/` but
+haven't been triaged. Loop-4 task.
+
+---
+
+## Page-level findings (desktop only — first pass)
+
+### `/` (landing) → SEE H1 — currently shows dashboard, not landing
+Cannot evaluate until H1 fixed.
+
+### `/login` (`login.png`)
+- Looks tight visually. Logo + cloud bg.
+- Email field → "Passkey" / "Magic Link" / "Ethereum" / "Solana" buttons.
+- ✅ no blue. ✅ orange CTA `Passkey` with neutral siblings.
+- **UX**: "Developer Dashboard" button top-right is confusing on a sign-in screen — what does it mean before login? Consider removing or renaming.
+- **Test gap**: error case when wallet user rejects sig (see `docs/E2E_COVERAGE_GAPS.md`).
+
+### `/bsc` (`bsc.png`)
+- Marketing-style purchase card. Looks clean.
+- Cloud bg + white card. Mobile not yet checked.
+- ✅ no obvious blue/orange-black hover. Confirm hover state once `--hover` shots exist.
+
+### `/dashboard` (`dashboard-home.png`) — REDESIGN IN PROGRESS (subagent C)
+- **VIOLATION**: "API Access" card is solid **blue** (`bg-blue-500` family). Banned. Subagent B should catch this.
+- Layout dominated by oversized marketing card "Run your Eliza agent on the hosted runtime" + 5 colored tiles. Feels like onboarding, not a dashboard.
+- "My Agent (0)" section is mostly empty → "Launch Instance" CTA. Reasonable empty state but the whole page is empty state.
+- Header right side: 🇺🇸 EN dropdown, "Invite" button, "LO" avatar. OK.
+- Sidebar shows "Dashboard" highlighted with thin orange left bar. Good.
+- **Test gap**: every tile's CTA → assert correct route.
+
+### `/dashboard/agents` (`dashboard-agents.png`)
+- Title bar shows "Instances" not "Agents" — naming inconsistency between sidebar ("Instances") and the historical route (`/dashboard/agents`).
+- Usage & Rates card: RUNNING/IDLE/YOUR COST/REMAINING tiles. Visually OK; colors fine.
+- Empty state: centered "No agents yet" + "New Agent" button. Good.
+- **VIOLATION CHECK**: "New Agent" button rests white → confirm hover doesn't go to orange or black-from-orange. Captured `--hover.png` needed.
+- **Test gap**: click "New Agent" → navigates to creation flow.
+
+### `/dashboard/api-explorer` (`dashboard-api-explorer.png`)
+- **VIOLATION**: blue HTTP-method badges (`POST` is solid blue). Subagent B must replace.
+- **VIOLATION**: "Auth" tab uses blue accent on selection. Replace with white/black or orange.
+- Endpoints list looks good otherwise.
+- Search + category chips work visually.
+- **Test gap**: each method badge color asserted in `blue-banned.spec.ts`.
+
+### `/dashboard/api-keys` → SEE H2 — error state captured
+### `/dashboard/containers` → SEE H2 — error state captured
+### `/dashboard/billing` → SEE H3 — skeleton captured
+### `/dashboard/settings` → SEE H3 — skeleton captured
+
+---
+
+## Net findings for loop 2
+
+1. **Fix the harness first** (H1–H3). Without that, screenshots for
+   ~half of dashboard routes are meaningless.
+2. **Blue eradication is broader than just hover classes** — subagent B
+   should also catch the dashboard-home "API Access" card and the
+   API-explorer method/auth badges (these are in component source, not
+   just Tailwind utility classes).
+3. **Sidebar label "Instances" vs route `/dashboard/agents`** — pick
+   one. The dashboard tile says "My Agent", the sidebar says
+   "Instances", the page heading says "Instances". Customer mental
+   model breaks. Decide on the canonical word and rename.
+4. **Header `/dashboard` title is just "Dashboard"** — once redesign
+   lands, give it a clearer title or remove the title bar entirely.
+5. **Per-page testids** required for H3 fix — emit
+   `data-testid="<slug>-ready"` on each dashboard page root once
+   content loads.
+
+## Loop 2 work derived from this triage
+
+(Tracked in TaskList.)
+
+- Fix H1, H2, H3 in `aesthetic-audit.spec.ts`.
+- Add per-page `data-testid` ready markers.
+- Add `blue-banned.spec.ts` enforcement.
+- Land subagent B's hover/color sweep including the dashboard-home blue card and API-explorer method badges.
+- Decide sidebar terminology: Instances vs Agents. Implement once.

packages/cloud-frontend/docs/BLUE_FOLLOWUP.md

@@ -0,0 +1,42 @@
+# Blue followup — `@elizaos/ui` components
+
+The cloud-frontend `src/` tree is now blue-free (verified by grep + the
+runtime `tests/e2e/blue-banned.spec.ts` check). Remaining blue lives in
+the shared `@elizaos/ui` package's cloud-ui subdir. These components are
+consumed by cloud-frontend, so the visual leak is still real — but
+fixing them is a sweep through a different package that wasn't in this
+session's scope.
+
+## Files still containing blue (as of 2026-05-21)
+
+| File | What's blue | Suggested replacement |
+| --- | --- | --- |
+| `packages/ui/src/cloud-ui/components/log-viewer.tsx:133,157` | `info` log severity → `text-blue-300 border-l-blue-500` | Neutral: `text-white/70 border-l-white/30` |
+| `packages/ui/src/cloud-ui/components/glowing-stars.tsx:160` | `bg-blue-500 shadow-blue-400` decorative | Orange or white; this is a decorative effect, pick from brand palette |
+| `packages/ui/src/cloud-ui/components/timeline.tsx:90` | `via-blue-500` gradient stop | `via-orange-500` or remove |
+| `packages/ui/src/cloud-ui/components/promote-app-dialog.tsx:236,241,249,263,446` | Selected-state highlight for "social" channel option | Orange-accent: `border-orange-500/50 bg-orange-500/10 text-orange-300` |
+
+Already handled in this session:
+
+- `connection-card.tsx` — `tone="blue"` callout remapped to neutral
+  `bg-white/5 border-white/15 text-foreground`. Three settings pages
+  (`microsoft-connection.tsx`, `telegram-connection.tsx`,
+  `whatsapp-connection.tsx`) still pass `tone="blue"` but now render
+  correctly thanks to the source-level remap; the prop name can be
+  renamed to `"info"` in a future cleanup pass.
+
+## CSS variables
+
+`packages/ui/src/styles/theme.css` has been edited so that
+`--brand-blue` (still defined for legacy callers) resolves to a neutral
+black/white opacity instead of `#0b35f1`. `--status-success` and
+`--status-info` were remapped off blue. The dist file
+`packages/ui/dist/styles/theme.css` is stale — running the package's
+build (or any consumer rebuild) will refresh it.
+
+## Verification
+
+Run `bun run --cwd packages/cloud-frontend test:e2e -- blue-banned`
+after the @elizaos/ui rebuild lands. The source-grep portion already
+passes; the runtime check will catch any remaining `var(--brand-blue)`
+fallthrough.

packages/cloud-frontend/docs/DASHBOARD_REDESIGN.md

@@ -0,0 +1,109 @@
+# Dashboard Index Redesign
+
+`/dashboard` (`src/dashboard/Page.tsx`) is the first authenticated surface a
+user sees. The legacy version showed a hero, a 5-card action strip
+(`DashboardActionCards`), and a 4-up "My Agents" grid. It mixed marketing
+copy, brand-blue chrome, and orange→black hover transitions, and surfaced
+no real state about the user's account.
+
+## Audiences (single page, four hats)
+
+1. **App creators** — building monetized apps. Want app health + earnings.
+2. **Agent operators** — running Eliza agents. Want container/agent status.
+3. **Inference customers** — using the model gateway. Want credit balance + API keys.
+4. **Affiliates** — referring users. Want a referral link they can copy.
+
+## Signal > noise: 6 things on first load
+
+1. **Greeting + credit balance** — what's in the wallet right now.
+2. **Top-up CTA** — single primary action for inference customers.
+3. **Agents snapshot** — count and a "Manage" affordance.
+4. **Containers snapshot** — running / total instances.
+5. **Apps snapshot** — count of deployed apps and a link to monetization.
+6. **API keys + Earnings + Referrals row** — three small, low-priority chips.
+
+Everything deeper (analytics, billing history, security, admin) lives behind
+the sidebar; the index does not duplicate it.
+
+## Layout (ASCII)
+
+```
++--------------------------------------------------------------+
+| Eyebrow: elizaOS Platform / Eliza Cloud                      |
+| H1: Welcome back, <name>                                     |
+| Sub: One-line status (e.g. "<n> agents, $X balance")         |
++--------------------------------------------------------------+
+
++-------------------- Balance (wide) ------+-- Top up (CTA) ---+
+| $12.34                                   |  Add credits  →   |
+| Credit balance                           |                   |
++------------------------------------------+-------------------+
+
++-- Agents (2x) ---------+-- Containers ---+-- Apps ----------+
+| 3 agents               | 2 / 3 running   | 1 deployed       |
+| [Manage]               | [Instances]     | [Apps]           |
++------------------------+-----------------+------------------+
+
++-------------- Agents Grid (existing AgentsSection) ----------+
++--------------------------------------------------------------+
+
++-- API keys ---+-- Earnings ---+-- Referrals ---+-- Docs -----+
+| 2 keys        | View          | Copy link      | Read        |
++---------------+---------------+----------------+-------------+
+```
+
+## Card spec
+
+| Card        | Hook / source                       | Empty state           | Skeleton          | Primary CTA              |
+| ----------- | ----------------------------------- | --------------------- | ----------------- | ------------------------ |
+| Balance     | `useCreditsBalance()`               | "—" + Add credits     | Pulse on number   | `/dashboard/billing`     |
+| Top-up      | static                              | n/a                   | n/a               | `/dashboard/billing`     |
+| Agents      | existing `useDashboardData`         | "No agent yet"        | Existing skeleton | `/dashboard/my-agents`   |
+| Containers  | `useContainers()`                   | "0 instances"         | Pulse on counts   | `/dashboard/containers`  |
+| Apps        | `useApps()`                         | "No apps yet"         | Pulse on counts   | `/dashboard/apps`        |
+| API keys    | `useApiKeys()`                      | "0 keys"              | Pulse on number   | `/dashboard/api-keys`    |
+| Earnings    | static link                         | n/a                   | n/a               | `/dashboard/earnings`    |
+| Referrals   | `useDashboardReferralMe()`          | "Generate link"       | Pulse             | copy referral URL        |
+| Docs        | static link                         | n/a                   | n/a               | `/docs`                  |
+
+All numeric stats are rendered from authoritative server responses; no
+client-side computation beyond formatting (`toFixed`, `length`, simple
+counts of an already-fetched array). No fallback `?? 0` math that would
+hide a broken pipeline — when a query errors, the card shows "—".
+
+## What's omitted (and why)
+
+- **Marketing copy / pitch headline** — this is an authenticated console,
+  not a landing page. The header is the user's name + status.
+- **Analytics charts** — `useAnalyticsBreakdown` is heavy and belongs on
+  `/dashboard/analytics`. Surfacing one chart here would duplicate it.
+- **Billing/invoices list** — already on `/dashboard/billing` and
+  `/dashboard/invoices`.
+- **Security panel** — settings live in `/dashboard/security`.
+- **Admin chrome** — admins reach it via the sidebar.
+- **App creation wizard** — the Apps card links to the dedicated route.
+- **`DashboardActionCards`** — the existing brand card strip mixes blue
+  (`#0B35F1`) and orange→black hover, both forbidden by the redesign
+  constraints. We rebuild a smaller, monochrome+orange variant inline.
+
+## Colors & hover
+
+- Neutral: `bg-white/[0.04]`, border `border-white/10`, text `text-white`
+  with `text-white/60` for muted lines.
+- Accent: `#FF5800` for the single primary balance/CTA card.
+- Hover:
+  - Orange resting → `hover:bg-[#E04E00]` (darker orange).
+  - Neutral resting → `hover:bg-white/[0.06]` (subtle white opacity).
+  - **No** orange→black, **no** blue anywhere.
+
+## Reuse
+
+- `AgentsSection` / `AgentsSectionSkeleton` — kept verbatim.
+- `DashboardPageWrapper`, `DashboardPageContainer`, `DashboardPageStack`,
+  `DashboardLoadingState` — kept.
+- `BrandButton`, `BrandCard` — for buttons and the framed cards.
+- Hooks: `useCreditsBalance`, `useContainers`, `useApps`, `useApiKeys`,
+  `useDashboardReferralMe`, plus the existing `/api/v1/dashboard` fetch
+  for agents.
+
+No new endpoints, no new dependencies.