instar 0.12.21 → 0.12.22

package/.claude/skills/setup-wizard/skill.md

@@ -1283,9 +1283,11 @@ Tell the user:
 
 **Wait for confirmation.**
 
-**Option A: Dashboard QR (preferred — no external browser needed)**
+**Option A: Dashboard QR (preferred)**
 
-The agent's dashboard serves the QR code at `GET /whatsapp/qr`. Open this in the browser:
+The dashboard renders the WhatsApp QR code after PIN authentication. **Do NOT navigate directly to `/whatsapp/qr`** — that API endpoint requires a Bearer auth header which browsers can't pass via URL. Instead, use the dashboard UI:
+
+**Step 1: Navigate to dashboard**
 
 **If using Playwright:**
 ```
@@ -1297,22 +1299,53 @@ mcp__playwright__browser_navigate({ url: "http://localhost:<PORT>/dashboard" })
 mcp__claude-in-chrome__navigate({ url: "http://localhost:<PORT>/dashboard", tabId: <tab_id> })
 ```
 
-Navigate to the WhatsApp section of the dashboard. The QR code should be visible.
+**Step 2: Authenticate with PIN**
 
-Tell the user:
+The dashboard requires a PIN (the `authToken` from `.instar/config.json`). Read the PIN:
+```bash
+jq -r '.authToken' <project_dir>/.instar/config.json
+```
+
+Take a snapshot to find the PIN input field, enter the PIN, and click Connect/Submit.
+
+**Step 3: Open WhatsApp QR panel**
+
+After authenticating, look for a "WhatsApp" button in the dashboard header. Click it to open the QR panel. The dashboard fetches `/whatsapp/qr` with the auth token internally and renders the QR code using the qrcode.js library.
+
+**Step 4: Wait for QR to appear**
+
+The WhatsApp adapter may take a few seconds to generate the first QR code after server start. If the QR panel shows "disconnected" or no QR:
+- Wait 5 seconds and refresh the panel (click the WhatsApp button again)
+- Retry up to 6 times (30 seconds total)
+- The Baileys adapter needs time to initialize and receive the first QR from WhatsApp servers
+
+Once the QR is visible, tell the user:
 
 > A QR code should be visible in the browser window. On your phone:
 > 1. Open WhatsApp
 > 2. Go to **Settings → Linked Devices → Link a Device**
 > 3. Scan the QR code in the browser
+>
+> Note: The QR code refreshes every ~20 seconds — that's normal. Just scan the current one.
+
+**Option B: Fetch QR via API and display (fallback if dashboard doesn't render)**
 
-**Option B: WhatsApp Web direct (fallback if dashboard QR isn't rendering)**
+If the dashboard QR panel isn't working, fetch the QR data via API and display it:
+
+```bash
+QR_DATA=$(curl -s -H "Authorization: Bearer <AUTH_TOKEN>" http://localhost:<PORT>/whatsapp/qr | jq -r '.qr')
+```
+
+If `QR_DATA` is not null, you can render it in the browser using JavaScript:
+```
+mcp__playwright__browser_evaluate({ expression: "document.body.innerHTML = '<div id=\"qr\"></div><script src=\"https://cdn.jsdelivr.net/npm/qrcode@1.5.4/build/qrcode.min.js\"></' + 'script><script>QRCode.toCanvas(document.createElement(\"canvas\"), \"QR_DATA_HERE\", {width:300}, (e,c) => document.getElementById(\"qr\").appendChild(c))</' + 'script>'" })
+```
 
-Navigate to `https://web.whatsapp.com` in the browser. The QR code there works the same way — scan it with WhatsApp on your phone.
+Or simply relay the QR data to the user and suggest they use the pairing code method instead (Option C fallback).
 
-> If you don't see a QR code in the dashboard, I've opened WhatsApp Web instead. Scan the QR code there with your phone.
+**Option C: Do NOT use WhatsApp Web (web.whatsapp.com) directly**
 
-**Note:** This approach requires the Baileys session to NOT be simultaneously connected. If the server's Baileys adapter already took the QR, WhatsApp Web won't show one. In that case, use the dashboard QR endpoint or the pairing code fallback.
+WhatsApp Web connects as its own linked device. The Baileys adapter is ALSO a linked device. WhatsApp only allows one web session at a time, so opening WhatsApp Web would conflict with the Baileys connection. Always use the dashboard QR or API QR — these are the Baileys adapter's QR, not a separate session.
 
 **Step 4: Wait for connection**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.12.21",
+  "version": "0.12.22",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-03-07T19:14:02.219Z",
-  "instarVersion": "0.12.21",
+  "generatedAt": "2026-03-07T19:36:23.999Z",
+  "instarVersion": "0.12.22",
   "entryCount": 166,
   "entries": {
     "hook:session-start": {
@@ -295,7 +295,7 @@
       "type": "skill",
       "domain": "skills",
       "sourcePath": ".claude/skills/setup-wizard/skill.md",
-      "contentHash": "b21b0c7e57c0fb346ad444912a1842139aed902fc3a91c76fe2d3242917d77e2",
+      "contentHash": "0984ec7e26e751b5068c7735e53fcfc1c6296e8fe41d9bfbf9bc25414afd7650",
       "since": "2025-01-01"
     },
     "route-group:health": {

package/upgrades/0.12.22.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.12.22
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed WhatsApp QR pairing flow in the setup wizard:
+
+- **Dashboard-first approach**: The wizard now navigates to the dashboard UI, authenticates with the PIN, and clicks the WhatsApp button to render the QR — instead of trying to hit `/whatsapp/qr` directly in the browser (which fails because that API requires Bearer auth headers that browsers can't pass via URL).
+- **QR initialization retry**: Added retry loop (up to 30 seconds) for when the WhatsApp adapter hasn't generated its first QR code yet after server start.
+- **Removed WhatsApp Web fallback**: WhatsApp Web creates a competing linked device session that conflicts with the Baileys adapter. The wizard no longer suggests opening web.whatsapp.com.
+- **API QR fallback**: If dashboard rendering fails, the wizard fetches QR data via curl with auth and renders it in the browser via JavaScript.
+
+## What to Tell Your User
+
+- **Smoother WhatsApp setup**: "The QR code pairing flow is more reliable now — it properly uses the dashboard to display the QR code."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dashboard-based QR pairing | Automatic during setup — navigates to dashboard, authenticates, opens QR panel |
+| QR initialization retry | Automatic — waits up to 30s for adapter to generate first QR |