LynkedUpPro_CRM/docs/superpowers/specs/2026-05-30-product-film-design.md

# LynkedUp Pro — Flagship Product Film (Design Spec)

> **Status:** Design agreed in brainstorming. Pending user review before writing the implementation plan.
> **Date:** 2026-05-30
> **Output:** A single comprehensive marketing/product film (~5 min) that conveys the whole product and sells every USP, for a B2B audience of roofing-company **owners** and their **operators**.

---

## 1. Goal

Produce one flagship film that makes a roofing-company owner *and* their team believe:

> "LynkedUp Pro takes us from the storm to the bank in one system — everyone runs it, and the owner controls all of it."

It must **showcase the real running app** (clicking, form-filling, role switching) as **proof**, organized as a **marketing narrative** (pain → promise → value pillars → payoff → CTA), not a screen-by-screen manual.

**Length:** ~5 minutes (free to run 4–8; comprehensiveness over brevity). 1080p, 16:9, 30fps.

## 2. Audience (B2B, dual)

- **Owner / operator-buyer** — the economic buyer. Cares about: surviving the storm surge, control/governance as they scale, and *real* profit per job.
- **Operators** (canvasser, sales rep, project manager/admin, subcontractor) — daily users. Care about: a focused experience that shows them only what they need.

The dual audience is a **feature, not a problem**: the headline USP is that the *same system gives every role a tailored, permission-bounded experience*. "Dual audience" and "access control" are therefore the **same beat** (Pillar ④).

## 3. Constraints

- **Do not modify any CRM code.** The film is captured from the running app and composited in an isolated sub-project. No edits under `src/`.
- Self-contained Remotion project at **`marketing/product-film/`** with its own `package.json` (no coupling to the CRM build).
- Brand consistency: reuse the landing page's visual language (logo, blue/cyan gradient, blueprint grid, the crane, the `craneSwing` curve, the en-US number formatting).
- Names/numbers on screen must be the canonical demo roster already seeded in the mock store (no fake "Sarah Connor"-style placeholders).

## 4. Narrative structure

**Cold Open → Promise → 5 Value Pillars → Crane CTA Close.** The landing page **bookends** the film (hero open, crane CTA close).

| Part | Sells | USP |
|------|-------|-----|
| Cold Open | The pain: storm hits, leads flood, reps freelance, jobs slip, "where's my margin?" | — |
| Promise | "One system. Storm to paid. Your team runs it — you control it." | End-to-end + control |
| ① Turn storms into pipeline | Weather → qualified pipeline, no junk leads | Storm intelligence |
| ② Right person on every job — automatically | Stop leads going cold; right skills, right roof | AI dispatch |
| ③ Every job runs on rails | No job slips; crews coordinated | End-to-end execution |
| ④ Scale with control | Everyone sees only their slice; you set the rules | Role-based access control |
| ⑤ Know your true profit | Real margin per job; stop flying blind | True profit visibility |
| Crane CTA Close | The transformation + CTA | — |

## 5. Beat sheet

On-screen text = the **caption**. The **VO line** is the written voiceover script (see §8 — captions + music ship first; real voiceover dropped in later against the same script). Durations approximate.

### Cold Open (~12s) — *Animated, landing-hero motif*
- **Visual:** Echo the landing hero — aerial-scan backdrop, "ROOFING **REVOLUTIONIZED**" wordmark, HUD annotations ("HAIL WATCH ACTIVE · ETA 35 MIN · WIND 24 MPH", "5,847 PROPERTIES TRACKED"). Snap into a 2s chaos montage: ringing phones, a cluttered spreadsheet, sticky notes, a missed-call list — abstracted, fast cuts.
- **Caption:** "A storm hits. The leads flood in. Then what?"
- **VO:** "When the storm clears, the race begins. Most roofing teams drown in it."

### Promise (~8s) — *Animated, logo reveal*
- **Visual:** Logo resolves on blueprint grid; tagline types in.
- **Caption:** "LynkedUp Pro — from the storm to the bank, in one system."
- **VO:** "LynkedUp Pro turns the chaos into closed, paid jobs — and puts the owner in control of all of it."

### ① Turn storms into pipeline (~45s) — *Recording + hybrid*
- **Screens:** Storm Intel (`StormIntelPage` — hail map, damage zones, `ZoneAssignmentModal`) → Territory Map (`Maps.jsx`) → Pro Canvas (`ProCanvas.jsx`) → Lead Verification (`LeadVerificationPage` — verify identity/insurance; verified → New Lead).
- **Action choreography:** Storm Intel opens, damage zones light up over Plano → cursor assigns a zone to a canvasser → cut to Lead Verification → cursor opens a pending lead, verifies it → it lands as a New Lead.
- **Caption beats:** "See the storm before your competition." → "Verify every lead. No junk gets through."
- **VO:** "Storm Intel maps the damage the moment it lands, so you canvass the right streets first. Every lead that comes back is verified before it ever reaches your pipeline."

### ② Right person on every job — automatically (~45s) — *Recording + hybrid*
- **Screens:** LynkDispatch (`LynkDispatchPage`, `DispatchRecommendationDrawer`, `DispatchMapPanel`) → Skill catalog/matching (`OrgSettings` SkillCatalogSection, `PeopleDirectory` skill scores) → Pipeline kanban (`KanbanPage`) → Lead detail (`LeadProjectPage`).
- **Action choreography:** Open LynkDispatch → AI recommendation drawer surfaces the best-fit rep (proximity + skill score) → cursor assigns → cut to kanban → cursor drags the lead from Contacted → Estimate.
- **Caption beats:** "AI picks the right rep — proximity + skill." → "Move every deal forward."
- **VO:** "LynkDispatch matches each new lead to the closest, best-skilled rep automatically. Deals move through the pipeline instead of going cold."

### ③ Every job runs on rails (~50s) — *Recording*
- **Screens:** Project lifecycle (`OwnerProjectDetail` — advance lifecycle stage) → Inspections + Estimates (`EstimatesPage`, `EstimateBuilder`, `EstimateDetailModal`) → Subcontractor task (`SubcontractorTasksPage`, `AssignTaskModal`) → **Subcontractor Portal** (`SubcontractorTaskDetailPage` — status → review) → Team Management (`TeamManagementPanel`).
- **Action choreography:** Advance a project stage on the state machine → log an inspection → send an estimate → assign a sub task → **switch into the sub portal** → sub updates status to in-progress, attaches a photo, marks for review.
- **Caption beats:** "Every job on a clear track." → "Crews get exactly what they need."
- **VO:** "From inspection to estimate to crew, every job runs on rails. Subcontractors get a focused portal — just their task, nothing else."

### ④ Scale with control (~45s) — *Recording, the access-control + dual-audience beat*
- **Screens:** Org roles (`OrgTeamManagement`) → ABAC permissions (`OrgSettings` access control, `AccessControlPersonModal` — module toggles per role + per-person override) → People directory / Profiles / User Details (`PeopleDirectory`, `UserDetailsPage`).
- **Live boundary moments:** Owner toggles **Financials = off** for the Sales Rep role → **switch to the rep's view** → Financials nav item is gone. Then the **sub portal** shows only their assigned job. Same app, rendered to each role's permission.
- **Caption beats:** "You decide who sees what." → "Everyone sees exactly their slice — no more, no less."
- **VO:** "As you grow, you stay in control. Set permissions by role or by person, and the app reshapes itself — the rep sees only their leads, the crew sees only their job, you see everything."

### ⑤ Know your true profit (~45s) — *Recording + hero, the payoff*
- **Screens:** Financial Overview (`FinancialKPICards`, `FinancialDetailsModal` — cost-to-cost POC, gross/net, drill-down) → Owner Snapshot (`OwnerSnapshot`) → Rep leaderboard (`LeaderboardPage`), commission (`CommissionDistributionPanel`) → **Storm attribution** (dashboard panel; `selectors.stormAttribution`) → Subcontractor performance.
- **Action choreography:** Open Financial Overview → real gross/net per job (grounded, positive) → drill into one job's revenue recognition → cut to leaderboard → storm attribution ties revenue back to the storm from Pillar ① (narrative bookend).
- **Caption beats:** "Real margin on every job." → "From that one storm: tracked, attributed, banked."
- **VO:** "Revenue is recognized job by job on a true cost-to-cost basis — so the profit you see is the profit you have. And every dollar traces back to the storm that started it."

### Crane CTA Close (~15s) — *Animated, faithful landing recreation*
- **Visual:** Recreate the landing crane in Remotion — blueprint tower crane (lattice mast, counter-jib + counterweights, main jib, trolley, dashed hoist cable, hook block). The **CTA card descends on the hoist cable into frame**, then settles into the signature pendulum sway.
  - **Swing:** reproduce `craneSwing` exactly — `rotate(+3deg)` ↔ `rotate(-3deg)`, 4s ease-in-out loop, `transform-origin: top center`. Entry: card starts higher with a slightly larger swing amplitude that damps to ±3°.
  - **Card content (verbatim from landing):** "✓ Project Ready" stamp · headline **"Ready to Build?"** · sub "Whether you protect one home or manage a thousand roofs, the future of roofing starts here." · buttons **"Schedule Demo →"** and **"Start Free Trial →"** · attachment-point dot connecting to the cable.
- **End plate:** logo · `LynkedUpPro.com` · `866-259-6533`.
- **Caption:** "Ready to build? Schedule a demo."
- **VO:** "From the storm to the bank, in one system. Ready to build? Let's get started."

**Runtime estimate:** ~12 + 8 + 45 + 45 + 50 + 45 + 45 + 15 ≈ **4:25** of content; transitions/title cards bring it to **~5:00**.

## 6. Feature → pillar coverage (proves "all functionality")

| Functionality | Pillar |
|---|---|
| Storm Intel / hail map / damage zones / zone assignment | ① |
| Territory Map | ① |
| Pro Canvas (canvassing, gamification) | ① |
| Lead Verification (identity/insurance → New Lead) | ① |
| LynkDispatch (AI rep recommendation, map, proximity+skill) | ② |
| Skill catalog + skill scoring | ② / ④ |
| Leads / Pipeline kanban + lead detail | ② |
| Project lifecycle state machine | ③ |
| Inspections | ③ |
| Estimates / estimate builder / templates | ③ |
| Subcontractor tasks (state machine) + Subcontractor Portal | ③ |
| Team Management | ③ / ④ |
| Org roles & team management | ④ |
| ABAC permissions (module toggles, per-person overrides) | ④ |
| People directory / Profiles / User Details | ④ |
| Financial Overview (cost-to-cost POC, gross/net, drill-down) | ⑤ |
| Owner dashboards / snapshot | ⑤ |
| Rep leaderboard / commission | ⑤ |
| Storm attribution | ⑤ |
| Subcontractor performance | ⑤ |
| Landing hero | Cold Open |
| Landing crane CTA (swing) | Close |

Nothing is dropped; everything is sold as *5 reasons to buy* across two audiences.

## 7. Technical architecture

### 7.1 Capture pipeline
- The CRM runs locally via `npm run dev` (Vite). A capture script drives a browser (Playwright, or the Chrome DevTools / Playwright MCP) to:
  1. Seed the mock store to the required state per beat (via the existing demo seed + in-app actions; no code changes — drive through the UI / `localStorage` the app already uses).
  2. Navigate to each screen, set theme (default **dark** for cinematic look), set a fixed viewport (1920×1080 device-scale 2 for crisp 1080p), and capture **high-res screenshots** of each state. For interaction beats, capture an ordered **sequence of states** (e.g., before/after a drag, before/after a verify) so Remotion can animate between them with a synthetic cursor.
  3. Optionally capture short **screen recordings** (`.webm`) for motion-heavy beats (kanban drag, map zoom) embedded via Remotion `OffthreadVideo`.
- Captures are written to `marketing/product-film/public/captures/<pillar>/<state>.png`.
- A `captures.manifest.json` lists every required capture (route, viewport, theme, pre-state) so the set is reproducible and gaps are visible.

### 7.2 Remotion project (`marketing/product-film/`)
```
marketing/product-film/
  package.json            # remotion, react, @remotion/cli, tailwind (or inline styles)
  remotion.config.ts
  src/
    Root.tsx              # registerRoot; <Composition id="LynkedUpProFilm" .../>
    Film.tsx              # <Series> of the 8 parts
    theme.ts              # brand tokens (blue/cyan gradient, blueprint grid, crane line vars)
    audio/                # music bed (licensed/royalty-free), optional VO track
    sequences/
      ColdOpen.tsx
      Promise.tsx
      Pillar1Storms.tsx
      Pillar2Dispatch.tsx
      Pillar3Rails.tsx
      Pillar4Control.tsx
      Pillar5Profit.tsx
      CraneClose.tsx
    components/
      ScreenFrame.tsx     # rounded browser-chrome frame around a capture
      Cursor.tsx          # synthetic cursor: spring-tween between targets + click pulse
      KenBurns.tsx        # slow pan/zoom on a still capture
      Caption.tsx         # animated lower-third / center caption
      PillarTitle.tsx     # animated section title card ("① Turn storms into pipeline")
      TypeReveal.tsx      # types text into a field (for form-fill beats)
      Transition.tsx      # wipe/blueprint-line transitions between parts
      Crane.tsx           # blueprint tower-crane SVG (ported from Landing.jsx)
      CraneCard.tsx       # the suspended CTA card with craneSwing reproduction
    captures.manifest.json
  public/captures/...
  out/                    # rendered mp4 (gitignored)
```
- **Root composition:** `LynkedUpProFilm`, 1920×1080, fps 30, `durationInFrames` = sum of part durations.
- **Cursor:** a single `Cursor` component animates between named targets per beat (spring easing) with a click-pulse keyframe; this is what makes still captures feel "live."
- **Form-fill beats:** `TypeReveal` overlays typed text onto a capture of the empty form, then crossfades to the captured filled/submitted state.
- **Crane:** `Crane.tsx` ports the exact SVG line art from `Landing.jsx`; `CraneCard.tsx` reproduces the `craneSwing` keyframe via `interpolate`/`spring` (±3°, 4s, top-center origin) with a damped entry.

### 7.3 Audio
- **Music:** one royalty-free cinematic-corporate bed, ducked under captions; energy build into Pillar ⑤ and the crane close.
- **Voiceover:** the VO lines in §5 are the **script**. Captions + music ship in v1; a real voiceover is recorded later and dropped onto the same timeline (sequence timings are authored to the script's pacing). No AI voiceover.

### 7.4 Render
- `npx remotion render LynkedUpProFilm out/lynkedup-pro-film.mp4` → H.264, 1080p, 30fps. A 720p/social cut can be derived later if needed.

## 8. Decisions (locked 2026-05-30)
1. **Audio:** ship **captions + music now**; real voiceover recorded later against the §5 VO script. Sequence timings are authored to the script's pacing so VO drops onto the same timeline. No AI voiceover.
2. **Theme:** capture the app in **dark mode** (cinematic).
3. **Runtime:** target **~5 min** as scoped in §5. No pillar expansion.

## 9. Out of scope (this spec)
- Plan 8 ABAC backend, homeowner portal, and any CRM code changes. The film only *depicts* the existing UI.
- Multi-language captions, social cut-downs, A/B variants — derivable later from the master timeline.