# Customer Onboard

End-to-end onboarding for a new QuickCall Trace customer. Handles API key generation, server deployment, and installation instructions.

## Input

The user provides an org name, e.g. `/customer-onboard staple-ai`.
If no argument: ask for the org name.

## Steps

### 1. Generate API key

Generate a push API key for the org. Convention: `{org-slug}_{random_hex}`.

```bash
python3 -c "import secrets; org='ORG_SLUG'; print(f'{org}_{secrets.token_hex(24)}')"
```

Replace `ORG_SLUG` with the org name (lowercase, hyphens replaced with no separator or kept as-is matching existing keys).

### 2. Update `.prod.env`

Add the new key to **two places** in `.prod.env`:

1. **Append to `QC_TRACE_PUSH_KEYS`** — comma-separated list on line 22
2. **Add a `ORG_{NAME}_API_KEY=` reference line** — under the per-org section

Use the Edit tool for both changes. Do NOT touch any other env vars.

### 3. Update GitHub secret and deploy

```bash
# Update the GitHub secret with the full comma-separated push keys list
gh secret set QC_TRACE_PUSH_KEYS --repo quickcall-dev/trace --body '<full comma-separated list from .prod.env>'

# Trigger deploy
gh workflow run deploy.yml --repo quickcall-dev/trace --ref main
```

Wait for deploy to complete:
```bash
gh run list --repo quickcall-dev/trace --workflow=deploy.yml --limit 1 --json status,conclusion -q '.[0]'
```

### 4. Verify key works

Test the key against the live server:
```bash
curl -s -o /dev/null -w "%{http_code}" -X POST https://trace.quickcall.dev/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <new-key>" \
  -d '[{"id":"test-onboard","session_id":"test-onboard","source":"qc_trace_install","msg_type":"system","timestamp":"2026-01-01T00:00:00Z","content":"onboard key test","source_schema_version":1}]'
```

**STOP if not 200.** Debug before giving the customer anything.

### 5. Generate installation instructions

Write the customer's install instructions to `onboard.md` in the project root:

```markdown
## QuickCall Trace — Installation

Run this in your terminal:

\```bash
curl -fsSL https://quickcall.dev/trace/install.sh | sh -s -- <org-name> <api-key>
\```

After installation:
- The daemon starts automatically and runs in the background
- It watches your AI CLI sessions (Claude Code, Codex, Gemini, Cursor) and syncs them
- **macOS users**: When prompted for Documents/Desktop/Downloads folder access, click **Allow**

Verify it's working:
\```bash
quickcall status
\```

### Troubleshooting

If `quickcall status` shows "Daemon: not running", do a clean uninstall + reinstall:

\```bash
# clean uninstall
curl -fsSL https://quickcall.dev/trace/uninstall.sh | sh

# clean install
curl -fsSL https://quickcall.dev/trace/install.sh | sh -s -- <org-name> <api-key>
\```

### UnicodeEncodeError / latin-1 codec error

This happens when the API key gets invisible unicode characters from copy-pasting from chat apps (WhatsApp, Slack, iMessage). Fix: copy the install command from a **plain text** source (terminal, notepad, or this markdown file rendered raw).

### macOS protected folder access (Documents / Desktop / Downloads)

If the daemon can't access repos in ~/Documents, ~/Desktop, or ~/Downloads — reset the folder permissions and reinstall:

\```bash
# reset permissions for protected folders
tccutil reset SystemPolicyDocumentsFolder
tccutil reset SystemPolicyDesktopFolder
tccutil reset SystemPolicyDownloadsFolder

# clean uninstall + reinstall
curl -fsSL https://quickcall.dev/trace/uninstall.sh | sh
curl -fsSL https://quickcall.dev/trace/install.sh | sh -s -- <org-name> <api-key>
\```

When macOS prompts for folder access, click **Allow**.
```

Replace `<org-name>` and `<api-key>` with actual values in the generated `onboard.md`.

### 6. Verify data flowing (after customer installs)

Use `/query` to check:
```bash
source .prod.env && psql "$QC_TRACE_DSN" -c "SELECT org, COUNT(*) as sessions FROM sessions WHERE org = '<org-name>' GROUP BY org;"
source .prod.env && psql "$QC_TRACE_DSN" -c "SELECT * FROM daemon_heartbeats WHERE org = '<org-name>';"
```

## Checklist

- [ ] API key generated and added to `.prod.env`
- [ ] GitHub secret `QC_TRACE_PUSH_KEYS` updated
- [ ] Deploy triggered and succeeded
- [ ] Key verified against live server (HTTP 200)
- [ ] `onboard.md` generated with install instructions
- [ ] Shared instructions with customer
- [ ] Customer installed and data is flowing
