wazap-mcp 0.9.3 → 0.9.6

package/README.md

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 22 tools any MCP client can
+chats, messages, media, contacts, groups — behind 23 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -25,6 +25,23 @@ npx wazap-mcp setup
 That is the whole install. It links your account, finds the MCP clients
 installed on this machine, writes their config and tells you what to restart.
 
+### Or the path your harness prefers
+
+| Harness | Fastest path |
+| --- | --- |
+| Claude Code | `/plugin marketplace add razvangirgiz/wazap`, then `/plugin install wazap@wazap` |
+| Claude Desktop | download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases) and double-click it |
+| Gemini CLI | `gemini extensions install https://github.com/razvangirgiz/wazap` |
+| Cursor | the [Install in Cursor](#other-mcp-clients) badge, then `npx wazap-mcp skills install cursor` |
+| VS Code | the [Install in VS Code](#other-mcp-clients) badge |
+| Codex CLI | `npx wazap-mcp connect codex`, then `npx wazap-mcp skills install codex` |
+| OpenCode | `npx wazap-mcp connect opencode`, then `npx wazap-mcp skills install opencode` |
+| Windsurf | `npx wazap-mcp connect windsurf` |
+| Anything else | the MCP entry `npx -y wazap-mcp` over stdio, or a [self-hosted](#self-host) URL |
+
+Each of those registers the server. Linking the WhatsApp account is a separate,
+one-time step in every one of them: `npx wazap-mcp login`.
+
 Or have your agent do it. Paste this:
 
 *Set up WhatsApp for me: run `npx wazap-mcp setup --agent` and follow what it prints.*
@@ -63,11 +80,25 @@ it would write.
 | `codex` | `[mcp_servers.whatsapp]` in `~/.codex/config.toml` |
 | `vscode` | `./.vscode/mcp.json`, for the current workspace |
 | `gemini` | `~/.gemini/settings.json` |
+| `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
+| `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
 | anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>` (see [Self-host](#self-host)) |
 
-Any MCP client works the same way: the command is `npx -y wazap-mcp`, the transport
-is stdio. Tell the agent to call `learn` first — it returns the id formats, the
-workflows and every error code with what to do about it.
+### Other MCP clients
+
+Cursor and VS Code install from a link:
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=whatsapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIndhemFwLW1jcCJdfQ)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22whatsapp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D)
+
+Both carry the same entry `connect` writes. Where a custom scheme is stripped
+before you can click it, VS Code also takes
+[the https form](https://insiders.vscode.dev/redirect/mcp/install?name=whatsapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D).
+`node scripts/badges.mjs` reprints all three.
+
+Any other MCP client works the same way: the command is `npx -y wazap-mcp`, the
+transport is stdio. Tell the agent to call `learn` first — it returns the id
+formats, the workflows and every error code with what to do about it.
 
 <details>
 <summary>The raw entries, for editing by hand</summary>
@@ -83,8 +114,9 @@ workflows and every error code with what to do about it.
 }
 ```
 
-Claude Desktop, Cursor and Gemini CLI take exactly that. VS Code nests it under
-`servers` and wants a `"type": "stdio"` alongside `command`. Codex CLI is TOML:
+Claude Desktop, Cursor, Gemini CLI and Windsurf take exactly that. VS Code nests
+it under `servers` and wants a `"type": "stdio"` alongside `command`. Codex CLI
+is TOML:
 
 ```toml
 [mcp_servers.whatsapp]
@@ -92,22 +124,68 @@ command = "npx"
 args = ["-y", "wazap-mcp"]
 ```
 
+OpenCode takes the command and its arguments as one array, under `mcp`:
+
+```json
+{
+  "mcp": {
+    "whatsapp": { "type": "local", "command": ["npx", "-y", "wazap-mcp"] }
+  }
+}
+```
+
 </details>
 
 The `skills/` folder follows the [Agent Skills](https://agentskills.io) format, so Codex, Cursor and other skill-aware agents can load the same five skills.
 
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/razvangirgiz/wazap
+```
+
+That reads `gemini-extension.json` at the repo root, so it registers the MCP
+server and loads `GEMINI.md` — the five skills below, concatenated, because the
+Gemini CLI takes one context file per extension rather than a skills directory.
+`wazap connect gemini` writes the server alone, without the context.
+
+`GEMINI.md` is generated: `npm run context:build` rebuilds it from
+`skills/*/SKILL.md`, and a test fails if the two have drifted, so a workflow is
+only ever edited in its skill.
+
+### Claude Desktop, without a terminal
+
+Download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases)
+and double-click it. Claude Desktop installs the server, its Node dependencies
+and the icon, and shows two settings: **Read-only**, ticked, and **Data
+directory**, empty. `wazap connect claude-desktop` does the same job by editing
+`claude_desktop_config.json`, and needs `npx` at launch; the bundle does not.
+
+Linking the account still needs a terminal once: `npx wazap-mcp login`. The
+bundle reads the session that login writes to `~/.wazap`.
+
+Untick **Read-only** to let Claude send. It ships ticked because a bundle that
+can message people from your number before you have said so is the wrong
+default, and because the setting cannot be left unanswered: the manifest format
+has no way to omit an argument, so the box you see is the answer the server gets.
+
+Build it yourself with `npm run bundle:mcpb`, which stages `dist/`, the
+manifest, the icon and a fresh production `node_modules`, then packs them with
+[`@anthropic-ai/mcpb`](https://github.com/modelcontextprotocol/mcpb).
+
 ## Tools
 
 | Tool | Kind | What it does |
 | --- | --- | --- |
 | `learn` | read | The guide to every tool, id format and error code. Call it first. |
-| `get_status` | read | Connection status, sync state, linked account, versions, data dir. |
+| `get_status` | read | Connection status, sync state, linked account, named-contact count, versions, data dir. |
 | `list_chats` | read | Conversations newest-first; filter `all`/`unread`/`groups`/`individual`/`archived`. |
 | `read_messages` | read | Messages in a chat; `before` pages further back, pulling older history from the phone. |
-| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. |
+| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. `include_system` adds WhatsApp's own notices. |
 | `search_messages` | read | Text search across the locally held messages. |
 | `get_message` | read | One message in full, with its quoted message and reactions. |
 | `search_contacts` | read | Find contacts by name or number. |
+| `sync_contacts` | read | Fetch the phone's address book from WhatsApp again, when names are missing. |
 | `get_contact` | read | Name, number, about text, profile picture. |
 | `get_group_info` | read | Participants, admins, announcement mode, invite link (when you are admin). |
 | `download_media` | read | Save an attachment to disk; small images also come back inline. |
@@ -147,7 +225,22 @@ Install everything (server and skills) as a Claude Code plugin:
 /plugin install wazap@wazap
 ```
 
-Or copy `skills/<name>/` into any skills directory your agent reads.
+Every other harness gets them with one command:
+
+```bash
+npx wazap-mcp skills install codex     # or cursor, opencode, agents
+```
+
+| Harness | Where the five directories land |
+| --- | --- |
+| `claude-code` | nowhere — the plugin above already carries them |
+| `codex` | `~/.agents/skills/`, the directory Codex documents for user skills. Cursor and OpenCode read it too |
+| `cursor` | `~/.cursor/skills/` |
+| `opencode` | `~/.config/opencode/skills/` |
+| `agents` | `./.agents/skills/`, in the current project, for anything that reads the cross-tool convention |
+
+Re-running overwrites, so an upgrade is the same command. `--dry-run` lists
+what it would copy.
 
 ## Errors
 
@@ -307,6 +400,10 @@ Flags beat environment variables, which beat `<data-dir>/.env`.
 - **`@lid` ids.** Newer accounts are addressed by a privacy id rather than a
   phone number. wazap translates them back to phone numbers when it has learned
   the mapping, and passes the `@lid` through when it has not.
+- **Names come from the phone's address book.** WhatsApp delivers it as an app
+  state sync, and only to a connection asking for it from scratch. If contacts
+  read as phone numbers and `get_status` shows `contacts_named: 0`, ask for it
+  again with the `sync_contacts` tool or `wazap contacts resync`.
 - **Your phone must stay reachable.** A linked device stops receiving once the
   phone has been offline long enough; `get_status` says so in `hint`.
 

package/dist/auth-state.js

@@ -117,3 +117,28 @@ export function readLinkedAccount(dir) {
 export function clearAuth(dir) {
     rmSync(dir, { recursive: true, force: true });
 }
+const APP_STATE_SYNC_VERSION = "app-state-sync-version";
+/**
+ * The same auth state with the app state sync journal held at zero: reads of it
+ * find nothing and writes to it are dropped, every other key type untouched.
+ *
+ * WhatsApp delivers the phone's address book to a companion as `contactAction`
+ * mutations in the app state sync, once per stored collection version. Whichever
+ * socket saves those versions consumes that one delivery; every later connection
+ * resyncs from the version it left behind and receives nothing. The login socket
+ * has no store to put contacts in, so it must leave the journal for the service
+ * that follows.
+ */
+export function withoutAppStateSync(state) {
+    return {
+        creds: state.creds,
+        keys: {
+            get: async (type, ids) => type === APP_STATE_SYNC_VERSION ? {} : state.keys.get(type, ids),
+            set: async (data) => {
+                const rest = { ...data };
+                delete rest[APP_STATE_SYNC_VERSION];
+                await state.keys.set(rest);
+            },
+        },
+    };
+}

package/dist/cli.js

@@ -5,7 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import makeWASocket, { DisconnectReason, } from "baileys";
 import qrcode from "qrcode";
 import qrcodeTerminal from "qrcode-terminal";
-import { clearAuth, readLinkedAccount, useAtomicAuthState } from "./auth-state.js";
+import { clearAuth, readLinkedAccount, useAtomicAuthState, withoutAppStateSync, } from "./auth-state.js";
 import { banner } from "./banner.js";
 import { runBridge } from "./bridge.js";
 import { BAILEYS_VERSION, WAZAP_VERSION, paths } from "./config.js";
@@ -20,7 +20,7 @@ import { formatAge } from "./messages.js";
 import { RateLimiter } from "./ratelimit.js";
 import { runHttp, runStdio, startLoopbackEndpoint } from "./server.js";
 import { applyWrites } from "./settings.js";
-import { bold, box, brand, humanLayout, dim, fail, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
+import { bold, box, brand, humanLayout, dim, fail, fix, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
 import { WA_BROWSER, WhatsAppService } from "./whatsapp.js";
 const LOGIN_TIMEOUT_MS = 120_000;
 const LIVE_TIMEOUT_MS = 15_000;
@@ -194,6 +194,53 @@ async function runLiveProbe(config) {
         releaseLock(p.lockFile);
     }
 }
+/**
+ * `wazap contacts resync`. One process owns the session, so this refuses while a
+ * server holds it rather than fighting for the socket: that server has the
+ * sync_contacts tool, which does the same thing.
+ */
+export async function runContacts(config) {
+    if (config.args[0] !== "resync") {
+        say(fail(`Unknown contacts command "${config.args[0]}".`));
+        say(fix("Run `wazap contacts resync`"));
+        process.exit(2);
+    }
+    const p = paths(config.dataDir);
+    const running = takeSessionLock(p.lockFile);
+    if (running !== null) {
+        say(fail(`wazap is running (pid ${running}).`));
+        say(fix("ask your agent for the sync_contacts tool, or stop the server and run this again"));
+        process.exit(1);
+    }
+    const wa = new WhatsAppService(config);
+    const spin = spinner("Asking WhatsApp for your address book…");
+    try {
+        await wa.start();
+        const deadline = Date.now() + LIVE_TIMEOUT_MS;
+        let probe = wa.getStatus();
+        while (!SETTLED_STATUSES.includes(probe.status) && Date.now() < deadline) {
+            await sleep(250);
+            probe = wa.getStatus();
+        }
+        const result = await wa.syncContacts();
+        spin.stop(result.named_after > result.named_before
+            ? ok(`${result.named_after} contacts have a name (was ${result.named_before})`)
+            : result.named_after > 0
+                ? ok(`Already up to date: ${result.named_after} contacts have a name`)
+                : warn("WhatsApp sent no names at all. The phone has no saved contacts for these people."));
+    }
+    catch (err) {
+        const failure = asWazapError(err);
+        spin.stop(fail(failure.message));
+        if (failure.fix)
+            say(fix(failure.fix));
+        process.exitCode = 1;
+    }
+    finally {
+        await wa.stop();
+        releaseLock(p.lockFile);
+    }
+}
 /** Bare `wazap` at a terminal: where you stand, and the one command to run next. */
 export async function runGreet(config) {
     say(banner());
@@ -580,10 +627,16 @@ async function linkSession(authDir, opts) {
             if (expired)
                 throw timedOut();
             const { state, saveCreds } = await useAtomicAuthState(authDir);
+            // This socket pairs and nothing else. It has no store, so anything it
+            // syncs is thrown away — and WhatsApp sends the history and the address
+            // book once. Refusing the history keeps it out of Baileys' sync state
+            // machine, which is what would otherwise bump `accountSyncCounter` and
+            // leave the service permanently past its own first sync.
             const sock = makeWASocket({
-                auth: state,
+                auth: withoutAppStateSync(state),
                 browser: WA_BROWSER,
                 markOnlineOnConnect: false,
+                shouldSyncHistoryMessage: () => false,
                 logger: SILENT_LOGGER,
             });
             current = sock;

package/dist/config.js

@@ -29,6 +29,8 @@ const COMMAND_ARGS = {
     logout: [0],
     connect: [1],
     config: [0, 2],
+    contacts: [1],
+    skills: [2],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -43,6 +45,17 @@ function asInt(value, fallback) {
     const n = Number.parseInt((value ?? "").trim(), 10);
     return Number.isFinite(n) ? n : fallback;
 }
+/**
+ * A user_config slot the person never filled in reaches us as the literal
+ * `${user_config.data_dir}`: the Claude Desktop bundle substitutes what it has
+ * and leaves the rest alone. An unanswered question is not a data directory.
+ */
+function dropUnfilledTemplates() {
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith("WAZAP_") && /^\$\{[^}]*\}$/.test(value ?? ""))
+            delete process.env[key];
+    }
+}
 /**
  * A human at a terminal running bare `wazap` wants to see where they stand, not
  * a silent MCP server on stdin. Everything else serves, including `wazap serve`.
@@ -87,6 +100,7 @@ export function parseCli(argv = process.argv.slice(2)) {
         return { kind: "help" };
     if (values.version)
         return { kind: "version" };
+    dropUnfilledTemplates();
     const [first, ...args] = positionals;
     if (first !== undefined && !COMMANDS.includes(first)) {
         throw new WazapError("INVALID_ID", `Unknown command "${first}".`, "Run `wazap --help`");

package/dist/connect.js

@@ -58,7 +58,7 @@ export const CLIENTS = [
         file: () => join(process.cwd(), ".vscode", "mcp.json"),
         format: "json",
         keyPath: ["servers", "whatsapp"],
-        extra: { type: "stdio" },
+        value: (entry) => ({ type: "stdio", ...entry }),
         next: "Written to ./.vscode/mcp.json for this workspace. Reload the VS Code window.",
         detect: (probe) => probe.onPath("code"),
     },
@@ -71,6 +71,27 @@ export const CLIENTS = [
         next: "Restart the Gemini CLI.",
         detect: (probe) => probe.exists(join(homedir(), ".gemini")),
     },
+    {
+        name: "windsurf",
+        describe: "Windsurf",
+        file: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        format: "json",
+        keyPath: ["mcpServers", "whatsapp"],
+        next: "Refresh the MCP servers in Windsurf's Cascade panel.",
+        detect: (probe) => probe.exists(join(homedir(), ".codeium", "windsurf")),
+    },
+    {
+        name: "opencode",
+        describe: "OpenCode",
+        file: () => join(homedir(), ".config", "opencode", "opencode.json"),
+        format: "json",
+        keyPath: ["mcp", "whatsapp"],
+        // OpenCode takes one array where the others take a command and its args,
+        // and its schema refuses anything else under the key.
+        value: (entry) => ({ type: "local", command: [entry.command, ...entry.args] }),
+        next: "Restart OpenCode.",
+        detect: (probe) => probe.exists(join(homedir(), ".config", "opencode")),
+    },
 ];
 export const CLIENT_NAMES = CLIENTS.map((client) => client.name).join(", ");
 const OTHER_CLIENTS = CLIENTS.slice(1)
@@ -173,7 +194,7 @@ function writeJsonEntry(spec, entry, dryRun) {
         }
         doc = parsed;
     }
-    const value = { ...spec.extra, command: entry.command, args: entry.args };
+    const value = spec.value?.(entry) ?? { command: entry.command, args: entry.args };
     setIn(doc, spec.keyPath, value);
     // Indent 1 collapsed to one line: short enough to read, still spaced like JSON.
     const shown = JSON.stringify(value, null, 1).replace(/\n\s*/g, " ");

package/dist/ids.js

@@ -11,6 +11,27 @@ export function normalizePhone(input) {
 export function isGroupId(jid) {
     return jid.endsWith("@g.us");
 }
+/**
+ * Jids that address nobody: the status feed, the `0@s.whatsapp.net` pseudo-chat
+ * WhatsApp files its own notices under, and anything malformed. They must never
+ * reach a chat list, a digest or the store.
+ *
+ * Stated as what to refuse rather than what to keep, so a jid kind wazap has
+ * not met yet — a broadcast list, a channel — still reaches the user instead of
+ * being silently swallowed, and a stored one is never purged.
+ */
+export function isNoiseJid(jid) {
+    const at = jid.lastIndexOf("@");
+    if (at === -1)
+        return true;
+    const user = jid.slice(0, at);
+    const domain = jid.slice(at + 1).toLowerCase();
+    if (domain === "broadcast")
+        return user.toLowerCase() === "status";
+    if (domain === "s.whatsapp.net" || domain === "c.us")
+        return /^0+$/.test(user) || !/^\d+$/.test(user);
+    return user === "";
+}
 /**
  * Canonicalize anything a caller may pass as a chat id.
  * Individuals become `<digits>@s.whatsapp.net`, groups stay `<id>@g.us`.

package/dist/index.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { BANNER } from "./banner.js";
-import { runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
+import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
 import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
 import { CLIENT_NAMES, runConnect } from "./connect.js";
+import { SKILL_TARGET_NAMES, runSkills } from "./skills.js";
 import { runSetup } from "./setup.js";
 import { runConfig } from "./settings.js";
 import { WazapError } from "./errors.js";
@@ -15,11 +16,14 @@ Usage:
   wazap login [--phone +15550100] [--code]              Link a WhatsApp account (QR by default)
   wazap setup [--agent] [--client <name>]                  Link, connect your client and finish, in one command
   wazap connect <client> [--dry-run]                       Register wazap with an MCP client
+  wazap skills install <harness> [--dry-run]               Copy the five skills into a harness
   wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
+  wazap contacts resync                                    Fetch the phone's address book from WhatsApp again
   wazap status [--live] [--json]                           Check the install, the session and the server
   wazap logout                                             Unlink and delete local credentials
 
 Clients for wazap connect: ${CLIENT_NAMES}.
+Harnesses for wazap skills install: ${SKILL_TARGET_NAMES}.
 
 Options:
   --data-dir <path>   Where wazap keeps its data (default ~/.wazap, or $WAZAP_DATA_DIR)
@@ -31,7 +35,7 @@ Options:
   --phone <number>    Your number in international format; implies --code
   --agent             With setup: print the procedure for an AI agent on stdout, then exit
   --client <name>     With setup: connect this client instead of the detected ones (repeatable)
-  --dry-run           With connect: print what would be written, and write nothing
+  --dry-run           With connect or skills install: print what would be written, and write nothing
   --live              With status: reach WhatsApp for real, then close the connection
   --json              With status: print the whole report as one JSON object on stdout
   --writes            Allow the agent to write, without login asking
@@ -72,9 +76,15 @@ async function main() {
         case "connect":
             runConnect(config);
             return;
+        case "skills":
+            runSkills(config);
+            return;
         case "config":
             runConfig(config);
             return;
+        case "contacts":
+            await runContacts(config);
+            return;
         case "status":
             await runStatus(config);
             return;

package/dist/messages.js

@@ -14,7 +14,8 @@ export function messageTimestampMs(raw) {
     const seconds = protoNumber(raw.messageTimestamp);
     return seconds === undefined ? Date.now() : seconds * 1000;
 }
-/** Stable across restarts, and stable under lid→pn remapping of the chat. */
+/** Stable across restarts. Not stable if the chat's own jid is later remapped
+ * from a LID to a phone number, which is why wazap does not remap chat jids. */
 export function messageIdFor(key, chatId) {
     return `${key.fromMe ? "true" : "false"}_${chatId}_${key.id ?? ""}`;
 }
@@ -50,7 +51,28 @@ const PROTOCOL = {
     tag: (m) => (isRevoke(m) ? DELETED_TEXT : SYSTEM_TEXT),
 };
 const SYSTEM = { type: "system", tag: SYSTEM_TEXT };
-const UNKNOWN = { type: "unknown", tag: "[unsupported message]" };
+/** Names the payload, so a bug report says which one to add. */
+const UNKNOWN = {
+    type: "unknown",
+    tag: (m) => {
+        const key = getContentType(m) ?? Object.keys(m).find((name) => m[name] != null);
+        return key ? `[unsupported: ${key}]` : "[unsupported message]";
+    },
+};
+/** Payloads WhatsApp exchanges with its own clients; no person ever sent one. */
+const CONTROL_KEYS = ["messageContextInfo", "senderKeyDistributionMessage"];
+/**
+ * The protocol messages that report something a person did. Baileys enumerates
+ * exactly these as cross-user in Utils/process-message.js — every other type is
+ * one device talking to another. MESSAGE_EDIT is cross-user too, but wazap
+ * applies the edit to the message it edits, so its envelope is not a second
+ * message to show.
+ */
+const REPORTABLE_PROTOCOL_TYPES = new Set([
+    proto.Message.ProtocolMessage.Type.REVOKE,
+    proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING,
+    proto.Message.ProtocolMessage.Type.GROUP_MEMBER_LABEL_CHANGE,
+]);
 /**
  * One table drives both messageType and messageText, so the reported type and
  * the placeholder can never disagree.
@@ -126,8 +148,13 @@ function ruleFor(content) {
     const rule = key ? RULES[key] : undefined;
     if (rule)
         return { rule, content };
-    if (content.messageContextInfo || content.senderKeyDistributionMessage)
+    // Only when the control keys are all there is. A payload wazap does not model
+    // yet usually carries messageContextInfo alongside it, and calling that a
+    // system message would hide someone's event, album or order behind
+    // "[system message]" and then out of the digest.
+    if (key === undefined && (content.messageContextInfo || content.senderKeyDistributionMessage)) {
         return { rule: SYSTEM, content };
+    }
     return { rule: UNKNOWN, content };
 }
 function stubKind(raw) {
@@ -141,6 +168,36 @@ function stubKind(raw) {
 function resolve(value, content) {
     return typeof value === "function" ? value(content) : value;
 }
+/**
+ * True for the machinery WhatsApp runs between devices: history-sync notices,
+ * app-state and peer-data responses, sender-key distribution, bare context
+ * info. They carry nothing a person did, so they are dropped rather than shown.
+ */
+export function isControlMessage(raw) {
+    if (isStubEvent(raw))
+        return false;
+    const content = unwrapEnvelopes(raw.message);
+    if (!content)
+        return true;
+    const key = getContentType(content);
+    if (key === "protocolMessage")
+        return !REPORTABLE_PROTOCOL_TYPES.has(content.protocolMessage?.type ?? -1);
+    if (key !== undefined)
+        return false;
+    // getContentType ignores the control keys, so reaching here means the payload
+    // is either nothing at all or nothing but control keys.
+    const present = Object.keys(content).filter((name) => content[name] != null);
+    return present.length === 0 || present.every((name) => CONTROL_KEYS.includes(name));
+}
+/**
+ * A message whose whole content is a stub type: WhatsApp's own notices about
+ * device linking, group membership and encryption. Baileys builds these with no
+ * `message` field at all, so they have to be recognised before the usual
+ * "no content, nothing to store" guard throws them away.
+ */
+export function isStubEvent(raw) {
+    return stubKind(raw) !== undefined;
+}
 export function messageType(raw) {
     const stub = stubKind(raw);
     if (stub === "deleted")
@@ -244,7 +301,7 @@ export function buildMessageView(raw, ctx) {
         from_me: Boolean(raw.key.fromMe),
         sender: {
             id: sender,
-            name: ctx.nameFor(sender) || raw.pushName || phoneOf(sender) || sender,
+            name: ctx.nameFor(sender),
             ...(phoneOf(sender) ? { phone: phoneOf(sender) } : {}),
         },
         type: messageType(raw),

package/dist/skills.js

@@ -0,0 +1,90 @@
+import { cpSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { WazapError } from "./errors.js";
+import { say } from "./logger.js";
+import { info, next, nextHint, ok, shortPath } from "./ui.js";
+/**
+ * Each path is the one that harness's own docs name today. Codex is the
+ * one that moved: `~/.codex/skills` still loads, but its docs call that
+ * location deprecated and put user skills in `~/.agents/skills`, which Cursor
+ * and OpenCode read too.
+ */
+export const SKILL_TARGETS = [
+    {
+        name: "claude-code",
+        describe: "Claude Code",
+        dir: null,
+        next: "/plugin marketplace add razvangirgiz/wazap",
+    },
+    {
+        name: "codex",
+        describe: "Codex CLI",
+        dir: () => join(homedir(), ".agents", "skills"),
+        next: "Restart Codex. Cursor and OpenCode read this directory too.",
+    },
+    {
+        name: "cursor",
+        describe: "Cursor",
+        dir: () => join(homedir(), ".cursor", "skills"),
+        next: "Reload the Cursor window.",
+    },
+    {
+        name: "opencode",
+        describe: "OpenCode",
+        dir: () => join(homedir(), ".config", "opencode", "skills"),
+        next: "Restart OpenCode.",
+    },
+    {
+        name: "agents",
+        describe: "This project, any agent",
+        dir: () => join(process.cwd(), ".agents", "skills"),
+        next: "Commit .agents/skills to share them with whoever clones this repo.",
+    },
+];
+export const SKILL_TARGET_NAMES = SKILL_TARGETS.map((target) => target.name).join(", ");
+/** The `skills/` folder shipped in the npm package, next to `dist/`. */
+function packagedSkills() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+function skillNames() {
+    try {
+        return readdirSync(packagedSkills(), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        throw new WazapError("FILE_NOT_FOUND", "This wazap install ships no skills/ directory.", "Upgrade with `npm i -g wazap-mcp@latest`, or run this from a checkout.");
+    }
+}
+function findSkillTarget(name) {
+    const target = SKILL_TARGETS.find((candidate) => candidate.name === name);
+    if (!target) {
+        throw new WazapError("INVALID_ID", `Unknown harness "${name}".`, `Pick one of: ${SKILL_TARGET_NAMES}`);
+    }
+    return target;
+}
+export function runSkills(config) {
+    if (config.args[0] !== "install") {
+        throw new WazapError("INVALID_ID", `Unknown skills command "${config.args[0]}".`, "Run `wazap skills install <harness>`");
+    }
+    const target = findSkillTarget(config.args[1] ?? "");
+    if (target.dir === null) {
+        say(info(`${target.describe} loads these skills from the wazap plugin, along with the MCP server.`));
+        say(next(target.next));
+        return;
+    }
+    const dir = target.dir();
+    const names = skillNames();
+    say(info(`${target.describe} · ${config.dryRun ? "would copy into" : "copying into"} ${shortPath(dir)}`));
+    for (const name of names) {
+        // Overwriting is the point: this is how an upgrade reaches an already
+        // installed harness, and re-running it must land in the same place.
+        if (!config.dryRun)
+            cpSync(join(packagedSkills(), name), join(dir, name), { recursive: true, force: true });
+        say(`  ${ok(name)}`);
+    }
+    say(nextHint(target.next));
+}