diff --git a/.claude/skills/add-whatsapp/SKILL.md b/.claude/skills/add-whatsapp/SKILL.md
index f572ea0..660123a 100644
--- a/.claude/skills/add-whatsapp/SKILL.md
+++ b/.claude/skills/add-whatsapp/SKILL.md
@@ -115,21 +115,33 @@ Tell the user to run `npm run auth` in another terminal, then:
 
 For pairing code:
 
+Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
+
+Run the auth process in the background and poll `store/pairing-code.txt` for the code:
+
 ```bash
-npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number>
+rm -f store/pairing-code.txt && npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
 ```
 
-(Bash timeout: 150000ms). Display PAIRING_CODE from output.
+Then immediately poll for the code (do NOT wait for the background command to finish):
 
-Tell the user:
+```bash
+for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
+```
 
-> A pairing code will appear. **Enter it within 60 seconds** — codes expire quickly.
+Display the code to the user the moment it appears. Tell them:
+
+> **Enter this code now** — it expires in ~60 seconds.
 >
 > 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
 > 2. Tap **Link with phone number instead**
 > 3. Enter the code immediately
->
-> If the code expires, re-run the command — a new code will be generated.
+
+After the user enters the code, poll for authentication to complete:
+
+```bash
+for i in $(seq 1 60); do grep -q 'AUTH_STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'AUTH_STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
+```
 
 **If failed:** qr_timeout → re-run. logged_out → delete `store/auth/` and re-run. 515 → re-run. timeout → ask user, offer retry.
 
diff --git a/.claude/skills/add-whatsapp/add/setup/whatsapp-auth.ts b/.claude/skills/add-whatsapp/add/setup/whatsapp-auth.ts
index 4aa3433..2cbec76 100644
--- a/.claude/skills/add-whatsapp/add/setup/whatsapp-auth.ts
+++ b/.claude/skills/add-whatsapp/add/setup/whatsapp-auth.ts
@@ -306,6 +306,16 @@ async function handlePairingCode(
     process.exit(3);
   }
 
+  // Write to file immediately so callers can read it without waiting for stdout
+  try {
+    fs.writeFileSync(
+      path.join(projectRoot, 'store', 'pairing-code.txt'),
+      pairingCode,
+    );
+  } catch {
+    /* non-fatal */
+  }
+
   // Emit pairing code immediately so the caller can display it to the user
   emitAuthStatus('pairing-code', 'pairing_code_ready', 'waiting', {
     PAIRING_CODE: pairingCode,