# AxleWise.ai — Master Plan

> Companion to `KNOWLEDGE.md`. That doc answers *"what exists?"*; this one answers *"what's next, in what order, and why?"*. Read this when picking the project back up to know exactly which lever to pull.

**North-star metric:** *paid Pro subscribers among active car-hauler drivers.*
**One-line strategy:** *Win the optimizer, earn the trust, sell the safety + route co-pilot as Pro.*

---

## 0. Status snapshot (2026-06-01)

| Surface | State | Next lever |
|---|---|---|
| Expo app | Feature-complete MVP, type-safe, dark + amber. Optimizer UX polished: compact chip rows, "All" filter, shortcut jump-to-calculate button, empty-slot car picker on results. 21 vehicle images (brand/style/category level) replace broken placeholders. | P0 pre-launch polish (onboarding, empty/error states, optimizer split) |
| Landing site | Live on Cloudflare Pages at `axlewise.ai`. Stage B real video shipped (hero_video_v2.mp4 w/ VO + music). SEO meta, JSON-LD, Search Console verified. Features grid, testimonials, comparison table, waitlist form. | Monitor indexing, A/B test waitlist copy |
| Search Console | ✅ Verified on `axlewise.ai` apex domain; sitemap submitted + indexed | Monitor indexing status |
| App Store | Not submitted | Run preflight, fill metadata, ship to TestFlight |
| Play Store | Not submitted | Build AAB, internal track |
| Monetization | RevenueCat wired, paywall screen built, Pro = Fuel Adjustment | Connect real offerings, A/B price points |
| Investor pack | 10 modal screens built (pitch / financials / GTM / launch / ads) | Use as warm-intro asset, not cold outreach |

---

## 1. Active workstreams

### 1A · Hero "video" rollout — two-stage plan

#### Stage A — Ship today: cinematic faux-video reel ✅

A pure CSS/SVG "product film" replaces the OPTIMIZE button. Zero load time, no AI generation cost, looks legit immediately. Lives inside a 16:10 player with chrome (REC pill, mute button, scrubber, time, captions).

- [x] 5-scene reel matching the planned shot list:
  - [x] **Scene 1 (0–3.2s):** Tight on a glowing 78,400 lb dial sweeping red → amber → green
  - [x] **Scene 2 (3.2–6.4s):** Pull back to a phone in a golden-hour cab
  - [x] **Scene 3 (6.4–9.6s):** OPTIMIZE tap, axle bars solve in real time, all green
  - [x] **Scene 4 (9.6–12.8s):** Loaded 9-car carrier rolls out at sunrise with stat pills (9 cars · 0 fines · 12s)
  - [x] **Scene 5 (12.8–16s):** Logo lockup with "Balance axles. Dodge fines. Haul more cars."
- [x] Caption track sync'd to scenes (acts as voiceover stand-in)
- [x] Live REC pill, mute button, animated scrubber, ticking 0:00 / 0:16 timer
- [x] Loops seamlessly, respects `prefers-reduced-motion`
- [x] Fully responsive (desktop side-by-side, mobile stacks)

#### Stage B — Later: real AI-generated hero video ✅

Drop-in replacement for the reel using stitched AI clips + voiceover + music. Same player chrome stays.

- [x] Approve voiceover script (current draft in chat history, ~55s / 135 words)
- [x] Pick voice tone: calm pro / energetic trucker / cinematic narrator
- [x] Generate 5 clips (~5–10s each) matching the existing scene structure
- [x] Mix VO + cinematic music bed
- [x] Swap the `.reel` block for `<video>` with poster frame, autoplay-muted, scroll-pause, fallback to faux-reel
- [x] No new app icon needed

### 1B · Google Search Console + SEO

- [x] Verified `pages.dev` via HTML file (`landing/google0c5fe369f3192bdb.html`)
- [x] Inline SVG favicon + Apple touch icon
- [x] JSON-LD: Organization, WebSite, MobileApplication
- [x] `robots.txt` + `sitemap.xml` in `landing/`
- [x] Sitemap URLs point at the verified `pages.dev` host (will swap to apex on domain cutover)
- [x] Submit `sitemap.xml` inside Search Console (`Sitemaps` → enter `sitemap.xml` → Submit)
- [ ] Request indexing on `/` and `/privacy.html` via URL Inspection
- [ ] Point real domain (`axlewise.ai`) at Cloudflare Pages
- [ ] Re-verify Search Console on apex + `www`
- [x] Add `<link rel="canonical">` once domain decision is final

### 1C · Custom domain cutover

- [ ] Pick: apex `axlewise.ai` or `www.axlewise.ai` canonical (lean apex, 301 www→apex)
- [ ] Add domain in Cloudflare Pages → Custom domains
- [ ] DNS: CNAME flattened at apex, CNAME `www`
- [ ] Update `landing/sitemap.xml` URLs
- [ ] Update OG/Twitter `url` + `og:url` in `index.html`
- [ ] Update JSON-LD `url` fields
- [ ] Update `app.json` `associatedDomains` if/when universal links are added

---

## 2. Roadmap (next 90 days)

### Phase 1 — Polish & Ship (weeks 1–3)

Goal: get a downloadable build in front of 20 real drivers.

- [ ] **Optimizer split-up:** `(tabs)/optimizer/index.tsx` is 1,275+ LOC. Extract `<TractorPicker/>`, `<CarrierPicker/>`, `<CarSelector/>`, `<LoadWarningsBanner/>` into `components/optimizer/`.
- [ ] **Empty/error states pass:** every screen needs (a) skeleton, (b) zero-data illustration, (c) error retry.
- [ ] **Paywall A/B copy:** test "Unlock Fuel Adjustment" vs. "Squeeze in one more car" headline.
- [ ] **Onboarding flow:** 3-screen first-run (welcome → pick your rig → run a sample load) before dropping into Home.
- [ ] **App icon + splash final pass** (see `app-config` skill).
- [ ] **TestFlight build #1.**
- [ ] **Play Store internal track build #1.**

### Phase 2 — Distribution (weeks 4–7)

Goal: 500 installs, 25 paying Pro, first review on each store.

- [ ] Landing waitlist → install email (Cloudflare Worker `waitlist-worker.js` already in place — wire to Resend/Mailgun).
- [ ] Stage B video shipped on hero.
- [ ] Custom domain live, indexed.
- [ ] Launch posts: r/Truckers, r/CarHauling, Facebook driver groups, TikTok demo clips from Stage B footage.
- [ ] Ad scripts (`app/ad-scripts.tsx`) → 3 TikTok/Reels variants; spend cap $20/day.
- [ ] In-app review prompt after 3rd successful optimize.

### Phase 3 — Defend the moat (weeks 8–12)

Goal: own the data + the network.

- [ ] **Spec requests pipeline:** the `request-specs` modal already saves to `axlewise_spec_requests`. Sync to Supabase (or revive `backend/`) so I can review + add to mocks centrally.
- [ ] **Crowd-sourced bridges:** add "Report a low bridge" to Routes; pin Cloudflare D1 table behind a Worker.
- [ ] **Dispatcher comms (Messages tab):** currently mock-only. Decide: build real, or cut to hidden-forever.
- [ ] **Fleet plan tier:** Pro = solo driver; Fleet = $X/truck/mo with admin dashboard.

---

## 3. Feature backlog (tagged, not ordered)

`P0` = must-ship before TestFlight · `P1` = before public launch · `P2` = post-launch · `nice` = if bored

- [ ] `P0` — Persist last-used tractor + carrier so Optimizer wizard auto-fills.
- [ ] `P0` — "Share load" → generate a PDF / image of the result screen for dispatcher.
- [ ] `P0` — Validate Fuel Adjustment paywall gate actually blocks free users (audit `useRevenueCat.isPro` reads).
- [ ] `P1` — Damage diagram: tap-to-mark on car silhouette → save to incident.
- [ ] `P1` — Pre-trip inspection PDF export (DOT-acceptable layout).
- [ ] `P1` — Route detail: turn-by-turn cards w/ height-flag pins along the polyline.
- [ ] `P1` — "Why did this car get rejected?" explainer modal on Optimizer results.
- [ ] `P2` — Multi-truck fleet view in Profile.
- [ ] `P2` — Bridge DB outside US (start CA provinces).
- [ ] `P2` — Apple Watch glance: current GVW + status light.
- [ ] `nice` — Live odometer on Home using `expo-location` (drive-time stat).
- [ ] `nice` — Haptic *pattern* on red-axle warning vs. simple impact.

---

## 4. Tech debt & risks

| Item | Severity | Plan |
|---|---|---|
| `(tabs)/optimizer/index.tsx` size | 🟡 | Split in Phase 1 |
| Mocks files 1.7k–2k LOC | 🟡 | Split by make when next 100+ rows added |
| Backend scaffolded but unused | 🟡 | Decide Supabase vs. revive Hono before crowd-sourced features |
| Mixed absolute/relative router paths | 🟢 | Lint pass — pick one style |
| RevenueCat sandbox tested but not production-validated | 🟠 | Block TestFlight until verified |
| No analytics yet | 🟠 | Add PostHog or Amplitude before Phase 2 |
| No crash reporting | 🟠 | Add Sentry before TestFlight |

---

## 5. Decision log

- **Dark-only theme** — committed, no light mode planned. Drivers run apps at 3am in cabs; light mode is a tax.
- **Curb weight = full tank** — Optimizer assumes worst-case. Fuel Adjustment is a Pro upside, never a safety override.
- **Mocks > backend, for now** — every screen client-only. Backend turns on when crowd-sourced data starts flowing.
- **One brand voice:** *"Balance axles. Dodge fines. Haul more cars."* — keep across OG, ads, App Store subtitle.
- **Hero CTA:** the faux-video reel *replaces* the old OPTIMIZE button. Don't add it back; the video *is* the demo.

---

## 6. Phase gates (definition of done)

**Ready for TestFlight when:**
- [ ] Onboarding lands
- [ ] Optimizer split, every screen has empty/error
- [ ] RevenueCat verified end-to-end
- [ ] Sentry installed
- [ ] App icon + splash final
- [ ] No `console.warn` on cold start

**Ready for public launch when:**
- [ ] Stage B video live
- [ ] Custom domain indexed
- [ ] Analytics dashboard shows funnel: install → first optimize → paywall view → purchase
- [ ] 20 beta drivers gave thumbs-up
- [ ] Privacy + Terms reviewed by counsel

---

## 7. Visual roadmap

```
TODAY ───── Phase 1 ───── Phase 2 ───── Phase 3
  │           │             │             │
  ▼           ▼             ▼             ▼
Stage A   Onboarding    Custom domain  Crowd bridges
video     Optimizer     Stage B video  Fleet tier
SEO meta  split         Waitlist mail  Supabase sync
JSON-LD   TestFlight    Ads $20/day    Real Messages
          Sentry        25 paying Pro  500 paying
          RC verified   Reviews        Reviews + PR
```

```
                        ┌─────────────────┐
                        │   NORTH STAR    │
                        │ Paid Pro drivers│
                        └────────┬────────┘
                  ┌──────────────┼──────────────┐
                  ▼              ▼              ▼
              ACQUIRE         ACTIVATE        RETAIN
              ───────         ────────        ──────
            Landing+SEO    Onboarding 3-step  Saved setups
            Waitlist mail  Sample load run    Load history
            TikTok ads     First win < 60s    Safety streak
            Reddit/FB      Paywall after win  Push: alerts
            Reviews        Pro = +1 car       Fleet upgrade
```

---

## 8. Quick links (where to start each session)

1. `KNOWLEDGE.md` — facts about the project
2. `PLAN.md` — this file, the order of operations
3. `expo/app/(tabs)/optimizer/index.tsx` — the product spine
4. `expo/utils/loadCalculator.ts` — the math spine
5. `landing/index.html` — the conversion surface
6. `expo/hooks/useRevenueCat.ts` — the monetization spine

---

*Last refreshed: 2026-05-19. Update checkboxes as items ship; promote `P1`s to active workstreams when Phase 1 closes.*
*
Recent completions (late May – June 1):*
- ✅ Vehicle image overhaul: 21 AI-generated brand/style/category photos (9 tractor brands, 5 carrier styles, 7 car categories)
- ✅ Optimizer chips: compact horizontal chip rows w/ "All" filter (replaced large 48% cards)
- ✅ Shortcut button: Scale icon jumps to "Calculate Optimal Load" from anywhere
- ✅ Empty-slot car picker: tap empty position on results grid to add cars
- ✅ `AXLEWISE_REFERENCE.md` created: complete single-file project reference (652 LOC)
- ✅ `expo-font` cache corruption: diagnosed fix (clear bun cache + reinstall)