# Cold-run checklist

End-to-end smoke test of the install + first-launch flow on a clean Mac. Run this **before** sending an invite to the first alpha PM.

The goal: catch any failure that would make a non-technical user bounce — broken script, missing prereq, opaque error, wizard that doesn't fire, dashboard that crashes on empty data.

---

## Setup the test environment

Pick one of these — in increasing order of fidelity:

### Option A — Borrow a second Mac (highest fidelity)

If you have access to a friend's or family member's Mac that hasn't used knitor or Claude Code, this is the most honest test. They don't even need to be present — just borrow it for 20 minutes.

### Option B — New macOS user account on your Mac

Create a new user via System Settings → Users & Groups → Add User. Log in as that user. The new user has its own `~/`, `~/.claude/`, Documents, etc. Nothing carries over.

```
System Settings → Users & Groups → Add User
  Account type: Standard
  Full name: knitor-test
  (skip Apple ID)
```

Run the checklist as that user. Delete the account when done.

### Option C — Move your own dotfiles aside (lowest fidelity, riskiest)

Only if A and B are too much trouble. Run these in a fresh terminal:

```bash
# 1. STOP any running knitor instance first (Ctrl+C in the dev terminal)

# 2. Move dotfiles aside — DO NOT remove
mv ~/.claude ~/.claude.coldrun-bak
mv ~/.bun ~/.bun.coldrun-bak

# 3. Open a NEW terminal (so $PATH no longer has ~/.bun/bin)
#    Verify you're in a clean state:
which bun     # should say "bun not found"
ls ~/.claude  # should say "No such file or directory"

# 4. Run the install + verify steps below.

# 5. AFTER the test, restore:
mv ~/.bun.coldrun-bak ~/.bun
rm -rf ~/.claude   # the test-created .claude
mv ~/.claude.coldrun-bak ~/.claude
```

⚠️ Option C carries real risk. If the restore step fails, you lose Claude Code state. Prefer A or B.

---

## Run

### Step 1: Get the code

```bash
git clone https://github.com/pavelracu/head-of-product-ui-v2.git knitor
cd knitor
```

**Check:** Did `git clone` succeed? If git wasn't installed, did the Xcode CLT prompt appear and get accepted?

### Step 2: Run the installer

```bash
bash scripts/install.sh
```

**Check each:**
- [ ] Installer detects Bun missing and offers to install it
- [ ] Bun installation completes (the curl-bash script)
- [ ] `bun install` runs without errors
- [ ] `bun run build` produces `dist/` and finishes cleanly
- [ ] Final output says "Install complete" and prints `bun start` as next step
- [ ] No errors, no warnings about unfound files / missing tools

**Common breaks to watch for:**
- "command not found: bun" after Bun installs → installer added Bun to PATH for the script's session but the new shell doesn't see it. Document this in INSTALL.md (it already is — verify the language matches the actual error).
- TypeScript / vite errors during build → ship-blocker, not an install issue. Should have been caught by earlier `bun run check`.
- Storybook files in the build → ts excludes them. Verify.

### Step 3: Start the app

In the SAME terminal (so PATH is fresh):
```bash
bun start
```

**Check:**
- [ ] Server boots, prints "Head of Product UI v2 backend — http://localhost:5181"
- [ ] Server prints the workspace root (likely something default like `~/Documents/head-of-product` since iCloud claude-output won't exist on a fresh Mac)
- [ ] No 500 errors in the startup logs
- [ ] No "scheduler skipped" message because we want a fresh setup (the scheduler is gated on `setupComplete` so on first launch it skips — that's correct)

### Step 4: Open in the browser

Navigate to `http://localhost:5181`

**Check:**
- [ ] Page loads (not blank, not "this site can't be reached")
- [ ] Within 1 second, the **Setup Wizard** modal fires
- [ ] Step 1 (Auth) shows both options with detection state
- [ ] On a fresh Mac, both "Claude Code detected" and "Logged in" should show **red X** marks
- [ ] An "Install / login guide" link points to docs.anthropic.com/claude-code
- [ ] The "Use an Anthropic API key" radio works, the input accepts a key (paste a test key)

### Step 5: Walk through the wizard

- [ ] Click "Use an Anthropic API key", paste a real API key, Continue → goes to Step 2 (Workspace)
- [ ] Folder picker opens (the `Browse…` button)
- [ ] Quick-pick chips render — on a fresh Mac, **Documents** and **Desktop** should appear; iCloud `claude-output` and `personal/codebase` should NOT (those don't exist for a new user)
- [ ] Picking a folder updates the "Selected:" chip
- [ ] Continue → Step 3 (Confirm) shows the recap
- [ ] "Finish setup" saves → page reloads
- [ ] After reload, the WelcomePane renders (because `chats.length === 0` for a new user)
- [ ] HealthBanner does NOT fire (because we just set up; the precondition checks pass)

### Step 6: First chat

- [ ] Click "Start your first chat" CTA on the welcome page → navigates to chat
- [ ] Composer renders at the top (NOT obscured by the layout)
- [ ] Type "Hello" and send
- [ ] Response streams back (proves the API key works through the SDK)
- [ ] No "Claude Code native binary not found" error

### Step 7: Activity scan

- [ ] Navigate back to dashboard
- [ ] Click "scan now"
- [ ] Scan starts; tools appear in the live tool log
- [ ] On a fresh Mac with no Linear/Notion configured, the scan likely returns 0 items — that's fine, but the UI should handle it gracefully (not crash, show "Activity 0" or "No items found")

### Step 8: Settings sanity

- [ ] Open Settings (Cmd+, or settings gear icon)
- [ ] All four sections render: Workspace, Authentication, Check sources, Hourly cap
- [ ] "Re-run setup wizard" button works (clicks → reload → wizard fires)
- [ ] "Report an issue" link opens a GitHub issue page with prefilled environment

---

## What's a stopper vs polish

**Stoppers (don't invite alpha until fixed):**
- Install script fails on a fresh Mac
- Wizard doesn't fire on first launch
- First chat returns an opaque error instead of streaming
- Empty-state crashes (scan with no sources, dashboard with no items, etc.)
- HealthBanner fires immediately after successful setup

**Polish (can wait):**
- "Welcome" page suggestions
- Onboarding tooltips
- README rewrite (separate task)
- Scan returns 0 with no helpful message (acceptable for v0.1)

---

## After the test

Pass: file the test result as a one-paragraph note in this repo (e.g., `docs/cold-run-results.md` with date + Mac + outcome).

Fail: open an issue per stopper, prioritize against the rest of Tier 1.

Either way: take a screenshot of the setup wizard, the welcome page, and the dashboard after first scan. They'll be the basis of any onboarding screenshots / README rewrite later.
