bloby-bot 0.23.7 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.23.7",
+  "version": "0.24.0",
   "releaseNotes": [
     "1. new stuff",
     "2. ",

package/supervisor/channels/manager.ts

@@ -221,6 +221,13 @@ export class ChannelManager {
     this.statusListeners.push(listener);
   }
 
+  /** Request a pairing code for phone-number-based linking (mobile alternative to QR) */
+  async requestWhatsAppPairingCode(phoneNumber: string): Promise<string> {
+    const provider = this.providers.get('whatsapp') as WhatsAppChannel | undefined;
+    if (!provider) throw new Error('WhatsApp not initialized — call connect first');
+    return provider.requestPairingCode(phoneNumber);
+  }
+
   /** Delete WhatsApp credentials and disconnect */
   async logoutWhatsApp(): Promise<void> {
     const provider = this.providers.get('whatsapp') as WhatsAppChannel | undefined;

package/supervisor/channels/whatsapp.ts

@@ -181,6 +181,23 @@ export class WhatsAppChannel implements ChannelProvider {
     return this.qrSvg;
   }
 
+  /** Request a pairing code for phone-number-based linking (alternative to QR scan) */
+  async requestPairingCode(phoneNumber: string): Promise<string> {
+    if (!this.sock) throw new Error('WhatsApp socket not initialized — call connect() first');
+    if (this.connected) throw new Error('Already connected — no pairing needed');
+
+    // Digits only, no + or dashes
+    const cleaned = phoneNumber.replace(/[^0-9]/g, '');
+    if (cleaned.length < 8 || cleaned.length > 15) {
+      throw new Error('Invalid phone number — use digits with country code (e.g. 5511999998888)');
+    }
+
+    log.info(`[whatsapp] Requesting pairing code for ${cleaned}...`);
+    const code = await this.sock.requestPairingCode(cleaned);
+    log.info(`[whatsapp] Pairing code generated: ${code}`);
+    return code;
+  }
+
   hasCredentials(): boolean {
     return fs.existsSync(path.join(AUTH_DIR, 'creds.json'));
   }

package/supervisor/index.ts

@@ -355,6 +355,7 @@ export async function startSupervisor() {
     'POST /api/channels/whatsapp/disconnect',
     'POST /api/channels/whatsapp/logout',
     'POST /api/channels/whatsapp/configure',
+    'POST /api/channels/whatsapp/pairing-code',
     'POST /api/channels/send',
   ];
 
@@ -463,8 +464,8 @@ export async function startSupervisor() {
 <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Space+Grotesk:wght@600;700&display=swap" rel="stylesheet">
 <style>
   *{margin:0;padding:0;box-sizing:border-box}
-  body{background:#212121;color:#f5f5f5;font-family:'Inter',system-ui,-apple-system,sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100dvh;margin:0;overflow:hidden}
-  .container{display:flex;flex-direction:column;align-items:center;max-width:360px;width:100%;padding:0 20px}
+  body{background:#212121;color:#f5f5f5;font-family:'Inter',system-ui,-apple-system,sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:100dvh;margin:0;overflow-x:hidden}
+  .container{display:flex;flex-direction:column;align-items:center;max-width:360px;width:100%;padding:20px}
 
   .qr-card{background:#2a2a2a;border:1px solid rgba(255,255,255,0.08);border-radius:20px;padding:28px;width:100%;box-shadow:0 0 0 1px rgba(175,39,227,0.1),0 0 20px -5px rgba(175,39,227,0.15);animation:fade-up .5s ease-out both}
   .qr-inner{background:#fff;border-radius:12px;padding:16px}
@@ -472,6 +473,32 @@ export async function startSupervisor() {
 
   .scan-hint{margin-top:20px;font-size:13px;color:#666;text-align:center;animation:fade-up .5s ease-out .2s both}
 
+  .divider{display:flex;align-items:center;gap:12px;width:100%;margin:24px 0;animation:fade-up .5s ease-out .3s both}
+  .divider-line{flex:1;height:1px;background:rgba(255,255,255,0.08)}
+  .divider-text{font-size:12px;color:#555;text-transform:uppercase;letter-spacing:0.5px}
+
+  .phone-section{width:100%;animation:fade-up .5s ease-out .4s both}
+  .phone-toggle{background:none;border:none;color:#888;font-size:13px;cursor:pointer;font-family:inherit;padding:4px 0;transition:color .2s;width:100%;text-align:center}
+  .phone-toggle:hover{color:#AF27E3}
+
+  .phone-form{display:none;width:100%;margin-top:16px;animation:fade-up .3s ease-out both}
+  .phone-form.visible{display:flex;flex-direction:column;align-items:center;gap:12px}
+  .phone-input-wrap{display:flex;gap:8px;width:100%}
+  .phone-input{flex:1;background:#2a2a2a;border:1px solid rgba(255,255,255,0.1);border-radius:10px;padding:12px 14px;color:#f5f5f5;font-size:15px;font-family:inherit;outline:none;transition:border-color .2s}
+  .phone-input:focus{border-color:#AF27E3}
+  .phone-input::placeholder{color:#555}
+  .phone-btn{background:linear-gradient(135deg,#AF27E3,#FB4072);border:none;border-radius:10px;padding:12px 20px;color:#fff;font-size:14px;font-weight:600;cursor:pointer;font-family:inherit;white-space:nowrap;transition:opacity .2s}
+  .phone-btn:hover{opacity:.9}
+  .phone-btn:disabled{opacity:.5;cursor:not-allowed}
+  .phone-hint{font-size:12px;color:#555;text-align:center}
+
+  .code-display{display:none;width:100%;margin-top:16px;text-align:center;animation:fade-up .3s ease-out both}
+  .code-display.visible{display:block}
+  .code-value{font-family:'Space Grotesk',monospace;font-size:32px;font-weight:700;letter-spacing:6px;background:linear-gradient(135deg,#04D1FE,#AF27E3);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;margin:12px 0}
+  .code-steps{font-size:12px;color:#666;line-height:1.8;text-align:left;margin-top:12px;padding:0 8px}
+  .code-steps li{margin-bottom:2px}
+  .code-error{color:#FB4072;font-size:13px;margin-top:8px}
+
   .confetti-wrap{position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;overflow:hidden}
   .confetti-dot{position:absolute;width:8px;height:8px;border-radius:50%;top:-10px;animation:confetti-fall 2s ease-out forwards}
   @keyframes confetti-fall{0%{opacity:1;transform:translateY(0) translateX(0) rotate(0) scale(1)}100%{opacity:0;transform:translateY(100vh) translateX(var(--drift)) rotate(360deg) scale(.5)}}
@@ -497,14 +524,104 @@ ${connected
 </div>
 <script>async function relink(){await fetch('/api/channels/whatsapp/logout',{method:'POST'});await fetch('/api/channels/whatsapp/connect',{method:'POST'});setTimeout(()=>location.reload(),2000)}</script>`
   : qr
-    ? `<div class="qr-card"><div class="qr-inner">${qr}</div></div><p class="scan-hint">Scan with WhatsApp to link</p>`
+    ? `<div class="qr-card"><div class="qr-inner">${qr}</div></div>
+<p class="scan-hint">Scan with WhatsApp to link</p>
+
+<div class="divider"><span class="divider-line"></span><span class="divider-text">or</span><span class="divider-line"></span></div>
+
+<div class="phone-section">
+  <button class="phone-toggle" onclick="togglePhoneForm()">Link with phone number instead</button>
+  <div id="phoneForm" class="phone-form">
+    <div class="phone-input-wrap">
+      <input id="phoneInput" class="phone-input" type="tel" placeholder="5511999998888" inputmode="numeric" pattern="[0-9]*">
+      <button id="phoneBtn" class="phone-btn" onclick="requestCode()">Get code</button>
+    </div>
+    <p class="phone-hint">Digits only, with country code. No + or dashes.</p>
+  </div>
+  <div id="codeDisplay" class="code-display">
+    <p style="font-size:13px;color:#999">Enter this code in WhatsApp:</p>
+    <div id="codeValue" class="code-value"></div>
+    <ol class="code-steps">
+      <li>Open <b>WhatsApp</b> on your phone</li>
+      <li>Go to <b>Settings &gt; Linked Devices</b></li>
+      <li>Tap <b>Link a Device</b></li>
+      <li>Tap <b>Link with phone number instead</b></li>
+      <li>Enter the code above</li>
+    </ol>
+    <div id="codeError" class="code-error"></div>
+    <button class="phone-toggle" style="margin-top:12px" onclick="resetPhoneForm()">Try again</button>
+  </div>
+</div>`
     : '<p class="loading">Starting WhatsApp...</p>'}
 </div>
-${!connected ? '<script>setTimeout(()=>location.reload(),4000)</script>' : ''}
+${!connected ? `<script>
+  setTimeout(()=>location.reload(),4000);
+
+  function togglePhoneForm(){
+    document.getElementById('phoneForm').classList.toggle('visible');
+  }
+  function resetPhoneForm(){
+    document.getElementById('codeDisplay').classList.remove('visible');
+    document.getElementById('phoneForm').classList.add('visible');
+    document.getElementById('phoneInput').value='';
+    document.getElementById('codeError').textContent='';
+  }
+  async function requestCode(){
+    const input=document.getElementById('phoneInput');
+    const btn=document.getElementById('phoneBtn');
+    const phone=input.value.replace(/[^0-9]/g,'');
+    if(phone.length<8){input.style.borderColor='#FB4072';return}
+    btn.disabled=true;btn.textContent='Requesting...';
+    try{
+      const res=await fetch('/api/channels/whatsapp/pairing-code',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({phoneNumber:phone})});
+      const data=await res.json();
+      if(!res.ok) throw new Error(data.error||'Request failed');
+      document.getElementById('phoneForm').classList.remove('visible');
+      const display=document.getElementById('codeDisplay');
+      display.classList.add('visible');
+      const formatted=data.code.match(/.{1,4}/g).join(' - ');
+      document.getElementById('codeValue').textContent=formatted;
+    }catch(err){
+      const errEl=document.getElementById('codeError');
+      if(!document.getElementById('codeDisplay').classList.contains('visible')){
+        const hint=document.querySelector('.phone-hint');
+        if(hint) hint.textContent=err.message;
+        hint.style.color='#FB4072';
+      }else{
+        errEl.textContent=err.message;
+      }
+    }finally{btn.disabled=false;btn.textContent='Get code'}
+  }
+  document.getElementById('phoneInput')?.addEventListener('keydown',e=>{if(e.key==='Enter')requestCode()});
+</script>` : ''}
 </body></html>`);
         return;
       }
 
+      // POST /api/channels/whatsapp/pairing-code — request phone-number pairing code (mobile alternative to QR)
+      if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/pairing-code') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        req.on('end', async () => {
+          try {
+            const { phoneNumber } = JSON.parse(body);
+            if (!phoneNumber) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ error: 'Missing phoneNumber' }));
+              return;
+            }
+            const code = await channelManager.requestWhatsAppPairingCode(phoneNumber);
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true, code }));
+          } catch (err: any) {
+            const status = err.message?.includes('rate') ? 429 : 500;
+            res.writeHead(status);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        });
+        return;
+      }
+
       // POST /api/channels/whatsapp/connect — start WhatsApp connection (triggers QR)
       if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/connect') {
         (async () => {

package/worker/prompts/bloby-system-prompt.txt

@@ -266,32 +266,17 @@ If something fails, own it: "Hmm, that didn't work. Let me try again."
 
 ## Skills
 
-Skills live in `skills/` — each skill is a folder with instructions and resources:
+Skills live in `skills/` — each skill is a folder with instructions and resources. Each skill has a `SKILL.md` with instructions for you on how to use it.
 
-```
-skills/
-  whatsapp-clinic/
-    SKILL.md          # Instructions for you (how to use this skill)
-    SCRIPT.md         # Customer-facing prompt (loaded as system prompt in business mode)
-    files/            # RAG documents, FAQs, etc.
-```
-
-Only ONE skill can be active for customer-facing mode at a time. The active skill is set in the channel config (`channels.whatsapp.skill`). When your human asks to switch skills, update the config:
-```bash
-curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
-  -H "Content-Type: application/json" -d '{"skill":"whatsapp-clinic"}'
-```
+Your installed skills and their SKILL.md contents are injected into your context automatically. If your human asks you to update a skill's behavior, edit the files INSIDE `skills/{skill-name}/`.
 
 **IMPORTANT: When editing skill files, always use the full path inside the skill directory.**
-- Correct: `skills/whatsapp-clinic/SCRIPT.md`
+- Correct: `skills/my-skill/SCRIPT.md`
 - Wrong: `SCRIPT.md` (this writes to workspace root!)
 
-Your installed skills and their SKILL.md contents are injected below in your context. If your human asks you to update a skill's behavior or script, edit the files INSIDE `skills/{skill-name}/`.
+## Channels (WhatsApp, Telegram, Discord, etc.)
 
-**Separation of concerns:**
-- `MYSELF.md`, `MYHUMAN.md`, `MEMORY.md` — about YOU and your human. Always yours.
-- `skills/{name}/SCRIPT.md` — business logic for customer interactions. Belongs to the skill.
-- `whatsapp/{phone}.md` — customer conversation logs. Your memory of each customer.
+You can communicate through messaging channels beyond the chat bubble. Channel support is provided by **skills** — if your human wants to use WhatsApp, Telegram, Discord, or any other channel, check the Bloby Marketplace for the corresponding skill. They install it, the skill teaches you everything you need to know about that channel.
 
 ## Marketplace — Getting New Skills
 
@@ -319,94 +304,6 @@ For a machine-readable catalog: `GET https://bloby.bot/api/marketplace/products`
 
 ---
 
-## Channels (WhatsApp, Telegram, etc.)
-
-You can communicate through messaging channels beyond the chat bubble. Currently supported: **WhatsApp**.
-
-### CRITICAL: How WhatsApp Responses Work
-
-**Your text response IS the WhatsApp reply.** When you receive a message tagged with `[WhatsApp | ...]`, the supervisor takes whatever you respond with and sends it directly to WhatsApp. You do NOT need to use curl or `/api/channels/send` to reply — just respond normally as if you're talking to the person.
-
-**Do NOT use `/api/channels/send` to reply to incoming WhatsApp messages.** That endpoint is ONLY for proactive messages (during pulse, cron, or when you want to initiate a conversation). If you use it to reply, the person will get duplicate messages.
-
-**Adjust your style for WhatsApp:** Keep messages shorter and more conversational than chat. No markdown headers, no code blocks unless asked. Think texting, not email.
-
-### Channel Config
-
-Your channel configuration is injected below (if any channels are configured). It comes from `~/.bloby/config.json` — a file OUTSIDE your workspace that the supervisor manages.
-
-### How Channels Work
-
-When a message arrives via WhatsApp, the supervisor wraps it with context:
-```
-[WhatsApp | 5511999888777 | customer | Alice]
-Hi, I'd like to schedule an appointment.
-```
-
-The format is: `[Channel | phone | role | name (optional)]`
-
-- **role=admin**: This is your human or an authorized admin. Use your normal personality, full capabilities, main system prompt.
-- **role=customer**: This is someone else messaging. Follow the instructions from the active skill's SCRIPT.md (loaded as your system prompt).
-
-### WhatsApp Modes
-
-**Channel Mode** (default): Your human's own WhatsApp number. Only self-chat triggers you — messages from other people are completely ignored. This is "just talk to me" mode.
-
-**Business Mode**: Bloby has its own dedicated number. Numbers in the `admins` array get admin access (main system prompt). Everyone else is a customer (support prompt).
-
-### Setting Up WhatsApp
-
-When your human asks to configure WhatsApp:
-1. Start the connection: `curl -s -X POST http://localhost:7400/api/channels/whatsapp/connect`
-2. Tell them to open the QR page: `http://localhost:7400/api/channels/whatsapp/qr-page` (Don't mention the URL until you are actually starting the connection)
-3. They scan the QR with their WhatsApp app
-4. The default mode is **channel** (self-chat only)
-
-To switch to **business mode** with admin numbers:
-```bash
-curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
-  -H "Content-Type: application/json" \
-  -d '{"mode":"business","admins":["+17865551234","+5511999887766"]}'
-```
-
-### Sending Proactive Messages
-
-To INITIATE a WhatsApp message (during pulse, cron, or when you want to reach out first):
-```bash
-curl -s -X POST http://localhost:7400/api/channels/send \
-  -H "Content-Type: application/json" \
-  -d '{"channel":"whatsapp","to":"5511999888777","text":"Your appointment is confirmed for tomorrow at 2pm."}'
-```
-
-**Remember:** This is ONLY for starting new conversations or sending unprompted messages. When replying to an incoming message, just respond normally — the supervisor handles delivery.
-
-### Customer Conversation Logs
-
-When you finish a conversation with a **customer** via WhatsApp, save a summary to `whatsapp/{phone}.md`:
-- Key details from the conversation
-- Outcome (appointment scheduled, question answered, etc.)
-- Any follow-ups needed
-- Timestamp
-
-This is your memory of that customer. Next time they message, read their file first.
-
-### Channel API Reference
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/channels/status` | GET | List all channel statuses |
-| `/api/channels/whatsapp/qr` | GET | Get current QR code SVG |
-| `/api/channels/whatsapp/qr-page` | GET | Standalone QR scanning page |
-| `/api/channels/whatsapp/connect` | POST | Start WhatsApp (triggers QR if needed) |
-| `/api/channels/whatsapp/disconnect` | POST | Disconnect WhatsApp |
-| `/api/channels/whatsapp/logout` | POST | Disconnect + delete credentials |
-| `/api/channels/whatsapp/configure` | POST | Set mode + admins array |
-| `/api/channels/send` | POST | Send proactive message via any channel |
-
-All endpoints are on `http://localhost:7400`.
-
----
-
 ## Dashboard Linking
 
 When your human gives you a claim code (format: XXXX-XXXX-XXXX-XXXX) to link you to their bloby.bot dashboard, read your relay token from `~/.bloby/config.json` (field: `relay.token`) and verify it: `curl -s -X POST https://api.bloby.bot/api/claim/verify -H "Content-Type: application/json" -H "Authorization: Bearer <relay_token>" -d '{"code":"<THE_CODE>"}'`. Tell your human whether it succeeded or failed.

package/workspace/skills/whatsapp/SKILL.md

@@ -8,40 +8,84 @@ Gives your agent a WhatsApp number. Connect via QR code, send and receive messag
 
 None.
 
-## Setup
+---
 
-### 1. Connect WhatsApp
+## How Responses Work
+
+**Your text response IS the WhatsApp reply.** When you receive a message tagged with `[WhatsApp | ...]`, the supervisor takes whatever you respond with and sends it directly to WhatsApp. You do NOT need to use curl or `/api/channels/send` to reply — just respond normally.
+
+**Do NOT use `/api/channels/send` to reply to incoming WhatsApp messages.** That endpoint is ONLY for proactive messages (during pulse, cron, or when you want to initiate a conversation). If you use it to reply, the person will get duplicate messages.
+
+**Adjust your style for WhatsApp:** Keep messages shorter and more conversational than chat. No markdown headers, no code blocks unless asked. Think texting, not email.
+
+---
 
-Tell your human to open the QR page so they can scan it with their phone:
+## How Messages Arrive
+
+When a message arrives via WhatsApp, the supervisor wraps it with context:
 
 ```
-Open this link to connect WhatsApp: http://localhost:3000/api/channels/whatsapp/qr-page
+[WhatsApp | 5511999888777 | customer | Alice]
+Hi, I'd like to schedule an appointment.
 ```
 
-If the QR page doesn't load, initiate the connection first:
+The format is: `[WhatsApp | phone | role | name (optional)]`
+
+- **role=admin**: This is your human or an authorized admin. Use your normal personality, full capabilities, main system prompt.
+- **role=customer**: This is someone else messaging. Follow the instructions from the active skill's SCRIPT.md (loaded as your system prompt for that conversation).
+
+---
+
+## Channel Config
+
+Your channel configuration is injected into your context (if any channels are configured). It comes from `~/.bloby/config.json` — a file OUTSIDE your workspace that the supervisor manages.
 
+---
+
+## Modes
+
+**Channel Mode** (default): Your human's own WhatsApp number. Only self-chat (messages your human sends to themselves) triggers you — messages from other people are completely ignored. This is "just talk to me" mode.
+
+**Business Mode**: Bloby has its own dedicated WhatsApp number. Numbers in the `admins` array get admin access (main system prompt). Everyone else is a customer and gets the support prompt from the active skill's SCRIPT.md.
+
+---
+
+## Setup
+
+### 1. Connect WhatsApp
+
+When your human asks to configure WhatsApp:
+
+1. Start the connection:
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/whatsapp/connect
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/connect
 ```
 
-Then direct the human to the QR page. They scan it with WhatsApp on their phone. The page shows a confirmation when connected.
+2. Tell them to open the QR page: `http://localhost:7400/api/channels/whatsapp/qr-page`
+   (Don't mention the URL until you are actually starting the connection)
+
+3. They scan the QR with their WhatsApp app
 
-### 2. Choose a mode
+4. The default mode is **channel** (self-chat only)
 
-After connecting, configure the mode based on what you need:
+If the QR page doesn't load, make sure you initiated the connection first (step 1).
 
-**Channel mode** (default) — personal assistant. Only messages you send to yourself trigger the agent. All other incoming messages are ignored.
+**On mobile?** The QR page also offers a "Link with phone number instead" option. The user enters their phone number, gets an 8-character code, and types it into WhatsApp (Settings > Linked Devices > Link a Device > "Link with phone number instead"). No camera needed.
+
+### 2. Choose a Mode
+
+**Channel mode** (default) — personal assistant. Only self-chat triggers the agent:
 
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/whatsapp/configure \
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
   -H "Content-Type: application/json" \
   -d '{"mode":"channel"}'
 ```
 
-**Business mode** — customer-facing. The agent responds to incoming messages from customers using a skill's SCRIPT.md. Admin numbers get full agent access.
+**Business mode** — customer-facing. The agent responds to incoming messages from customers using a skill's SCRIPT.md. Admin numbers get full agent access:
 
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/whatsapp/configure \
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
   -H "Content-Type: application/json" \
   -d '{"mode":"business","admins":["ADMIN_PHONE_1","ADMIN_PHONE_2"],"skill":"SKILL_FOLDER_NAME"}'
 ```
@@ -50,60 +94,91 @@ Replace `ADMIN_PHONE_1` with the human's phone number (digits only, with country
 
 ### 3. Verify
 
-Check connection status:
-
 ```bash
-curl -s http://localhost:3000/api/channels/status
+curl -s http://localhost:7400/api/channels/status
 ```
 
 Expected: `"channel":"whatsapp","connected":true`
 
-## Usage
+---
+
+## Business Mode — Active Skill
+
+Only ONE skill can be active for customer-facing mode at a time. The active skill is set in the channel config (`channels.whatsapp.skill`). When your human asks to switch skills:
+
+```bash
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
+  -H "Content-Type: application/json" -d '{"skill":"whatsapp-clinic"}'
+```
+
+The active skill should have:
+- `SCRIPT.md` — the customer-facing system prompt (loaded automatically for customer conversations)
+- Optionally a `customer_data/` directory — per-customer memory files (named by phone number, e.g. `5511999887766.md`)
+
+---
+
+## Sending Proactive Messages
 
-### Sending messages
+To INITIATE a WhatsApp message (during pulse, cron, or when you want to reach out first):
 
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/send \
+curl -s -X POST http://localhost:7400/api/channels/send \
   -H "Content-Type: application/json" \
-  -d '{"channel":"whatsapp","to":"PHONE_NUMBER","text":"Your message here"}'
+  -d '{"channel":"whatsapp","to":"5511999888777","text":"Your appointment is confirmed for tomorrow at 2pm."}'
 ```
 
 Phone number format: digits with country code (e.g. `5511999887766`). The system normalizes to WhatsApp JID format automatically.
 
-### Receiving messages
+**Remember:** This is ONLY for starting new conversations or sending unprompted messages. When replying to an incoming message, just respond normally — the supervisor handles delivery.
 
-Messages arrive automatically through the supervisor. In **channel mode**, only self-chat messages reach you. In **business mode**, customer messages are routed to the active skill's SCRIPT.md and admin messages reach the full agent.
+---
 
-### Voice notes
+## Customer Conversation Logs
 
-Voice messages are automatically transcribed via Whisper and delivered as text. No extra setup needed if whisper is configured on the supervisor.
+When you finish a conversation with a **customer** via WhatsApp, save a summary to `whatsapp/{phone}.md`:
+- Key details from the conversation
+- Outcome (appointment scheduled, question answered, etc.)
+- Any follow-ups needed
+- Timestamp
 
-### Typing indicator
+This is your memory of that customer. Next time they message, read their file first.
+
+---
+
+## Voice Notes
+
+Voice messages are automatically transcribed via Whisper and delivered as text. No extra setup needed if Whisper is configured on the supervisor.
+
+## Typing Indicator
 
 The agent automatically shows "typing..." to the recipient while composing a response. This is handled by the supervisor — no action needed from you.
 
-### Message buffering (business mode)
+## Message Buffering (Business Mode)
 
-In business mode, rapid messages from the same customer are debounced (4 second window) and delivered together. The system maintains a 30-message conversation buffer per customer.
+In business mode, rapid messages from the same customer are debounced (4-second window) and delivered together. The system maintains a 30-message conversation buffer per customer.
 
-### Concurrent conversations (business mode)
+## Concurrent Conversations (Business Mode)
 
 Up to 5 customer conversations can run in parallel. Additional messages queue automatically.
 
+---
+
 ## Account Management
 
 **Disconnect** (keep credentials for later):
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/whatsapp/disconnect
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/disconnect
 ```
 
 **Logout** (delete credentials, requires new QR scan):
 ```bash
-curl -s -X POST http://localhost:3000/api/channels/whatsapp/logout
+curl -s -X POST http://localhost:7400/api/channels/whatsapp/logout
 ```
 
 **Switch accounts** (relink): Use the "Relink" button on the QR page, or logout + connect again.
 
+---
+
 ## Human Interaction
 
 - The human must scan the QR code with their phone — this cannot be automated
@@ -111,7 +186,27 @@ curl -s -X POST http://localhost:3000/api/channels/whatsapp/logout
 - In business mode, explain to the human that admin numbers get full agent access while all other numbers get the customer-facing skill
 - If the human asks about privacy: credentials are stored locally at `~/.bloby/channels/whatsapp/auth/`, never sent to external servers
 
-## Notes
+---
+
+## API Reference
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/channels/status` | GET | List all channel statuses |
+| `/api/channels/whatsapp/qr` | GET | Get current QR code SVG |
+| `/api/channels/whatsapp/qr-page` | GET | Standalone QR scanning page |
+| `/api/channels/whatsapp/connect` | POST | Start WhatsApp (triggers QR if needed) |
+| `/api/channels/whatsapp/disconnect` | POST | Disconnect WhatsApp |
+| `/api/channels/whatsapp/logout` | POST | Disconnect + delete credentials |
+| `/api/channels/whatsapp/configure` | POST | Set mode + admins + skill |
+| `/api/channels/whatsapp/pairing-code` | POST | Get 8-char pairing code (mobile linking) |
+| `/api/channels/send` | POST | Send proactive message via channel |
+
+All endpoints are on `http://localhost:7400`.
+
+---
+
+## Technical Notes
 
 - Baileys is a reverse-engineering of WhatsApp Web. It can break if WhatsApp changes their protocol. Reconnection is automatic on network drops.
 - If you get error 401 (loggedOut), credentials were invalidated — the human needs to re-scan QR.