waggle-os/docs/superpowers/plans/2026-07-08-ux-phase-1-corrections.md

UX Phase 1 Corrections Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Remove the trust, coherence, responsive layout, shortcut, visual-regression, and route-evidence blockers that currently prevent the five-persona UX judge gate from honestly reaching 9/10.

Architecture: Keep all fixes inside existing Waggle surfaces. Do not create new pages, flows, or abstractions unless a tiny local helper is needed to make an existing surface testable. Use current route shell, Settings app, auth provider, marketplace/visual tests, and judge artifacts as the proof path.

Tech Stack: React 19, TypeScript, Vite, Tailwind 4, Fastify local sidecar, Vitest, Playwright.

---

Source Artifacts

• Findings: docs/audits/2026-07-08-complete-ux-usage-audit.md
• Route/scenario manifest: docs/audits/2026-07-08-ux-route-scenario-manifest.md
• Judge scorecards: docs/audits/2026-07-08-five-persona-judge-scorecards.md
• Correction register: docs/audits/2026-07-08-ux-correction-register.md
• Mobile Executive evidence supplement: docs/audits/2026-07-08-mobile-executive-t2-t12-analysis.md
• First-run onboarding evidence supplement: docs/audits/2026-07-08-first-run-onboarding-t1-t2-t12-analysis.md

Files by Responsibility

• packages/server/src/local/security-middleware.ts: local CSP/security headers.
• packages/server/tests/local/security-middleware.test.ts: CSP/security header assertions.
• apps/web/src/lib/clerk.ts: Clerk publishable-key resolution and accountless decision point.
• apps/web/src/providers/WaggleClerkProvider.tsx: optional Clerk mounting.
• apps/web/src/components/os/apps/SettingsApp.tsx: Settings layout, copy, backup alerts, billing copy.
• apps/web/src/components/os/overlays/OnboardingWizard.tsx: first-run wizard shell and mobile action row.
• apps/web/src/components/os/overlays/onboarding/WhoAreYouStep.tsx: first-run Profile step density and Continue reachability.
• apps/web/src/components/os/AppShell.tsx: active workspace resolution, route-changing overlay behavior, shortcut target.
• apps/web/src/hooks/useKeyboardShortcuts.ts: Ctrl+Shift+N dispatch path.
• apps/web/src/components/os/overlays/WorkspaceSwitcher.tsx: modal close behavior and route traversal interactions.
• apps/web/src/components/os/apps/MarketplaceApp.tsx: Marketplace/MCP copy.
• apps/web/src/components/os/apps/mcp/AddCustomMcpForm.tsx: custom MCP gating copy.
• apps/web/src/lib/command-catalog.ts: Command Center group labels.
• apps/web/src/components/os/overlays/LoginBriefing.tsx: login/team copy.
• apps/web/src/components/os/apps/skills/SkillRow.tsx: skill verification copy.
• apps/web/src/components/os/apps/PaymentSuccessApp.tsx: Teams success and legacy Pro copy boundary.
• tests/visual/views.spec.ts: visual regression route list/readiness and baseline triage.
• tests/e2e/phase-ab-verification.spec.ts: Ctrl+Shift+N and CSP console assertions.
• tests/e2e/power-user-stress.spec.ts: shortcut stress assertion.
• tests/e2e/full-wiring-audit.spec.ts: full traversal/console route behavior.
• tests/e2e/full-product-audit.spec.ts: load console health.
• tests/e2e/user-journeys.spec.ts: route smoke expansion for thin routes.
• docs/audits/2026-07-08-ux-route-scenario-manifest.md: update route evidence statuses after fixes.
• docs/audits/2026-07-08-five-persona-judge-scorecards.md: update readiness notes after fixes.

Phase Rules

• Keep work inside the files above unless a test exposes a direct local dependency.
• Re-read a file immediately before editing it.
• Write or adjust the failing test before the implementation for each task.
• Do not update visual baselines until the rendered screenshots are reviewed.
• Do not mark the five-persona gate ready until all P0 findings are closed.
• If a task reveals unrelated pre-existing dirty files, leave them untouched.

Task 1: Local Auth, Clerk, and CSP Console Health

Files:

• Modify: packages/server/src/local/security-middleware.ts

• Modify: packages/server/tests/local/security-middleware.test.ts

• Modify: apps/web/src/lib/clerk.ts

• Modify: apps/web/src/providers/WaggleClerkProvider.tsx

• Test: tests/e2e/full-product-audit.spec.ts

• Test: tests/e2e/phase-ab-verification.spec.ts

• Step 1: Add/adjust CSP test for strict local accountless mode

Add assertions in packages/server/tests/local/security-middleware.test.ts that document the accountless default:

expect(csp).toContain("script-src 'self'");
expect(csp).not.toMatch(/script-src[^;]*clerk/i);
expect(csp).not.toMatch(/connect-src[^;]*clerk/i);

Run:

npx vitest run packages/server/tests/local/security-middleware.test.ts

Expected before implementation review: current assertions pass for strict CSP, but rendered E2E still fails because client-side Clerk mounts when the local env contains a key.

• Step 2: Make accountless local mode the default client behavior

In apps/web/src/lib/clerk.ts, keep clerkPublishableKey() shape validation, but add a local opt-in guard so the desktop/local audit lane does not mount Clerk just because .env.local contains VITE_CLERK_PUBLISHABLE_KEY.

Use this behavior:

function clerkEnabledForThisBuild(): boolean {
  return import.meta.env.VITE_WAGGLE_ENABLE_CLERK === '1';
}

export function clerkPublishableKey(): string | undefined {
  if (!clerkEnabledForThisBuild()) return undefined;
  const k = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
  return k && isValidPublishableKey(k) ? k : undefined;
}

Keep the existing invalid-key fallback. Update the surrounding comment so it says Clerk is enabled only when the publishable key is valid and VITE_WAGGLE_ENABLE_CLERK=1.

• Step 3: Add a web unit test for accountless default

Create apps/web/src/test/clerk-accountless.test.ts if no equivalent exists. Test the exported function by stubbing import.meta.env in the same style used by nearby web tests. The test must assert:

expect(clerkPublishableKey()).toBeUndefined();

with a valid-looking key present and VITE_WAGGLE_ENABLE_CLERK absent.

Run:

cd apps/web
npx vitest run src/test/clerk-accountless.test.ts
cd ../..

Expected: pass after Step 2.

• Step 4: Verify rendered console health

Run a fresh-port focused lane:

$env:WAGGLE_E2E_PORT='3391'
$env:WAGGLE_E2E_BASE_URL='http://127.0.0.1:3391'
$env:WAGGLE_E2E_SKIP_LITELLM='1'
node node_modules/playwright/cli.js test tests/e2e/full-product-audit.spec.ts tests/e2e/phase-ab-verification.spec.ts --project=chromium --reporter=list

Expected after the task: no Clerk 429/load errors and no CSP failure caused by Clerk or the inline startup script.

• Step 5: Verify clean-data first-run console health

Run or codify a no-skip first-run smoke with a fresh data dir. It must navigate to / without skipOnboarding, wait for the onboarding takeover, and capture console/page errors from navigation start.

Minimum manual lane if no test exists yet:

$env:WAGGLE_PORT='3392'
$env:WAGGLE_TRUST_LOCALHOST='1'
$env:WAGGLE_DISABLE_MARKETPLACE_SYNC='1'
$env:EMBEDDING_PROVIDER='mock'
$env:VITE_CLERK_PUBLISHABLE_KEY=''
$env:CLERK_SECRET_KEY=''
$env:WAGGLE_DATA_DIR="$env:TEMP\waggle-first-run-auth-3392"
npm run build
npx tsx packages/server/src/local/start.ts --skip-litellm

Expected after the task: clean-data first-run onboarding has no Clerk/CSP/page errors, and the wizard still renders before shell chrome.

Completed 2026-07-08: clerkPublishableKey() now requires VITE_WAGGLE_ENABLE_CLERK=1 in addition to a valid key; the pre-hydration theme bootstrap moved from inline HTML to /theme-boot.js so local CSP keeps script-src 'self'; console-health E2E assertions now explicitly fail on Clerk/CSP noise. Verification: web auth Vitest 10/10, server security middleware Vitest 43/43, phase-ab initial-load console Playwright 1/1, full-product console Playwright 1/1, clean first-run onboarding Playwright 1/1, and git diff --check.

Task 2: Mobile Settings and First-Run Onboarding Responsive Layout

Files:

• Modify: apps/web/src/components/os/apps/SettingsApp.tsx

• Modify: apps/web/src/components/os/overlays/OnboardingWizard.tsx

• Modify: apps/web/src/components/os/overlays/onboarding/WhoAreYouStep.tsx

• Test: apps/web/src/test/pr5-settings-reskin.test.tsx

• Test: add or extend Playwright mobile coverage in tests/e2e/user-journeys.spec.ts

• Step 1: Add mobile Settings assertions that catch visible clipping

In tests/e2e/user-journeys.spec.ts, add a test that sets the viewport to 390 x 844, opens /settings, /settings?tab=models, /settings?tab=billing, and /settings/profile, and asserts both no document-level horizontal overflow and no visible critical-control overflow.

Do not rely on this check alone:

document.documentElement.scrollWidth > document.documentElement.clientWidth

The fresh mobile smoke in docs/audits/2026-07-08-mobile-executive-t2-t12-analysis.md found clipped/squeezed controls while document scroll width stayed clean.

Use a helper shaped like this:

test('J-mobile: Settings is usable at 390px width', async ({ page }) => {
  await page.setViewportSize({ width: 390, height: 844 });

  const routes = ['/settings', '/settings?tab=models', '/settings?tab=billing', '/settings/profile'];
  for (const route of routes) {
    await gotoApp(page, route);
    if (route !== '/settings/profile') {
      await expect(page.getByRole('tablist', { name: 'Settings sections' })).toBeVisible();
      await expect(page.getByRole('tabpanel').first()).toBeVisible();
    } else {
      await expect(page.locator('body')).toContainText(/profile|identity|save|writing style/i);
    }

    const documentOverflow = await page.evaluate(
      () => document.documentElement.scrollWidth > document.documentElement.clientWidth,
    );
    expect(documentOverflow, `${route} document overflow`).toBe(false);

    const visibleOverflow = await page.locator(
      'button:visible, [role="tab"]:visible, [role="tabpanel"]:visible, input:visible, select:visible, textarea:visible',
    ).evaluateAll(elements => elements
      .map(el => {
        const rect = el.getBoundingClientRect();
        return {
          text: (el.textContent || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.tagName).trim(),
          left: Math.floor(rect.left),
          right: Math.ceil(rect.right),
        };
      })
      .filter(item => item.left < -1 || item.right > window.innerWidth + 1));

    expect(visibleOverflow, `${route} visible control overflow`).toEqual([]);
  }
});

Run:

node node_modules/playwright/cli.js test tests/e2e/user-journeys.spec.ts --project=chromium --grep "Settings is usable at 390px"

Expected before implementation: fail on /settings, /settings?tab=models, or /settings?tab=billing because the current two-rail layout squeezes or clips visible controls even without document-level overflow.

• Step 2: Add first-run mobile onboarding assertions

Add a no-skip mobile first-run assertion using a clean data dir or an isolated server fixture. At 390 x 844:

• / renders the Onboarding Wizard, not shell chrome.
• Welcome has no horizontal overflow.
• After pressing Continue, the Profile step shows the progress/top bar, profile content, and primary Continue action without the action starting below the visible viewport, or the action is sticky/clearly reachable by design.
• Console capture is shared with Task 1, so Clerk/CSP errors remain visible until T1 is fixed.

Use docs/audits/2026-07-08-first-run-onboarding-t1-t2-t12-analysis.md as the red evidence source. The current trace puts the Profile Continue button bottom at 880 in an 844 px viewport.

• Step 3: Replace the fixed Settings rail on narrow screens

In SettingsApp.tsx, replace the root/tabs layout classes:

<div className="flex h-full">
  <div className="w-36 border-r border-border/50 shrink-0 flex flex-col">

with responsive classes:

<div className="flex h-full min-w-0 flex-col md:flex-row">
  <div className="shrink-0 border-b border-border/50 md:w-36 md:border-b-0 md:border-r flex flex-col">

Change the tablist container from vertical-only spacing to mobile horizontal scroll:

<div
  className="flex gap-1 overflow-x-auto p-2 md:block md:space-y-0.5"
  role="tablist"
  aria-label="Settings sections"
>

Change tab button classes from full-width only to responsive:

className={`flex min-w-max items-center gap-2 rounded-lg px-2 py-1.5 text-xs transition-colors md:w-full ${...}`}

• Step 4: Make Settings header controls wrap gracefully

Change the header row:

<div className="flex items-center justify-between gap-2 px-4 pt-3 pb-2.5 border-b border-border/40 shrink-0">

to:

<div className="flex flex-wrap items-center justify-between gap-2 px-3 pt-3 pb-2.5 border-b border-border/40 shrink-0 sm:px-4">

Change the content padding:

<div className="flex-1 p-4 overflow-auto" role="tabpanel">

to:

<div className="flex-1 overflow-auto p-3 sm:p-4" role="tabpanel">

• Step 5: Make onboarding Profile mobile-reachable

Prefer the smallest change that preserves the existing wizard:

• reduce mobile vertical density in WhoAreYouStep, or
• make the wizard action row sticky within the scroll container, or
• split optional details into a secondary mobile section while keeping the current desktop layout.

Do not remove the personalization signals; the fix is reachability and visual hierarchy.

• Step 6: Verify mobile and desktop

Run:

node node_modules/playwright/cli.js test tests/e2e/user-journeys.spec.ts --project=chromium --grep "Settings"
cd apps/web
npx vitest run src/test/pr5-settings-reskin.test.tsx
cd ../..

Expected: mobile tests pass for Settings general, Models, Billing, and Profile; screenshots show no clipped critical controls; existing desktop Settings tab behavior still passes.

Additional expected result: clean-data mobile first-run Welcome/Profile screenshots show no hidden primary action and the desktop first-run path still reaches workspace chat after template and first task.

Completed 2026-07-08: Settings now stacks/wraps its tab rail and header controls on narrow screens; the first-run wizard content starts at the top on mobile, and the Profile step uses tighter mobile density so the Continue action is initially reachable at 390 x 844. Verification: J-mobile Playwright tests failed red on Settings overflow and Profile Continue bottom 870 > 844, then passed 2/2 after the responsive changes; pr5-settings-reskin.test.tsx passed 3/3.

Task 3: Solo/Teams/Enterprise Pricing and Gating Copy

Files:

• Modify: apps/web/src/components/os/apps/MarketplaceApp.tsx

• Modify: apps/web/src/components/os/apps/mcp/AddCustomMcpForm.tsx

• Modify: apps/web/src/lib/command-catalog.ts

• Modify: apps/web/src/components/os/overlays/LoginBriefing.tsx

• Modify: apps/web/src/components/os/apps/skills/SkillRow.tsx

• Modify: apps/web/src/components/os/apps/SettingsApp.tsx

• Modify: apps/web/src/components/os/apps/PaymentSuccessApp.tsx

• Step 1: Add a copy guard command

Run before editing:

rg -n "Pro|PRO|pro_" apps/web/src/components/os/apps/MarketplaceApp.tsx apps/web/src/components/os/apps/mcp/AddCustomMcpForm.tsx apps/web/src/lib/command-catalog.ts apps/web/src/components/os/overlays/LoginBriefing.tsx apps/web/src/components/os/apps/skills/SkillRow.tsx apps/web/src/components/os/apps/SettingsApp.tsx apps/web/src/components/os/apps/PaymentSuccessApp.tsx

Expected current hits include active user-facing Pro copy in Marketplace, AddCustomMcpForm, Command Center, LoginBriefing, SkillRow, and Settings.

• Step 2: Replace active Pro copy

Use these replacements:

// MarketplaceApp.tsx
mcp: 'Enable MCP servers here (security-scanned). Manage running servers in the MCP Hub.',

// AddCustomMcpForm.tsx
Registers a local stdio server (command + args). Teams governance can manage shared use; Solo can run local servers on this device.

// command-catalog.ts
heading: "Pinned"

// SkillRow.tsx title
title="Run the skill against a synthesized test and grade it - mints the verified badge"

// SettingsApp.tsx local-first note
it is independent of your Solo/Team plan, and every app stays reachable via Ctrl+K.

In LoginBriefing.tsx, replace "Pro/Teams" and "Pro/Enterprise" phrasing with "Teams" or "Teams/Enterprise" depending on whether the copy refers to shared workspaces or sovereign deployment.

• Step 3: Preserve explicit legacy billing context only

In PaymentSuccessApp.tsx, keep legacy PRO mapping only if the rendered copy clearly says it is a legacy state. Do not present Pro as an active upgrade path.

• Step 4: Re-run copy guard

Run:

rg -n "Pro|PRO|pro_" apps/web/src

Expected: remaining hits are comments, type/legacy billing compatibility, or explicit "legacy Pro" servicing only. Active upgrade or gating copy must not say Pro.

Completed 2026-07-08: Active user-facing Pro copy was removed from Marketplace MCP copy, custom MCP copy, Command Center pinned heading, LoginBriefing workspace hints, SkillRow verification tooltip, and Settings local-first/billing comments. Legacy PRO billing remains only as explicit legacy state (Legacy Pro / Pro (legacy)). Verification: copy guard rerun leaves only false positives (Props, Providers), internal isPro, and explicit legacy PRO handling; command-catalog.test.ts passed 2/2 and pr7a-billing.test.tsx passed 10/10.

Task 4: Ctrl+Shift+N and Workspace Switcher Route Contract

Files:

• Modify: apps/web/src/components/os/AppShell.tsx

• Modify: apps/web/src/hooks/useKeyboardShortcuts.ts only if comments/tests require it.

• Modify: apps/web/src/components/os/overlays/WorkspaceSwitcher.tsx only if route-close behavior remains failing.

• Test: tests/e2e/phase-ab-verification.spec.ts

• Test: tests/e2e/power-user-stress.spec.ts

• Test: tests/e2e/full-wiring-audit.spec.ts

• Step 1: Preserve the existing failing tests as the red proof

Run:

node node_modules/playwright/cli.js test tests/e2e/phase-ab-verification.spec.ts tests/e2e/power-user-stress.spec.ts --project=chromium --grep "Ctrl\\+Shift\\+N"

Expected current result: failures where the URL does not become /workspaces/:id/chat.

• Step 2: Implement deterministic chat target resolution

In AppShell.tsx, replace navigateToActiveChat with a resolver that uses:

1. Explicit active workspace.
2. First non-archived workspace from the loaded list.
3. Workspace Switcher only when no workspace exists.

Use this implementation shape:

const firstAvailableWorkspaceId = useMemo(
  () => workspaces.find(ws => ws.status !== 'archived')?.id ?? null,
  [workspaces],
);

const chatShortcutWorkspaceId = effectiveActiveWorkspaceId ?? firstAvailableWorkspaceId;

const navigateToActiveChat = useCallback(() => {
  if (chatShortcutWorkspaceId) {
    selectWorkspace(chatShortcutWorkspaceId);
    ov.setShowWorkspaceSwitcher(false);
    navigate(routeFor('chat', { activeWorkspaceId: chatShortcutWorkspaceId }));
    return;
  }
  ov.toggleWorkspaceSwitcher();
}, [chatShortcutWorkspaceId, navigate, ov, selectWorkspace]);

setShowWorkspaceSwitcher exists in apps/web/src/hooks/useOverlayState.ts; do not add a second overlay state store.

• Step 3: Close Workspace Switcher during route-changing nav

In the sidebar/search handlers that navigate to a new route, close the switcher before or after navigate(route). The minimal target is the failing full-wiring-audit traversal path. Use the existing overlay setter if available; otherwise add a small closeBlockingOverlaysBeforeRouteChange() helper inside AppShell.tsx.

• Step 4: Verify shortcuts and full traversal

Run:

node node_modules/playwright/cli.js test tests/e2e/phase-ab-verification.spec.ts tests/e2e/power-user-stress.spec.ts tests/e2e/full-wiring-audit.spec.ts --project=chromium --grep "Ctrl\\+Shift\\+N|Full Console Error Audit"

Expected: both shortcut tests pass and the console traversal no longer fails because a Workspace Switcher backdrop intercepts navigation.

Completed 2026-07-08: Ctrl+Shift+N and the Chat sidebar item now resolve chat through the same deterministic target: explicit active workspace, first non-archived loaded workspace, then Workspace Switcher only when no workspace exists. A cold-load race was fixed with a pending shortcut state that waits for workspacesLoading to settle before deciding. Route-changing open-app, keyboard app, Command Center, and Workspace Switcher callbacks now close the switcher before navigation. Verification: the red shortcut lane failed 2/2 on port 34130, an intermediate green attempt exposed the cold-load race, then Ctrl+Shift+N passed 2/2 on port 34133; the scoped gate passed 4/4 on port 34135 for both shortcut specs plus Full Console Error Audit.

Task 5: Visual Snapshot Triage

Files:

• Inspect/possibly modify: tests/visual/views.spec.ts

• Inspect/update after review: tests/visual/baselines/**

• Do not modify UI just to satisfy stale snapshots.

• Step 1: Re-run visual suite and preserve artifacts

Run:

node node_modules/playwright/cli.js test tests/visual/views.spec.ts --project=chromium --reporter=list

Expected current result: 14 failures across 7 views in dark and light.

Analysis note: completed on fresh port 3463 with artifacts under output/playwright/visual-t5-3463/test-results/.

• Step 2: Review actual screenshots

Open the generated test-results/** images for each failed view. Classify each as:

intentional drift -> update baseline
real UI regression -> fix UI first
test readiness problem -> fix wait/stabilization in tests/visual/views.spec.ts

Record the classification in docs/audits/2026-07-08-complete-ux-usage-audit.md under P0-4 or in a short new visual decision note.

Analysis note: current classification is recorded in docs/audits/2026-07-08-visual-t5-classification.md. Most failures are stale-baseline drift, with Settings waiting for T2/T3 and Memory/Skills/Mission Control retaining targeted follow-up checks.

• Step 3: Apply approved baseline updates only after review

If the rendered screenshots are coherent and approved, run:

node node_modules/playwright/cli.js test tests/visual/views.spec.ts --project=chromium --update-snapshots

Expected: visual suite passes afterward.

Completed 2026-07-08: Re-ran the visual suite after Tasks 1-4 and reproduced the classified 14/14 stale-baseline failures on port 34136. Spot-checked the current Chat, Settings, Home, and Memory actual captures; the rendered surfaces were coherent and matched the approved Phase 1 direction. Updated the active Visual-Regression---... baseline family on port 34137, then reran without update mode on port 34138; tests/visual/views.spec.ts passed 14/14.

Task 6: Route Evidence for Thin Phase 1 Judge Paths

Files:

• Modify: tests/e2e/user-journeys.spec.ts

• Modify: docs/audits/2026-07-08-ux-route-scenario-manifest.md

• Modify: docs/audits/2026-07-08-route-evidence-t11-analysis.md

• Modify: docs/audits/2026-07-08-state-failure-t12-analysis.md

• Modify: docs/audits/2026-07-08-five-persona-judge-scorecards.md

• Step 1: Add smoke coverage for zero-hit and priority thin routes

Add a user journey test that verifies /benchmarks, /platform, and /payment-cancelled:

test('J-route-coverage: thin utility routes render or redirect clearly', async ({ page }) => {
  await gotoApp(page, '/benchmarks');
  await expect(page.locator('body')).toContainText(/benchmark|capability|score|memory/i);

  await gotoApp(page, '/platform');
  await expect(page.locator('body')).toContainText(/platform|local|governance|memory|agent/i);

  await gotoApp(page, '/payment-cancelled');
  await page.waitForURL(/\/settings\?tab=billing/, { timeout: 10_000 });
  await expect(page.locator('body')).toContainText(/billing|plan|team|solo|checkout/i);
});

Add a second user journey test that codifies the ad hoc thin-route smoke from the analysis packet:

test('J-route-coverage: priority thin routes render meaningful shells', async ({ page }) => {
  const routeChecks: Array<[string, RegExp]> = [
    ['/launcher', /tool launcher|optional prompt|detecting installed tools|launch/i],
    ['/launcher?watch=1', /tool launcher|optional prompt|detecting installed tools|launch/i],
    ['/waggle-dance', /waggle dance|signals|discovery|handoff/i],
    ['/artifacts', /artifact|library|document|presentation/i],
    ['/settings/profile', /who are you|identity|writing style|save/i],
    ['/settings/timeline', /timeline|workspace|activity/i],
    ['/payment-success', /checkout|paid|plans|nothing to confirm/i],
    ['/automations', /automation|schedule|trigger|history|logs/i],
    ['/mcps', /mcp hub|installed|catalog|custom/i],
    ['/settings/usage', /usage|cost|tokens|budget|upgrade/i],
    ['/files', /storage|files|workspace|local/i],
  ];

  for (const [route, bodyPattern] of routeChecks) {
    await gotoApp(page, route);
    await expect(page.locator('body')).toContainText(bodyPattern);
  }
});

Run:

node node_modules/playwright/cli.js test tests/e2e/user-journeys.spec.ts --project=chromium --grep "thin utility routes"
node node_modules/playwright/cli.js test tests/e2e/user-journeys.spec.ts --project=chromium --grep "priority thin routes"

Expected: pass after route behavior is confirmed or copy is clarified. Current analysis evidence already proves these URLs render/redirect in ad hoc smokes, but this step still codifies that evidence and keeps T1 console errors, Launcher detect-in-flight noise, and Usage/Cost 403 noise visible.

• Step 2: Update manifest statuses

In docs/audits/2026-07-08-ux-route-scenario-manifest.md, keep or update the rows for /benchmarks, /platform, /payment-cancelled, /launcher, /launcher?watch=1, /waggle-dance, /artifacts, /settings/profile, /settings/timeline, /payment-success, /automations, /mcps, /settings/usage, and /files with the codified route-smoke evidence owner. They already have ad hoc Mixed evidence from the analysis packet, but the implementation task must replace that with repeatable test evidence.

Also update docs/audits/2026-07-08-route-evidence-t11-analysis.md with the new passing command output and any remaining thin-route owners.

• Step 3: Update scorecard prerequisites

In docs/audits/2026-07-08-five-persona-judge-scorecards.md, add the new route smoke test to the judge evidence packet under Team Admin and Engineer if it is part of their journey.

In docs/audits/2026-07-08-state-failure-t12-analysis.md, add only a short evidence note if the new route smoke also proves a state-bundle field such as payment-cancelled recovery, route-level Launcher state, or disclosure-tier route access.

Completed 2026-07-08: Added two codified route-coverage tests to tests/e2e/user-journeys.spec.ts: one for /benchmarks, /platform, and /payment-cancelled redirect recovery; one for priority thin routes (/launcher, /launcher?watch=1, /waggle-dance, /artifacts, /settings/profile, /settings/timeline, /payment-success, /automations, /mcps, /settings/usage, /files). Verification: J-route-coverage passed 2/2 on port 34139. Updated the route manifest, T11 evidence supplement, T12 state supplement, and Engineer/Team Admin scorecards to cite the codified smoke while keeping deeper workflow-state evidence open.

Task 7: Phase 1 Verification Gate

Files:

• No source change unless a gate fails.

• Update: docs/audits/2026-07-08-complete-ux-usage-audit.md

• Update: docs/audits/2026-07-08-ux-route-scenario-manifest.md

• Update: docs/audits/2026-07-08-five-persona-judge-scorecards.md

• Step 1: Run static and unit verification

Run:

npm run typecheck:web
npm run ux:contrast
npm run ux:color-guard
cd apps/web
npx vitest run
cd ../..
npm run build

Expected: all pass. Warnings are allowed only if documented and unrelated to Phase 1.

• Step 2: Run focused browser lane

Run:

$env:WAGGLE_E2E_PORT='3391'
$env:WAGGLE_E2E_BASE_URL='http://127.0.0.1:3391'
$env:WAGGLE_E2E_SKIP_LITELLM='1'
node node_modules/playwright/cli.js test tests/e2e/full-product-audit.spec.ts tests/e2e/full-wiring-audit.spec.ts tests/e2e/phase-ab-verification.spec.ts tests/e2e/power-user-stress.spec.ts tests/e2e/user-journeys.spec.ts tests/visual/views.spec.ts --project=chromium --reporter=list

Expected: pass, or visual baseline updates are explicitly reviewed and approved.

• Step 3: Capture manual screenshots

Capture or inspect:

Desktop: first-run onboarding Welcome/Profile/Model/Template/First Task, /home, /settings, /marketplace, /mcps, /memory, /workspaces/:id/chat, /launcher
Mobile 390 x 844: first-run onboarding Welcome/Profile, /home, /settings, /settings?tab=models, /settings?tab=billing, /settings/profile, /memory, /workspaces/:id/chat
Overlays: Command Center, Workspace Switcher

Expected: no clipped critical controls, no incoherent overlap, no horizontal overflow in required mobile surfaces, and the selected Mobile Executive overlay opens and closes without trapping focus or scroll. If Command Center still remains visible after Escape or touch-close, record it as a T10/T12 blocker or explicitly use Workspace Switcher as the scoped mobile overlay proof.

• Step 4: Update analysis artifacts

Update the audit docs with current evidence:

P0-1 closed/open evidence
P0-2 closed/open evidence
P0-7 first-run mobile onboarding evidence
P0-3 closed/open evidence
P0-4 visual decision log
P0-5/P0-6 shortcut and overlay evidence
T11 route evidence status

Expected: Phase 1 is either ready for a judge dry run or has a short list of remaining blockers.

Completed 2026-07-08: Static/unit verification passed: npm run typecheck:web, npx tsc --noEmit --project packages/server/tsconfig.json, npm run ux:contrast, npm run ux:color-guard, full apps/web Vitest (174 files / 1578 tests), and npm run build. Focused browser verification passed 10/10 on port 34146. tests/e2e/user-journeys.spec.ts passed 16/16 on port 34149. The full combined browser gate passed 156/156 on port 34150 across full-product-audit, full-wiring-audit, phase-ab-verification, power-user-stress, user-journeys, and tests/visual/views.spec.ts. Visual artifacts were reviewed during Task 5 before baseline updates; the combined gate revalidated the approved baselines. The audit, route manifest, and judge scorecards now record the Phase 1 post-fix evidence and remaining non-Phase-1 blockers.

Self-Review Checklist

• Spec coverage: This plan covers Phase 1 items T1, T2, T3, T4, T5, and T11 from the audit, including first-run onboarding console and mobile reachability evidence. It intentionally defers T6-T10 and T12-T19 except where a Phase 1 test touches them.
• Placeholder scan: Each task includes concrete test commands or code shapes for the intended change.
• Type consistency: The plan uses existing route names, file paths, and current test names from the repo.
• Scope check: The plan does not create new product surfaces. It fixes existing surfaces and evidence gates.

Execution Choice

Plan complete and saved to docs/superpowers/plans/2026-07-08-ux-phase-1-corrections.md. Two execution options after user approval:

1. Subagent-Driven (recommended): dispatch a fresh subagent per task, review between tasks, fast iteration.
2. Inline Execution: execute tasks in this session using executing-plans, batch execution with checkpoints.