docs: define v1 requirements

.planning/REQUIREMENTS.md

@@ -0,0 +1,148 @@
+# Requirements: Pulse Mobile Shell Redesign
+
+**Defined:** 2026-05-03
+**Core Value:** A manager can open Pulse on their phone and, in under 30 seconds, see the state of the business and triage tickets — without ever needing to switch to desktop for read-only awareness.
+**Source spec:** `docs/superpowers/specs/2026-05-03-mobile-shell-design.md`
+
+## v1 Requirements
+
+Requirements for this milestone. Each maps to a spec section and a roadmap phase.
+
+### PWA — Progressive Web App scaffolding (spec §4)
+
+- [ ] **PWA-01**: `public/manifest.json` exists with name "Pulse", short_name "Pulse", `display: "standalone"`, `start_url: "/mobile"`, theme/background colors matching dark and light shells
+- [ ] **PWA-02**: Manifest is referenced from `app/layout.tsx` via `<link rel="manifest">`
+- [ ] **PWA-03**: Viewport meta in `app/layout.tsx` includes `viewport-fit=cover`
+- [ ] **PWA-04**: Header and bottom tab bar respect `env(safe-area-inset-top)` and `env(safe-area-inset-bottom)` (Tailwind arbitrary values or shared utility class)
+
+### Shell — `/mobile` layout (spec §5)
+
+- [ ] **SHELL-01**: New `app/mobile/layout.tsx` replaces the current layout (rebuild in place — no parallel `/mobile-v2`)
+- [ ] **SHELL-02**: Sticky top header: `bg-background/95 backdrop-blur` + bottom border; left = Wulf mark + "Pulse" wordmark linked to `/mobile/dashboard`; no page title in header
+- [ ] **SHELL-03**: Header right slot — `Bell` icon button (placeholder, no menu/badge, `aria-label="Notifications"`, empty `onClick`, keyboard-accessible)
+- [ ] **SHELL-04**: Header right slot — compact user avatar (`h-7 w-7`); tapping opens the More drawer
+- [ ] **SHELL-05**: `<main>` content area is scrollable with bottom padding equal to bottom-nav height + safe-area inset
+- [ ] **SHELL-06**: Fixed bottom nav: `border-t bg-background`, `max-w-lg mx-auto` wrapper, 5 cells (4 tabs + More)
+
+### NAV — Bottom tab bar (spec §3.1)
+
+- [ ] **NAV-01**: Four equal-width primary tabs: Dashboard (`LayoutDashboard`), Tickets (`Ticket`), Finance (`DollarSign`), Analyzer (`Sparkles`)
+- [ ] **NAV-02**: Tabs route to `/mobile/dashboard`, `/mobile/tickets`, `/mobile/finance`, `/mobile/analyzer`
+- [ ] **NAV-03**: Active state uses `text-primary`, inactive uses `text-muted-foreground`; active detection via `pathname.startsWith(href)`
+
+### DRAWER — More Sheet drawer (spec §3.2)
+
+- [ ] **DRAWER-01**: Fifth bottom-bar control labeled "More" with `Menu` icon opens a shadcn `Sheet`
+- [ ] **DRAWER-02**: Sheet uses a single consistent side (`right` or `bottom`) — pick one and stay consistent
+- [ ] **DRAWER-03**: Drawer top section "Mobile sections" lists Engagement (`/mobile/engagement`)
+- [ ] **DRAWER-04**: Drawer middle section "Full site" lists desktop-only pages (Quotes, Configuration Items, Backup Status, Ticket Digest, Admin / Sync) each with `ExternalLink` icon
+- [ ] **DRAWER-05**: Drawer bottom section "Account" shows current user (avatar + email, read-only) and a Sign out action that calls `signOut()` then `router.push('/auth/sign-in')`
+- [ ] **DRAWER-06**: `app/mobile/nav/page.tsx` is deleted in the same change that ships the drawer
+
+### DASH — Mobile Dashboard (spec §6.1)
+
+- [ ] **DASH-01**: 2×2 KPI grid with four primary metric cards drawn from desktop dashboard hero stats
+- [ ] **DASH-02**: "Needs Attention" horizontal-scroll strip of compact cards (overdue tickets, failed backups, stalled workflows); tapping a card opens its detail view
+- [ ] **DASH-03**: Compact backup/worker status row showing analyzer worker, RMM worker, and backup-success-rate; read-only; tap opens desktop admin page
+- [ ] **DASH-04**: No charts/recharts on the mobile Dashboard
+
+### TICK — Mobile Tickets list (spec §6.2)
+
+- [ ] **TICK-01**: Collapsible filter strip at top (`Collapsible` from shadcn), default collapsed; expanded shows status, priority, queue, assigned-to-me toggle
+- [ ] **TICK-02**: Filter state syncs to URL query string for deep-linking
+- [ ] **TICK-03**: List rows have left-edge color stripe by priority (Critical/High/Medium/Low → red/orange/amber/slate); body shows ticket #, title, company, age, assignee
+- [ ] **TICK-04**: Single-tap on a row opens detail page
+- [ ] **TICK-05**: Cursor-based infinite scroll (~25 per page) replaces pagination; next page triggers when last row enters viewport via IntersectionObserver
+- [ ] **TICK-06**: "Load more" fallback button present for accessibility
+- [ ] **TICK-07**: Detail page (`/mobile/tickets/[id]`) header reskinned to match new shell (Wulf mark, breadcrumb back); body kept largely as-is
+
+### FIN — Mobile Finance (spec §6.3)
+
+- [ ] **FIN-01**: Page restyled with new Card and typography scale; spacing fixed for small phones
+- [ ] **FIN-02**: Wide tables on mobile widths replaced with stacked lists; no new data, no new sections
+
+### ANL — Mobile Analyzer feed (spec §6.4) — NEW PAGE
+
+- [ ] **ANL-01**: `/mobile/analyzer` route exists (read-only feed, most-recent-first stream of AI ticket analyses)
+- [ ] **ANL-02**: Each list row shows ticket #, title, analyzer one-line summary, confidence badge, stage indicator (Triage → Analyze → Deep Review)
+- [ ] **ANL-03**: Tapping a row opens a mobile summary view rendering Summary, Next Step, Next Step Rationale (all already produced by the analyzer pipeline)
+- [ ] **ANL-04**: Summary view includes "View full analysis" link out to the desktop analyzer page
+- [ ] **ANL-05**: No editing, no re-run, no prompt tuning on mobile
+- [ ] **ANL-06**: Source data via `/api/mobile/analyzer/feed` (or reuse an existing list endpoint if it returns the right shape) reading from `analyzer_analyses`
+
+### ENG — Mobile Engagement (spec §6.5) — NEW PAGES
+
+- [ ] **ENG-01**: `/mobile/engagement` overview page (real refactor, not a thin adaptation of the ~1300-line desktop page)
+- [ ] **ENG-02**: Period selector chip row (today / 7d / 30d) sticky just below the page H1
+- [ ] **ENG-03**: Summary cards stacked single-column (active users, total Graph hours, total Autotask hours, hours-per-active-user) — no 4-up grid on phone widths
+- [ ] **ENG-04**: Per-employee list as stacked rows (avatar/initials, name, role, hours bar) with sort control above (sort by hours, name, utilization) and search input
+- [ ] **ENG-05**: Top of list shows compact "hours trend" sparkline scoped to the selected period; no multi-series chart on mobile
+- [ ] **ENG-06**: User profile is `/mobile/engagement/[userId]` (segment form preferred for shareable URLs); single-column layout: identity header → period selector → key metrics (compact) → activity breakdown list → recent items
+- [ ] **ENG-07**: User profile is a real page, not a modal — replaces desktop user-detail modal pattern on mobile so back gesture works
+- [ ] **ENG-08**: Profile reuses existing engagement profile data endpoints; no new data
+- [ ] **ENG-09**: Engagement is reachable from the More drawer, NOT the bottom bar
+
+## v2 Requirements
+
+Acknowledged but deferred. Not in this milestone's roadmap.
+
+### NOTIF — Notifications
+
+- **NOTIF-01**: Real notification list behind the Bell icon (replaces SHELL-03 placeholder)
+- **NOTIF-02**: Notification badge logic on the Bell icon
+
+### TABLET — Tablet breakpoint
+
+- **TABLET-01**: `md:max-w-2xl mx-auto` wrapper for tablet widths
+
+### OFFLINE — Offline support
+
+- **OFFLINE-01**: Service worker for offline cache
+- **OFFLINE-02**: Push notifications (requires SW)
+
+### EDIT — Mobile editing
+
+- **EDIT-01**: Mobile editing on Engagement user detail
+- **EDIT-02**: Mobile re-run / prompt edits on Analyzer
+
+## Out of Scope
+
+Explicitly excluded for v1. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Service worker / offline cache / push notifications | No clear offline use-case yet — defer until one lands (spec §4, §7) |
+| Tablet breakpoint (`md:max-w-2xl`) | Noted as follow-up; keep `max-w-lg` for v1 (spec §4, §7) |
+| Real notification list behind the Bell | Placeholder only this iteration; future phase wires it (spec §5.1, §7) |
+| Mobile editing on Engagement user detail | Read-only on mobile by design (spec §6.5, §7) |
+| Mobile re-run / prompt tuning on Analyzer | Read-only on mobile by design (spec §6.4, §7) |
+| Charts / recharts on mobile Dashboard | Not earning their weight on small widths (spec §6.1, §7) |
+| Restyling/replacing desktop pages reachable from More drawer | Desktop pages stay as-is (spec §7) |
+| Multi-series chart on mobile Engagement overview | Replaced by single sparkline (spec §6.5) |
+| Modal-based user detail on mobile | Replaced by real page so back gesture works (spec §6.5) |
+| `/mobile-v2` parallel directory | Rebuild `/mobile` in place — keep canonical URLs (spec §2) |
+
+## Traceability
+
+Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PWA-01 to PWA-04 | TBD | Pending |
+| SHELL-01 to SHELL-06 | TBD | Pending |
+| NAV-01 to NAV-03 | TBD | Pending |
+| DRAWER-01 to DRAWER-06 | TBD | Pending |
+| DASH-01 to DASH-04 | TBD | Pending |
+| TICK-01 to TICK-07 | TBD | Pending |
+| FIN-01 to FIN-02 | TBD | Pending |
+| ANL-01 to ANL-06 | TBD | Pending |
+| ENG-01 to ENG-09 | TBD | Pending |
+
+**Coverage:**
+- v1 requirements: 47 total
+- Mapped to phases: 0 (pending roadmap)
+- Unmapped: 47 ⚠️ (resolved by roadmapper)
+
+---
+*Requirements defined: 2026-05-03*
+*Last updated: 2026-05-03 after initial definition*