@rubytech/create-sitedesk-code 0.1.340

package/payload/platform/plugins/whatsapp/references/channels-whatsapp.md

@@ -0,0 +1,307 @@
+# WhatsApp Channels
+
+WhatsApp connects via Baileys multi-account:
+
+| Provider | Use Case | Connection |
+|----------|----------|------------|
+| **baileys** | All WhatsApp accounts | WebSocket via QR code (linked device) |
+
+## Reply-only posture
+
+The agent has **no tool to initiate a WhatsApp message to an arbitrary number.** The `whatsapp-send` and `whatsapp-send-document` MCP tools were removed after an agent-initiated cold first-contact send (to a number with no prior conversation) tripped WhatsApp's anti-automation guard and restricted the operator's account. Initiating is intentionally unavailable, not merely gated — a soft approval gate already existed and did not prevent the incident.
+
+What the agent **can** still do: reply within an existing chat. On a native admin channel session the whatsapp-channel server (`platform/services/whatsapp-channel/`) exposes two reply tools, both reply-only: `reply` (text) and `reply-document` (one or more files delivered as WhatsApp documents). `reply-document` POSTs to `POST /wa-channel/reply-document` → `sendWhatsAppDocument`, the one send core that owns path validation, the 100 MB ceiling, the canonical log, and per-file reconciliation. A bare `SendUserFile` is also caught and delivered through the same core by a read-only JSONL follower on the session, so an attachment reaches the sender even if the agent skips the explicit tool. File delivery is refused for a sender with no live conversation — same reply-only posture as text. (The removed `whatsapp-send-document` route tool and the bridge path `SendUserFile` → `file-delivery-bridge.ts` → `POST /api/whatsapp/send-document` are the legacy webchat/email bridge surface, not the native WhatsApp channel.) Replying within your chats is what WhatsApp permits; starting new chats from a linked device is what it penalises.
+
+## Observation-only in groups
+
+The agent **never responds in a group chat.** Every inbound group message is stored, recorded, and persisted to the graph (observation is fully preserved — `list-groups`, `whatsapp-group-info`, conversations, and the `/whatsapp` reader all still work), but it is never dispatched to a responding session and never produces an outbound message into the group. `checkGroupAccess` is a structural observe-only deny — there is no group policy, allowlist, per-group activation, or @mention setting to turn responses on. A belt invariant in the manager's `reply` closure refuses any `@g.us` recipient (`op=group-reply-blocked`).
+
+This is the same Meta-policy constraint as the reply-only DM posture above, applied one step further. Replying into a group from an unofficial linked device is automated business-style messaging — the class of behaviour that restricted a live operator account. It is a **Meta-policy constraint, not a SiteDesk limitation.**
+
+For agent-driven messaging in groups or initiating conversations, **Telegram is the better channel** — it has no equivalent linked-device automation penalty, so the agent can send and respond freely there. See `platform/plugins/telegram/references/setup-guide.md`.
+
+## Primary Architecture: Multi-Account Baileys
+
+Users link one or more WhatsApp numbers via QR. Each account is an independent Baileys connection with its own credentials, policies, and agent routing. Multiple accounts are optional — most setups use a single account.
+
+WhatsApp Business **app** vs personal WhatsApp is irrelevant from the platform's perspective — Baileys connects to both identically via QR. The Business app just adds business profile, catalog, and labels in the phone UI.
+
+**Linked device note:** The primary phone must come online periodically (~every 14 days) to keep the Baileys linked-device session alive. It does NOT need to be on 24/7.
+
+## Managing Accounts via UI
+
+The Setup page (`/setup`) supports multi-account management in its status dashboard (shown after initial setup is complete):
+
+- **Add Account:** Click "+ Add WhatsApp Account" below the status dashboard, enter a name (e.g. "Business"), and scan the QR code to link
+- **Relink:** Each account has its own relink button (rotate icon) that shows a per-account QR code inline
+- **Remove:** Each account (except the last one) has a remove button (X icon) that disconnects and removes the account from config
+- **Per-account QR:** QR codes appear inline under the specific account being linked
+
+The initial first-run wizard flow stays single-account. Multi-account is managed from the status dashboard that appears once setup is complete.
+
+## Multi-Account Config Example
+
+```yaml
+channels:
+  whatsapp:
+    adminPhones:
+      - "<admin-phone>"    # E.164 phone the user messages from
+    accounts:
+      default:
+        provider: baileys
+        name: "Main"
+```
+
+Accounts are linked via QR in the Channels UI. Outbound routing (`src/web/outbound-routing.ts`) selects the right account automatically:
+
+| Target | Account | Reason |
+|--------|---------|--------|
+| Admin phones | Account with admin binding | Admin's registered number |
+| Self-chat | Account with selfChatMode | Admin talking to themselves |
+| Customer DMs | Account with open DM policy | Dedicated agent number |
+| Inbound replies | Same account that received | Closures capture the right provider |
+
+## Baileys Risk Profile
+
+Baileys uses the same WebSocket protocol as WhatsApp Web/Desktop linked devices. Meta cannot blanket-block it without breaking their own official clients for hundreds of millions of users.
+
+**Responsibility model:** The platform and its other users are not at risk — bans are per-number, targeting individual accounts for abusive behaviour. Users should be told: *"Don't use this for bulk messaging or spam. Meta may ban your number for abusive patterns. Normal business conversations are fine."*
+
+- Normal conversational use (replies, scheduling, quotes) = effectively zero risk
+- Ack reactions, typing indicators, and reply delays mimic real linked-device behaviour
+- Risk increases only with spam patterns: mass messaging, rapid-fire sends to unknown contacts, broadcasting
+- If a user's number is banned, it's between them and Meta — other users are unaffected
+
+## WhatsApp Outbound Policy — No Automated Broadcasts
+
+**WhatsApp's Terms of Service explicitly prohibit automated bulk/broadcast messaging.** Violations result in permanent number bans with no appeal.
+
+The platform enforces this at multiple levels:
+
+1. **Broadcast action blocked** — The `message broadcast` action (which sends to multiple targets) always excludes WhatsApp as a target channel, regardless of config. This is a hard block that cannot be overridden.
+2. **Agent tool suppression** — When an agent session is on WhatsApp, the `broadcast` action is removed from the message tool schema entirely. Agents cannot invoke it.
+3. **Broadcast disabled by default** — `tools.message.broadcast.enabled` defaults to `false`. Even when enabled for other channels (Discord, Telegram, Slack), WhatsApp remains blocked.
+
+**What IS allowed on WhatsApp:**
+- Replying to incoming messages (the core use case)
+- Sending messages to a single known contact via the `send` action
+- Heartbeat/scheduled messages to the admin's own number
+- Owner outbound mirroring (detecting manual WhatsApp Web sends)
+
+**What is NOT allowed:**
+- Sending the same message to multiple WhatsApp contacts in a loop
+- Any form of automated outreach to contacts who have not messaged first
+- Using the broadcast action with WhatsApp as a target channel
+- Building "campaign" or "blast" workflows that target WhatsApp contacts
+
+## DM Policy & Access Control
+
+**Precise definitions — these terms are NOT interchangeable:**
+
+| Term | Definition | Code |
+|------|-----------|------|
+| **Self phone** | The WhatsApp account's own phone number (the phone that scanned the QR code). Self-chat only. | `phonesMatch(senderPhone, selfPhone)` in `access-control.ts` |
+| **Admin phones** | Phones listed in `adminPhones` in `account.json`. The user's personal phone is auto-registered on QR link; additional phones are added via `whatsapp-config action: "add-admin-phone"`. | `isAdminPhone()` in `access-control.ts` — iterates `adminPhones` |
+| **Public/unknown** | Any phone that is not self and not in `adminPhones`. Subject to DM policy gating. | Everything else in `checkDmAccess()` |
+
+**Critical distinction:** The *self phone* is the paired device's number (the WhatsApp account SiteDesk controls). The *admin phone* is the user's personal phone (the phone they message *from*). These are typically different numbers. If the user's personal phone is not in `adminPhones`, their messages route as public — not admin.
+
+**`dmPolicy` behaviour (per-account):**
+
+| Policy | Self phone | Admin phones (in `adminPhones`) | Public/unknown |
+|--------|-----------|-------------------------------|----------------|
+| `"open"` | Allowed | Allowed | Allowed |
+| `"allowlist"` | Allowed | Allowed | Allowed only if in `allowFrom` (wildcard `"*"` counts) |
+| `"disabled"` | Allowed | Allowed | **Blocked** |
+
+Admin phones always bypass DM policy — the `isAdminPhone()` check runs before any policy-specific logic. Self phone is always allowed regardless of policy.
+
+**Schema constraint:** `dmPolicy: "open"` requires `allowFrom` to include `"*"` (enforced by Zod validation).
+
+**Key file:** `access-control.ts` — `checkDmAccess()` gates DMs by the policy above; `checkGroupAccess()` is a structural observe-only deny (always `allowed:false reason:group-observe-only`) — no group policy is consulted.
+
+**Config path:** Per-account at `whatsapp.accounts.{accountId}.dmPolicy` in `account.json`. Falls back to `whatsapp.dmPolicy`. Changes are conversational — the admin agent writes to config via `whatsapp-config action: "update-config"`.
+
+For config field definitions (field names, types, valid values), use `whatsapp-config action: schema`.
+
+## Owner Outbound Mirroring
+
+When the business owner sends a WhatsApp message directly via WhatsApp Web (not through the agent), Baileys detects the echo with `key.fromMe = true`. The inbound monitor (`src/web/inbound/monitor.ts`) checks `access.isOwnerOutbound` and calls `mirrorOwnerReplyToSession()`, which writes a `[Owner reply] {body}` delivery-mirror into the public agent's session transcript via `appendAssistantMessageToSessionTranscript`. This ensures the public agent knows about the owner's direct intervention when the customer next replies.
+
+The same path is used when an **admin agent** sends to a customer via the `message` tool (cross-agent echo): `fireCrossAgentEcho` in `src/infra/outbound/cross-agent-echo.ts` resolves the public agent's session key and delegates to `mirrorOwnerReplyToSession`. For established sessions the mirror is written to disk immediately; for first-contact customers with no session yet, an ephemeral system event is queued instead.
+
+### Agent-sent echo suppression
+
+Every outbound Baileys message echoes back as a `fromMe` `messages.upsert` event. To prevent the monitor from treating agent-sent echoes as manual owner messages, all send paths must track message IDs via `trackAgentSentMessage(id)` in `src/web/inbound/dedupe.ts`. The monitor then checks `isAgentSentMessage(id)` before calling `mirrorOwnerReplyToSession`.
+
+There are two send paths — both must track IDs:
+- **IPC send API** (`src/web/inbound/send-api.ts`): used by the message tool, gateway RPC, and `sendPoll`. Tracks IDs after `sock.sendMessage`.
+- **Auto-reply closures** (`monitor.ts` lines 390-401): the `reply()` and `sendMedia()` functions on `WebInboundMessage`, used by `deliverWebReply`. Track IDs after `sock.sendMessage`.
+
+The dedupe cache (`agentSentMessages`) has a 2-minute TTL and 500-entry cap, which is sufficient because Baileys echoes arrive within seconds.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `src/web/inbound/monitor.ts` | Detects `fromMe` echoes, calls `mirrorOwnerReplyToSession`; auto-reply `reply`/`sendMedia` closures |
+| `src/web/inbound/owner-mirror.ts` | `mirrorOwnerReplyToSession()` — canonical implementation |
+| `src/web/inbound/access-control.ts` | `isOwnerOutbound` flag for `fromMe` DMs |
+| `src/web/inbound/send-api.ts` | IPC send path — tracks agent-sent message IDs |
+| `src/web/inbound/dedupe.ts` | `trackAgentSentMessage` / `isAgentSentMessage` — echo suppression cache |
+| `src/infra/outbound/cross-agent-echo.ts` | Adapter: agent tool → `mirrorOwnerReplyToSession` |
+
+## Self-chat command lane
+
+The companion-device link means the operator's paired phone cannot DM the agent — a message typed from the paired number arrives as `fromMe=true` with upsert type `append`, which the manager's append branch historically dropped before dispatch. The operator's **self-chat** (the message-yourself thread, `remoteJid` == the account's own jid/lid) is the exception: the agent never writes there first, so it is an unambiguous admin command surface.
+
+The discriminator lives in `platform/ui/app/lib/whatsapp/inbound/self-chat.ts` (`evaluateSelfChatCommand`) and dispatches only when **all** of:
+
+1. `msg.key.fromMe === true`;
+2. `remoteJid` is the self surface — `selfJid`, `selfLid`, or `${selfPhone}@s.whatsapp.net`, with device suffixes (`447…:12@s.whatsapp.net`) normalised before comparison;
+3. the message id is not in the agent-sent cache (`isAgentSentMessage`) — suppresses the agent's own self-chat reply echoes within the 2-minute TTL;
+4. the message timestamp (Unix seconds, normalised to ms) is **strictly after** `conn.lastConnectedAt` — excludes history backfill replayed on reconnect, and is the restart-safe backstop when the in-memory echo cache has expired or been cleared;
+5. it is not an in-session duplicate (`isDuplicateInbound`);
+6. it has non-empty extracted text.
+
+A match dispatches via `buildSelfChatDispatch` (`manager.ts`): `agentType: "admin"`, raw command text (no `[Owner reply]` prefix), `senderPhone = selfPhone`, the admin cacheKey (`whatsapp:<accountId>`), `reply`/`composing` closures bound to the self jid so the agent's answer returns to the self-chat, and **no `isOwnerMirror` flag** — the inbound route drops owner-mirror payloads before the gateway, and a self-chat message is a command expecting a reply, not a mirror. The reply goes out through `sendTextMessage`, which tracks the id for clause-3 echo suppression.
+
+`fromMe` in any **non-self** thread is unchanged: it remains the `[Owner reply]` mirror described above, never a command.
+
+**Log grammar** (one decision lineage per self-chat message, greppable by `msgId=`):
+
+```
+[whatsapp:self-chat] op=seen account=… msgId=… tsMs=… connAtMs=… fromMe=true
+[whatsapp:self-chat] op=skip account=… msgId=… reason=echo|backfill|duplicate|no-text
+[whatsapp:self-chat] op=dispatch account=… msgId=… bytes=… agentType=admin
+```
+
+Failure signatures: an `op=dispatch` whose `tsMs ≤ connAtMs` (backfill wrongly dispatched — must never appear; the `op=seen` line carries both fields so this is checkable per message); back-to-back `op=dispatch` with no operator-originated message between (self-reply loop); a self-chat message the operator confirms sending with no `op=seen` at all (silent drop upstream of the discriminator).
+
+## Offline Message Recovery
+
+Baileys is a WhatsApp Web protocol client. When the gateway is offline, WhatsApp's servers hold incoming messages and push them back as history (`append`-type `messages.upsert` events) when Baileys reconnects — so the system self-recovers automatically on restart. These replayed messages are stored in the UI message cache and marked as read, but **not** dispatched to the agent (no auto-reply on catch-up). The self-chat command lane (above) does not weaken this: replayed history fails its strictly-after-`lastConnectedAt` timestamp clause and skips with `reason=backfill`. The recovery window is determined entirely by WhatsApp's server-side delivery queue (approximately 30 days); `syncFullHistory: false` only prevents requesting full chat history on first pairing and does not restrict this window.
+
+## Voice Notes
+
+### Inbound (transcription)
+
+Inbound voice notes are transcribed to text before reaching the agent. The pipeline runs in `manager.ts` after `downloadInboundMedia` succeeds for audio messages:
+
+1. **ffmpeg** converts OGG Opus → WAV (16 kHz, mono, PCM s16le)
+2. **whisper.cpp** (`/opt/whisper.cpp/build/bin/whisper-cli` with `ggml-base` model) transcribes WAV → raw text
+
+The raw whisper transcript is set on `extracted.text` so both agent paths receive identical content. On any failure, the pipeline degrades silently — the agent sees the standard media placeholder instead of transcribed text.
+
+**Source:** `platform/ui/app/lib/stt/index.ts` (transcription)
+
+**Log tag:** `[stt]`
+
+### Outbound (PTT)
+
+Outbound TTS audio is sent as native WhatsApp PTT (Push-To-Talk) voice notes. The pipeline:
+
+1. **TTS output format:** `resolveOutputFormat("whatsapp")` returns Opus (OGG container) instead of MP3 (`src/tts/tts.ts`)
+2. **ffmpeg normalization:** `normalizePttAudio()` re-encodes to WhatsApp-native format — OGG Opus, 48 kHz, mono, 64 kbps, VoIP mode (`src/media/ptt-normalize.ts`)
+3. **Baileys metadata:** `music-metadata` and `audio-decode` npm packages compute `seconds` (duration) and `waveform` fields for the PTT message. Without these, WhatsApp renders audio as a generic file attachment.
+4. **Send:** `ptt: true` flag on the audio message, no caption (voice IS the content)
+
+**System dependency:** ffmpeg must be on PATH. Installed automatically by `install.sh` (fresh) and `postinstall.js` (upgrades). Best-effort — if ffmpeg is unavailable, the original audio is sent as-is.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `src/media/ptt-normalize.ts` | ffmpeg re-encoding to WhatsApp-native OGG Opus |
+| `src/web/auto-reply/deliver-reply.ts` | Auto-reply path (calls normalizePttAudio for audio) |
+| `src/web/inbound/send-api.ts` | Baileys send wrapper (sets `ptt: true`) |
+| `src/tts/tts.ts` | TTS output format resolution (Opus for WhatsApp) |
+
+## Session Credentials (Baileys Auth)
+
+Baileys stores WhatsApp session credentials (linked-device state) on disk. The auth directory contains `creds.json` (session keys) and Signal protocol pre-keys.
+
+**Path resolution** (`src/web/accounts.ts` → `resolveWhatsAppAuthDir`):
+
+| Priority | Path | When |
+|----------|------|------|
+| 1. Explicit config | `channels.whatsapp.accounts.{id}.authDir` | User overrides in config |
+| 2. Default | `~/.maxy/credentials/whatsapp/{accountId}/` | Normal operation |
+
+**Diagnostics on the Pi:**
+
+```bash
+# List all WhatsApp auth directories
+ls -la ~/.maxy/credentials/whatsapp/
+
+# Check if credentials exist for an account
+ls ~/.maxy/credentials/whatsapp/default/creds.json
+
+# Check credential freshness (should be recent if just linked)
+stat ~/.maxy/credentials/whatsapp/default/creds.json
+```
+
+If `creds.json` is missing, the session was never linked or was deleted. If it exists but WhatsApp rejects it (401), the session was invalidated (cleared from phone, expired after 14 days offline, or account banned).
+
+**Key files:** `src/web/accounts.ts` (resolveWhatsAppAuthDir), `src/config/paths.ts` (resolveOAuthDir, resolveStateDir), `src/web/session.ts` (enqueueSaveCreds — writes creds on update).
+
+## Disconnect Reasons
+
+Baileys disconnect errors carry a numeric status code mapped to `DisconnectReason`. The monitor translates these to user-facing messages via `humanizeWhatsAppError()` in `src/web/auto-reply/monitor.ts`.
+
+| Status | Baileys Reason | Meaning | Auto-reconnect? |
+|--------|---------------|---------|-----------------|
+| 401 | loggedOut | Session removed from phone or expired | No — re-link required |
+| 401 + "conflict" | connectionReplaced (server override) | Another WhatsApp Web session took over | Yes |
+| 403 | forbidden | Number banned or restricted | No |
+| 408 | connectionLost / timedOut | Network interruption or timeout | Yes |
+| 428 | connectionClosed | Server closed the connection | Yes |
+| 440 | connectionReplaced | Another session replaced this one | Yes |
+| 500 | badSession | Corrupted session data | No — re-link required |
+| 515 | restartRequired | Server requests reconnection | Yes |
+
+**Conflict vs logout (401 ambiguity):** WhatsApp's server can send a stream error with code 401 and reason "conflict" — Baileys normally maps "conflict" to 440, but the server's explicit `code` attribute overrides the mapping. The monitor checks for "conflict" in the error message to distinguish this from a true logout.
+
+## Terminal Logout: Visibility and Remedy
+
+A `loggedOut` (401, `device_removed`) or a `conflict` (login taken over elsewhere) is **terminal**: the manager stops reconnecting (`classifyDisconnect` returns `shouldRetry: false`) and the link will NOT come back on its own. The cause is a WhatsApp-account-side action — the phone unlinked the device, or another login replaced this one — not something the gateway can recover from. The only remedy is re-pairing (the connect-whatsapp skill); waiting does nothing.
+
+The dead state is reported at two surfaces so it is visible without a reply having to fail first:
+
+- **Standing health signal.** On a terminal disconnect the manager sets `terminalReason` on the account connection (distinct from `sessionStuckReason`, which is the fast-reconnect-churn give-up). `/api/health` reports `whatsapp.any_terminal = true` and the account's `terminalReason`; `whatsapp-status` shows the account Disconnected with the reason (`Session logged out — re-link required`). `terminalReason` clears automatically once a re-pair establishes a fresh connection.
+- **Reply failures are correctly described.** The native-channel `reply` tool no longer returns a bare `gateway returned 500`. On a terminal link it returns `reply: WhatsApp logged out — re-link required` (the agent must NOT promise an automatic recovery — there is none until re-pairing); a transient blip during reconnection stays a retryable `reply: WhatsApp disconnected — cannot reply`. The gateway carries the distinction as a `terminal` boolean in the `/wa-channel/reply` failure body, and the `op=reply-failed` log line records `terminal=true|false`.
+
+What is NOT handled here: the end user who triggered the reply receives no delivery-failure notice over WhatsApp, and there is no outbound retry queue — a dropped reply on a dead link is lost (the agent is made aware of the failure, but the sender is not). That is a separate concern; file a task if it is wanted.
+
+## Reconnection: Setup Failures vs Runtime Disconnects
+
+> **Authoritative source:** The current runtime connection lifecycle — including reconnect bounding (`STABLE_UPTIME_MS`, `MAX_RECONNECT_ATTEMPTS`), platform-side init queries (fetchBlocklist, fetchPrivacySettings, intentional fetchProps skip), and the `/api/health` WhatsApp field — is documented in [`.docs/whatsapp.md`](../../../../.docs/whatsapp.md) under "Connection Lifecycle", "Init Query Visibility", and "Reconnect Bounding and Escape". The content below describes the historical disconnect-reason mapping which still applies; for anything about how the loop retries, aborts, or runs its init sequence, read the `.docs` file first.
+
+The reconnection loop in `monitorWebChannel` handles two distinct failure modes:
+
+| Failure Mode | When | Example | Handling |
+|-------------|------|---------|----------|
+| **Runtime disconnect** | After a successful connection drops | 408 (connectionLost), 428 (connectionClosed) | `listener.onClose` resolves → backoff retry |
+| **Setup failure** | Connection never establishes | 405 (Method Not Allowed), 503 (service unavailable) | `monitorWebInbox` throws → caught by try-catch → same backoff retry |
+
+Both paths use the same backoff policy (2s → 30s, 12 max attempts) and the same loggedOut detection. A 401 status only triggers logout if the error message does NOT contain "conflict" (see Disconnect Reasons above). Setup failures log as `"web reconnect: connection setup failed"` instead of `"web reconnect: connection closed"`.
+
+Without the setup-failure handling, a transient WhatsApp server rejection (e.g., 405 during a protocol update) would kill the channel permanently — the error would escape the reconnection loop, and only a gateway restart could recover.
+
+## Provider Architecture
+
+```
+src/web/
+├── outbound-routing.ts  # Multi-account outbound routing logic
+├── active-listener.ts   # Per-account listener registry (listActiveWebAccountIds, etc.)
+├── outbound.ts          # Outbound send (routes through outbound-routing)
+├── providers/
+│   ├── types.ts         # WhatsAppProvider interface
+│   ├── factory.ts       # createWhatsAppProvider()
+│   └── baileys/         # BaileysProvider (wraps monitorWebInbox)
+└── auto-reply/
+    ├── monitor.ts       # Baileys reconnection loop (monitorWebChannel)
+    └── monitor/
+        └── on-message.ts # Message handler
+
+extensions/whatsapp/src/
+└── channel.ts           # Channel plugin
+```

package/payload/platform/plugins/whatsapp/skills/connect-whatsapp/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: connect-whatsapp
+description: Guide the user through connecting WhatsApp via a typed pairing code, registering admin phones, and selecting the public agent. Complete setup — not just pairing.
+---
+
+# Connect WhatsApp
+
+Invoked from `specialists:personal-assistant`.
+
+Conversational flow for linking a WhatsApp account to {{productName}} via a typed WhatsApp pairing code, followed by admin phone registration and public agent selection. All three phases are required for a correctly configured WhatsApp channel.
+
+## When to activate
+
+User says anything about connecting, linking, setting up, or adding WhatsApp.
+
+## Prerequisites
+
+Call `whatsapp-status` first to check the current state. If already connected, tell the user and offer to relink. If connected but admin phones or public agent are not configured, proceed to the relevant post-pairing step.
+
+## Flow
+
+### Phase 1: Pairing Code
+
+1. **Get the WhatsApp number** — ask the operator for the phone number of the WhatsApp account being linked, in international format (e.g. +44 7700 900123). You need it before starting.
+
+2. **Initiate pairing** — call `whatsapp-login-start` with `phone` set to that number. If the account is already linked and the user didn't say "relink", inform them and skip to Phase 2.
+
+3. **Give the operator the code** — the tool returns an 8-character pairing code. Show it and tell the user: "On the phone with that number, open WhatsApp → Settings → Linked Devices → Link a Device → tap 'Link with phone number instead', then enter this code: {code}."
+
+4. **Wait for the link** — call `whatsapp-login-wait`. It polls for up to 60 seconds. The code stays valid and the connection stays alive across polls, so if it returns still-waiting, call it again — do not generate a new code unless the operator asks. While waiting, tell the user you're watching for the link.
+
+5. **Confirm connection** — when pairing completes, the tool returns the linked phone number (the *self phone* — the WhatsApp account {{productName}} now controls). The platform persists the WhatsApp config in `account.json` and registers this phone as an admin phone automatically, driven by the connection event (so it lands even when the link finishes after a restart, not only while you are polling). Confirm: "WhatsApp connected as {phone}. Your phone is registered as admin."
+
+6. **Verify** — call `whatsapp-status` and confirm the linked phone shows as Connected. If status reports "Linked but config was missing — repaired automatically," that is the self-heal: call `whatsapp-status` once more to confirm it now shows Connected. It must never report "No accounts configured" while a phone is linked; if it does, reconnect with `whatsapp-login-start force: true`.
+
+### Phase 2: Additional Admin Phones
+
+The self phone from Phase 1 is automatically registered as an admin phone. If the user has additional phones that should also have admin access (e.g. a partner, co-owner, or second device), register them here.
+
+1. **Offer additional admin phones** — "Would you like to add any other phone numbers as admin? For example, a partner or co-owner who should also have admin access."
+
+2. **Register additional phones** — For each phone the user provides, call `whatsapp-config` with `action: "add-admin-phone"` and `phone: "{E.164 number}"`. The tool validates the format and adds it to the admin list.
+
+3. **Confirm** — "Added {number} as admin. Messages from this number will route to the admin agent." Use `whatsapp-config` with `action: "list-admin-phones"` to show the complete list.
+
+4. **Skip if not needed** — If the user declines, proceed to Phase 3. The self phone is already registered.
+
+### Phase 3: Public Agent Selection
+
+WhatsApp inbound from non-admin phones routes only for **authenticated-public** senders: the sender must be allowed by the DM policy **and** resolve to an enrolled `:Person` (their phone is on a Person record for this account). An allowed-but-unenrolled sender is dropped with `[whatsapp:route] op=dropped reason=public-unresolved`. Each routed sender gets their own per-person, reply-only session. The public-agent setting below is the WhatsApp config's designated public agent; it does not change how an authenticated-public sender is routed.
+
+1. **Check current state** — Call `whatsapp-config` with `action: "get-public-agent"` to see if one is already set. Also call `account-manage` to list the available public agents.
+
+2. **Ask which agent should handle WhatsApp** — "Which of your public agents should respond to WhatsApp messages from customers?"
+
+3. **Set the public agent** — Call `whatsapp-config` with `action: "set-public-agent"` and `slug: "{chosen-slug}"`.
+
+4. **Set the DM policy** — Call `whatsapp-config` with `action: "update-config"`, `dmPolicy: "allowlist"`, and the enrolled customers' phones in `allowFrom`. Without a policy that allows the sender, all non-admin messages are silently dropped regardless of which public agent is configured. Even an allowed sender only routes once enrolled as a `:Person` carrying that phone.
+
+5. **Confirm** — "Enrolled customers on the allowlist will get their own WhatsApp conversation with the agent."
+
+If only one public agent exists, confirm it as the choice rather than asking. If no public agents exist, the public-agent setting can be skipped — it does not gate authenticated-public routing.
+
+## Relinking
+
+If the user says "relink WhatsApp" or the status shows disconnected with a 401 error:
+1. Call `whatsapp-login-start` with `force: true` and the WhatsApp `phone` to clear old credentials and issue a fresh pairing code
+2. Follow the same flow from Phase 1
+
+Admin phone registration and public agent selection persist across relinks — no need to repeat Phases 2-3 unless the user wants to change them.
+
+## Troubleshooting
+
+- **Code expired** — generate a new one with `whatsapp-login-start` (with the `phone`)
+- **Code not accepted** — ensure the phone has internet, WhatsApp is updated, and the operator used "Link with phone number instead" (not the camera scanner)
+- **Keeps disconnecting** — check `whatsapp-status` for error details. A 401 means re-link is needed. Repeated transient errors suggest network issues on the device.
+- **Messages routing as public** — the user's personal phone is not in `adminPhones`. Call `whatsapp-config` with `action: "add-admin-phone"` and the user's phone number to register it.
+
+## Language
+
+Use plain English:
+- "pairing code" not "Baileys pairing token"
+- "Link your phone with a code" not "initiate WebSocket connection"
+- "WhatsApp is connected" not "Baileys socket is open"
+- "admin phone" not "allowFrom entry"
+- "public agent" not "defaultAgent slug"

package/payload/platform/plugins/whatsapp/skills/manage-whatsapp-config/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: manage-whatsapp-config
+description: Guide the user through viewing and editing WhatsApp settings — DM messaging policy, operational limits, and acknowledgement behaviour. Conversational, not a raw form dump.
+---
+
+# Manage WhatsApp Config
+
+Invoked from `specialists:personal-assistant`.
+
+Conversational editing of WhatsApp settings. Every field is presented with its description, current value, and what the default means — the user makes informed decisions without needing backend knowledge.
+
+## When to activate
+
+User asks to change, view, edit, or manage WhatsApp settings, policies, or limits. Also activate when the user asks about read receipts, message batching, media limits, or the DM policy. If the user asks how to make the agent respond in a group, see "Group posture" below — the answer is that it cannot, by design.
+
+## Prerequisites
+
+Call `whatsapp-status` first — if no WhatsApp account is connected, direct the user to the connect-whatsapp skill instead.
+
+## Presenting settings
+
+Call `whatsapp-config action: schema` to get field definitions with descriptions, and `whatsapp-config action: get-config` to get current values. Use the Description column from the schema output as the `description` field on each form field — do not improvise descriptions.
+
+### Form fields
+
+Present the settings to the operator as a numbered checklist in plain chat. For each field show the schema name, its label, the current value (from `get-config`) or the schema default, and the description from the schema output. For selects, list the available options. The operator replies with the changes they want, and the agent applies them via `whatsapp-config action: update-config`.
+
+**Admin phones:**
+
+Call `whatsapp-config action: list-admin-phones` and present the current list. Ask the operator which phones to add (`+44…` format) and which to remove. Apply each change via `whatsapp-config action: add-admin-phone` / `remove-admin-phone`. Confirm the resulting list to the operator after the writes land.
+
+Each add/remove fires immediately — admin phones are managed per-action, independent of the form's batch submit.
+
+**Public agent:**
+
+Call `whatsapp-config action: list-public-agents` to get available agents, and `whatsapp-config action: get-public-agent` to get the current selection.
+
+- `publicAgent` (`select`): label "Public agent for WhatsApp"
+  - Options: one per agent from `list-public-agents` response — `value: slug`, `label: displayName`
+  - `defaultValue`: the slug returned by `get-public-agent` (current selection)
+  - `description`: from the schema's `.describe()` metadata for the `publicAgent` field
+  - If `list-public-agents` returns an empty array, still include the field with no options and `description`: "No public agents available. Create one first using the public agent manager."
+
+**Messaging policies:**
+
+- `dmPolicy` (`select`): label "Who can message your agent (DMs)", options:
+  - `open` — "Open — anyone can message"
+  - `allowlist` — "Allowlist — only approved numbers"
+  - `disabled` — "Disabled — no public DMs"
+
+There is no group policy. Groups are observation-only — see "Group posture" below.
+
+**Behaviour:**
+
+- `sendReadReceipts` (`select`): label "Blue ticks (read receipts)", options:
+  - `true` — "On — contacts see read receipts"
+  - `false` — "Off — no read receipts"
+
+**Operational limits:**
+
+- `mediaMaxMb` (`number`): label "Media size limit (MB)"
+- `textChunkLimit` (`number`): label "Message chunk limit (characters)"
+- `debounceMs` (`number`): label "Message batching delay (ms)", defaultValue `2000`
+
+### Submit
+
+The form's `submitMessage` must map the field values back to `update-config` field names: `Save these WhatsApp settings: {{json}}` — where `{{json}}` produces the JSON object with field names as keys (e.g. `{ "dmPolicy": "open", "mediaMaxMb": 50, ... }`).
+
+## Group posture
+
+The agent is **observation-only in groups**: it sees and records every group message but never replies in a group. There is no per-group setting to turn responses on — the restriction is structural, not a toggle. `whatsapp-config action: list-groups` still lists the groups the connected phone is in, for reference.
+
+This is a **Meta-policy constraint, not a SiteDesk limitation.** WhatsApp penalises automated and business-style messaging sent from an unofficial linked device. Replying in groups and sending cold first-contact messages are both anti-automation triggers — they restricted a live operator account, which is why the agent is observe-only in groups and reply-only in DMs.
+
+If the user wants an agent that actively messages in groups or initiates conversations, recommend **Telegram** instead. Telegram has no equivalent linked-device automation penalty, so the agent can send and respond freely there. Point them to the Telegram setup path at `platform/plugins/telegram/references/setup-guide.md`.
+
+## Writing changes
+
+After the user submits, write changes via `whatsapp-config action: "update-config"` with the `fields` parameter containing a JSON object of the changed fields. Each field is merged individually — unchanged fields are left untouched. Confirm what changed — name each setting that was modified and its new value.
+
+## Language
+
+Plain English goes in `label` — schema field names go in `name`. The `name` property is the machine key (must match the schema exactly); the `label` is what the user reads. Examples:
+
+- `name: "dmPolicy"`, `label: "Who can message your agent (DMs)"`
+- `name: "debounceMs"`, `label: "Message batching delay (ms)"`
+- `name: "mediaMaxMb"`, `label: "Media size limit (MB)"`
+- `name: "sendReadReceipts"`, `label: "Blue ticks (read receipts)"`
+
+Group names (not JIDs) in all user-facing text.

package/payload/platform/plugins/work/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "work",
+  "description": "Graph-backed work-item lifecycle management. Task nodes in Neo4j with dependency tracking (BLOCKS), conflict detection (AFFECTS), and a parallel safety query (work-ready). Surfaced by memory-search.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "work": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "work"
+      }
+    }
+  }
+}

package/payload/platform/plugins/work/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "work": {
+      "command": "node",
+      "args": ["~/maxy/platform/plugins/work/mcp/dist/index.js"],
+      "env": {
+        "ACCOUNT_ID": "${ACCOUNT_ID}",
+        "PLATFORM_ROOT": "${PLATFORM_ROOT}",
+        "SESSION_ID": "${SESSION_ID}"
+      }
+    }
+  }
+}