# Trackmint Operations Guide — Running, Testing, and Where Everything Lives

**Date: July 18, 2026** · One page to rule the project.

## 1. What exists, and where

| Thing | Where | What it's for |
|---|---|---|
| Clickable prototype (desktop) | Cowork sidebar artifact **"caseboard-prototype"** (also a downloadable HTML file) | Instant testing, showing the idea to others |
| Mobile/web app (real code) | Your Mac: `~/apex/projects/trackmint-app` | The actual product: Expo + React Native + TypeScript |
| Marketing website | Sidebar artifact **"caseboard-website"** + `~/apex/projects/trackmint-app/website/index.html` | Landing page, deploy anywhere static |
| TestFlight guide | `~/apex/projects/trackmint-app/TESTFLIGHT.md` | Step-by-step to your iPhone |
| Document library (17 PDFs) | This chat (docs 00–16) | Research, PRD v2, flows, workbook |
| Training workbook | Doc 16 PDF | 30 exercises to learn the tool |

## 2. Testing ladder — do these in order

### Level 1 — Prototype (0 setup, do it now)
Open the "caseboard-prototype" artifact. Use the **Pack** and **Tier** switches (top right). Follow workbook Parts A and B. Data resets on reload — that's fine for learning.

### Level 2 — App on your Mac + phone (2 minutes)
```bash
cd ~/apex/projects/trackmint-app
npm install          # first time only, ~2-3 min
npx expo start
```
- Press **i** → iOS Simulator (if Xcode installed), or
- Scan the QR with the **Expo Go** app on your iPhone (App Store, free).
- Tap **"Continue in demo mode"** — no accounts needed; data persists on the device.
- Repeat workbook exercises on the phone (especially timers, C3).

### Level 3 — Real accounts + cloud data (10 minutes, optional)
```bash
cp .env.example .env   # then paste values from Firebase Console →
                       # Project settings → General → Your apps → Web app
```
In Firebase Console: enable **Authentication → Email/Password** and **Firestore**. Paste the security rule from TESTFLIGHT.md. Restart `npx expo start`. Now sign-up/login is real and data syncs across devices.

### Level 4 — TestFlight on your iPhone (~1 hour, mostly waiting)
Prereqs you already have: Apple Developer account (Team 36M5AD7X5C), ASC API key at `~/apex/AuthKey_K3DJLR35C6.p8`, Expo account.
```bash
npm install -g eas-cli   # if needed
cd ~/apex/projects/trackmint-app
eas login
eas init                                            # accept defaults
eas build --platform ios --profile production       # ~15-25 min in Expo's cloud
eas submit --platform ios --latest                  # auto-creates the ASC app record
```
Then: App Store Connect → TestFlight → add yourself as internal tester → install from the TestFlight email on your phone.
- First `eas build` asks about credentials → choose **"Let EAS manage credentials."**
- If the name "Trackmint" is taken in App Store Connect, pick any placeholder — it's a working title.

### Level 5 — Web app + website (optional)
```bash
npx expo export --platform web --output-dir dist-web   # the app as a website
```
Host `dist-web/` and/or `website/index.html` on Firebase Hosting (`firebase init hosting`, `firebase deploy`) or Netlify/Vercel.

## 3. What to test (acceptance pass)

Use the workbook's completion checklist (doc 16, last page). Beyond it, the five things that MUST feel right, in priority order:
1. **Timer honesty** — start, switch screens, kill the app, reopen: is the time right?
2. **No double-billing** — invoice a client twice in a row; the second draft must be empty.
3. **Budget math** — log hours, check the bar percentage against a calculator once.
4. **Tier gates** — Basic must never show billing data anywhere.
5. **Pack integrity** — switching packs must never mix legal and dev data.
File anything broken as a note; those become the v1 bug list.

## 4. Troubleshooting

| Symptom | Fix |
|---|---|
| `npx expo start` errors | `rm -rf node_modules && npm install`; Node 20+ required |
| QR scan does nothing | Phone and Mac must be on the same Wi-Fi; or run `npx expo start --tunnel` |
| App stuck on splash | Check terminal for red errors; demo mode needs no network |
| `eas submit` fails on auth | Confirm `~/apex/AuthKey_K3DJLR35C6.p8` exists; `eas credentials` to inspect |
| Firebase login fails | .env values complete? Email/Password enabled in console? Restart expo after editing .env |
| Prototype artifact seems stale | It was updated July 18 (v2 features); reload the artifact |

## 5. Rhythm suggestion

Week 1: Levels 1–2 + workbook → note every annoyance (that's free product research on yourself).
Week 2: Level 4 (TestFlight) → daily-drive it for your real work in demo mode.
Then: decide from the executive summary's 5 next steps (customer interviews before more code).