Portal Polish Sweep: Admin + Merchant QoL/UI-UX Day

Date: 2026-08-07 Status: Shipped to draft PR #803 (awaiting operator's manual review; stays draft until she flips it) Branch: worktree-portal-polish (worktree off origin/dev @ 643a5f0a) Theme: One-day quality-of-life and easy UI/UX polish pass over the admin portal (apps/admin/src/admin) and merchant portal (apps/admin/src/merchant), driven by live browser testing on deployed dev, verified with before/after screenshots.

Scope

In:

• Browser sweep of every admin-portal page/tab/state (as the Agent Probe admin) and every merchant-portal page/tab/state (as a freshly provisioned test merchant).
• Papercut fixes surfaced by the sweep: spacing, alignment, copy, loading/empty states, token drift, pattern violations per docs/engineering/guides/ADMIN_PAGE_PATTERNS.md.
• One small feature rider from the alpha gap map (Tier-3 #8): auto-refresh poll (15-30s) for analytics/VenueActivityDashboard.jsx, which is manual-Refresh only.

Out (owned elsewhere or deferred):

• User app (apps/web) screens: operator directive, leave the app alone today.
• Merchant provisioning / application-review code (admin/merchants create + review flow): #793's agent lane. Using that UI as a user to mint a test merchant is fine; editing it is not.
• Tooling scripts (tooling/): another agent's lane (uncommitted edits live in the main checkout).
• #624 Users-page consolidation: verified already shipped (feea9ace + follow-ups); closed 2026-08-07.
• #357 offers polish: web-app/backend tail, not portal UI.

Phases

1. Setup (done): worktree off origin/dev, .env.local symlink, deps installed, admin test baseline green (374/374).
2. Sweep: headless Playwright walks both portals on deployed dev; screenshot every page, tab, and empty/loading state. Judge against design tokens + ADMIN_PAGE_PATTERNS.
3. Punch list: ranked findings (quick-win first) posted to the operator for veto before fixing.
4. Fix loop: design skill first; one logical commit per theme; before/after screenshot per fix; push as we go. Dashboard poll rides as its own commit.
5. Ship: npm run validate, /code-review, one draft PR to dev referencing this plan and any papercut issues filed.

Verification limits

Screenshots verify layout, color, alignment, copy, and states. Touch ergonomics and animation feel are flagged for the operator's device pass, not claimed verified.

Live status

• 2026-08-07 morning: Phases 1-3 done. 61 screenshots across 19 admin routes + 8 merchant views; punch list approved by operator (green light on everything, PR stays draft for her manual review).
• Punch-list outcomes so far:
  • Fixed: venue category humanize, PageHeader title truncation, assistant-FAB clearance, users email dupe, 2h TTL taxonomy copy, em dashes in service descriptions + Photos copy, venue-activity 30s auto-poll, merchant hero-photo upload idiom, pin-location label, offer not-found state, GrowthChart duplicate ticks.
  • Done since: emoji → Lucide sweep landed (~300 occurrences, 30 files; CreateMerchantForm.jsx untouched, #793's lane), feature-tracker label-pill contrast guard (WCAG luminance), manual-ban default 7 days (+ test), Configuration pages reworked to the PageHeader idiom. Full npm run validate 31/31 green; after-fix browser pass on local admin (port 3001 + local auth-api) confirmed config idiom, 7-day ban default, humanized categories, email dedupe, Lucide drawers. Feature-tracker pill contrast is code-verified only (local docs-api not running; check on deployed dev).
  • Filed instead of fixed: #797 (uptime false DOWNs, CORS probes), #798 (login console noise).
  • For operator: delete the stray "test" registered event (classifier blocked the automated delete); BigQuery rollup was 3 days stale at sweep time; moderation Appeals badge shows 7 (looks like E2E leftovers).
• 2026-08-08: live marketplace round-trip (paired with the heavy-hitters session) found #817, alpha-blocking: merchants could not create ANY offer on deployed dev (publish and save-draft both 400). Fixed in 099d9a00. It first landed on the polish branch (branch creation was blocked by the session's permission guards at the time), then the operator approved a restructure: the fix moved to the chained branch fix/817-offer-publish as PR #820, returning PR #803 to exactly the polish scope she reviewed. What the pairing proved green: merchant provisioning with venue auto-associate (#793), one-time setup link, merchant set-password, real merchant login, and offer-form validation. What is NOT verified: the publish path live, since deployed dev still runs the buggy code and local verification is blocked by a missing iam.serviceAccounts.signBlob on this VM. Re-run the round-trip finale (offer publish -> pending_review -> admin approve -> user discover/claim) after #817 deploys; merchant m_KlAXPi6q4RvB stays provisioned on venue v9jQLgRn8sZ3jrTpncGw for that. Cosmetic finding filed as #818 (Review-step cards wrap one character per line).
• 2026-08-07 late afternoon: SHIPPED as draft PR #803 (14 commits). Adversarial review (2 agents) pre-draft caught 2 real bugs, both fixed + re-verified live: FAB-clearance padding clipped every full-height page (clearance moved to the internal scroller; measured 0 outer scroll on Users/Config, 96px on Venues) and the offer not-found guard was on a never-mounted path (moved to OffersDetail/OffersEdit). Also landed: poll error-banner clear + fetch-seq race guard, GrowthChart zero-tick placement, same-file re-pick reset, emoji-only pill fallback, icon-only search button a11y label, EventCreator registry-table Radio glyph. Validate 31/31, admin tests 375/375. PR stays DRAFT for the operator's manual review.