docs: add manual end-to-end pairing test runbook

docs/superpowers/specs/manual-test-pairing.md

@@ -0,0 +1,56 @@
+# Manual test: WhatsApp pairing end-to-end
+
+Run this checklist on every release that touches the pairing flow. It can't be
+automated — pairing requires a real phone scanning a QR.
+
+## Prerequisites
+- `.env.development` filled in with real values.
+- `scripts/db.sh migrate && scripts/db.sh seed` ran clean.
+- `scripts/dev.sh up` is running; `scripts/dev.sh logs bot` is tailing.
+- Dev WhatsApp mock account installed on a test phone (NOT brother's prod accounts).
+- Dev Telegram bot opened in Telegram.
+
+## Steps
+
+1. Send `/start` to the dev bot. Expected: welcome message.
+2. Send `/help`. Expected: command list including `/pair`.
+3. Send `/pair "Test Account 1"`. Expected:
+   - Reply: "📡 Starting pairing for 'Test Account 1'..."
+   - Within ~5 seconds, a QR PNG arrives.
+4. On the test phone: WhatsApp → Settings → Linked Devices → Link a Device → scan the QR.
+5. Within ~5 seconds expect Telegram replies:
+   - "✅ 'Test Account 1' connected as +60xxxxxxx" (your test phone number).
+   - "Synced N groups. Ready to send reminders." (N = number of WA groups).
+6. Send `/accounts`. Expected: "• Test Account 1 (+60xxx) — db:connected live:connected".
+7. Send `/groups "Test Account 1"`. Expected: bulleted list of groups.
+8. Verify in Postgres:
+   ```bash
+   NO_SUDO=1 scripts/dev.sh exec sh -c 'cd packages/db && pnpm exec tsx -e "
+   (async () => {
+     const { Pool } = await import(\"pg\");
+     const p = new Pool({ connectionString: process.env.DATABASE_URL });
+     console.log(\"accounts:\", (await p.query(\"SELECT label, status, phone_number FROM whatsapp_accounts\")).rows);
+     console.log(\"groups:\", (await p.query(\"SELECT count(*) FROM whatsapp_groups\")).rows);
+     console.log(\"audit:\", (await p.query(\"SELECT action FROM audit_log ORDER BY created_at DESC LIMIT 5\")).rows);
+     await p.end();
+   })();
+   "'
+   ```
+   Expected: account connected, groups present, audit shows `account.paired`.
+9. Restart the bot: `NO_SUDO=1 scripts/dev.sh restart-bot`. Expected: in logs, "session-manager: state change connecting → connected" for the test account, no QR re-prompt.
+10. Send `/unpair "Test Account 1"`. Expected:
+    - Reply: "🗑 'Test Account 1' unpaired. Session files deleted."
+    - `whatsapp_accounts.status` is `logged_out`.
+    - Directory `dev-data/sessions/<account-id>/` is gone.
+
+## Failure modes to verify
+
+- **QR expiry:** ignore the QR for 30s. Bot edits the same Telegram message with a new QR (no second photo). Repeat 3-5 times to verify edits keep working.
+- **Wrong-account `/pair`:** as a non-whitelisted Telegram user, send `/pair "X"`. Expected: "Sorry, this bot is private."
+- **Re-pair while connected:** send `/pair "Test Account 1"` again immediately after step 5. Expected: "already connected. Use /unpair first."
+
+## Sign-off
+- [ ] All steps passed
+- [ ] Postgres rows match expectations
+- [ ] No errors in `scripts/dev.sh logs bot`
+- [ ] Tester: ____________   Date: ____________