wazap-mcp 0.9.5 → 0.9.6

package/README.md

@@ -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,10 +124,55 @@ 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 |
@@ -148,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
 

package/dist/config.js

@@ -30,6 +30,7 @@ const COMMAND_ARGS = {
     connect: [1],
     config: [0, 2],
     contacts: [1],
+    skills: [2],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -44,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`.
@@ -88,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/index.js

@@ -3,6 +3,7 @@ import { BANNER } from "./banner.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,12 +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)
@@ -32,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
@@ -73,6 +76,9 @@ async function main() {
         case "connect":
             runConnect(config);
             return;
+        case "skills":
+            runSkills(config);
+            return;
         case "config":
             runConfig(config);
             return;

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));
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "wazap-mcp",
-  "version": "0.9.5",
+  "version": "0.9.6",
+  "mcpName": "io.github.razvangirgiz/wazap",
   "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, 22 tools, stdio or token-protected HTTP.",
   "license": "MIT",
   "author": "Răzvan Girgiz",
@@ -26,6 +27,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "AGENT.md",
     "LICENSE"
@@ -36,7 +38,11 @@
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/*.test.mjs",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "registry:validate": "node scripts/validate-server-json.mjs",
+    "bundle:mcpb": "node scripts/bundle-mcpb.mjs",
+    "icon": "node scripts/make-icon.mjs",
+    "context:build": "node scripts/build-context.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/wazap-setup/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: wazap-setup
+description: Install, link or repair the WhatsApp connection. Use when the user wants to connect WhatsApp to Claude, when a WhatsApp tool returns NOT_LINKED, SESSION_EXPIRED or SESSION_CORRUPT, when `get_status` is anything but connected, or when the user asks how wazap works with Claude Desktop, Claude Code or HTTP.
+---
+
+# wazap setup
+
+wazap links the user's own WhatsApp account as a "linked device" and exposes it as MCP tools. The phone must stay online; the link needs the user's hands once.
+
+## Diagnose first
+
+Run `npx wazap-mcp status` and branch on its output. It never contacts WhatsApp, so it is safe at any point.
+
+| `status` says | Do |
+| --- | --- |
+| `wazap: command not found` / npx fails | Node 20+ is required. `node --version`; install from nodejs.org if older. |
+| `linked: no` | Go to **Link**. |
+| `linked: yes`, `server: running` | The server is up. If tools still fail, call `get_status` and follow its `fix`. |
+| `linked: yes`, `server: not running` | Go to **Connect a client**. |
+
+Below those lines is a `checks:` section. Every `✗` carries the command that
+fixes it; run that command rather than improvising.
+
+| `checks:` line | What it means |
+| --- | --- |
+| `✗ node` | The Node version is below 20. Nothing else will work until it is upgraded. |
+| `✗ data dir` | Missing, not a directory, mode other than 0700, or not writable. The line names the `chmod` to run. |
+| `– lock: stale` | A previous server died without cleaning up. Harmless; the next start reclaims it. |
+| `✓ lock: held` | A server is running. Do not run `logout` or `status --live`; ask through the client with `get_status`. |
+| `✗ credentials` | Unreadable. `npx wazap-mcp logout` then `npx wazap-mcp login`. |
+| `writes: off` | Write tools are not registered. Enabling them is **Allow writes**. |
+| `– update` | A newer wazap exists, or the check could not reach npm. Never blocking. |
+
+`npx wazap-mcp status --live` reaches WhatsApp for real and reports whether the
+phone is reachable, how many chats synced and how old the last message is. It
+refuses while a server holds the lock, because one process owns the session.
+`--json` gives the same report as one object.
+
+## Link
+
+Run `npx wazap-mcp setup --agent` and follow what it prints.
+
+That procedure starts `login` in the background and reads the
+`pairing code: XXXX-XXXX` line out of its output, so the user is left with the
+one part of linking a machine cannot do, typing the code into the phone.
+
+`SESSION_EXPIRED` means the phone removed the device: run `npx wazap-mcp login` again. `SESSION_CORRUPT` means unreadable credentials: `npx wazap-mcp logout` then `npx wazap-mcp login`.
+
+## Connect a client
+
+Run `npx wazap-mcp connect <client>`, where the client is one of `claude-code`,
+`claude-desktop`, `cursor`, `codex`, `vscode` or `gemini`. It writes the entry,
+keeps whatever else is in the file, backs it up once, and prints the next step
+(restart, reload window, or `claude mcp list`). Running it twice is safe.
+
+- Add `--dry-run` first if the user wants to see the entry before it is written.
+- Claude Code users can install this plugin instead, which registers the server.
+- Remote clients (claude.ai, another machine) need HTTP mode with tokens; follow "HTTP mode" in the wazap README rather than improvising.
+
+Done when `get_status` returns `status: "connected"`. Then call `learn` once before using the other tools.
+
+## Allow writes
+
+Writes are off unless the user said yes at `login`. The write tools are then not
+registered at all, so the agent cannot see them.
+
+Turn them on with `npx wazap-mcp config writes on`, off again with
+`npx wazap-mcp config writes off`. Both edit `WAZAP_READ_ONLY` in
+`<data-dir>/.env`; a running server has to be restarted for the change to take
+effect. `npx wazap-mcp config` alone prints every effective setting and where it
+came from, which is how you tell a flag from an `.env` line.
+
+## Limits the user should hear once
+
+Baileys is an unofficial WhatsApp client; Meta can flag accounts, so heavy automated sending is the user's risk. One process owns the session: two wazap servers on the same data dir refuse to start.

package/skills/whatsapp-groups/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: whatsapp-groups
+description: Catch up on a busy WhatsApp group. Use when the user asks what happened in a group, what was decided, what they are being asked to do there, or for a summary of a thread with many messages. Read-only.
+---
+
+# WhatsApp group catch-up
+
+Deliverable: decisions, dates, and what is asked of the user, in that order, with the chatter gone. A 300-message thread should compress to a screen.
+
+## Load the whole window
+
+1. Resolve the group with `list_chats` `filter: "groups"` (match on name; ask if two match). `get_group_info` once for the participant names and who the admins are; use names, not numbers, in the summary.
+2. `read_messages` with `limit: 200`. If the oldest message is still inside the window the user asked for, call again with `before` set to that oldest `message_id`, until the window is covered. Done loading when the oldest message you hold is older than the window, or WhatsApp returns no more.
+3. Note which messages quote or mention the user: `quoted.sender` equal to the user, the user's name in `text`, or `sender` addressing them directly. These are the **asks**.
+
+## Extract
+
+Work through the messages once and collect:
+
+- **Decisions**: something agreed or announced by an admin or by the people it concerns ("ok, Saturday at 10 then").
+- **Dates and deadlines**: any concrete day, time, or "by Friday", with what it is for.
+- **Asks of the user**: every mention or reply to them, plus open questions nobody answered that fall on the user.
+- **Open threads**: questions still without an answer, for anyone.
+- **Polls**: the question and options (`[poll] …`); wazap cannot read votes, so say that if the user asks who voted.
+
+Skip greetings, reactions, stickers, and messages that only acknowledge.
+
+## Report
+
+```
+Bloc 12 — 312 messages since Monday
+
+Decided
+- Roof repair goes to Tehnoplast, 18,400 lei, vote closed Wednesday.
+- Water off Thursday 09:00–13:00.
+
+Dates
+- Fri 15 Mar: pay share (1,150 lei) to the association account.
+
+You
+- Mihai asked (Tue) if you can be home Thursday for the plumber. Unanswered.
+
+Open
+- Nobody confirmed who holds the basement key.
+```
+
+End with the message count and the window covered, so the user knows what the summary stands on. Replying in the group is the `whatsapp-send` skill's job; here, offer it only for the *You* items.

package/skills/whatsapp-inbox/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: whatsapp-inbox
+description: Triage the user's WhatsApp. Use when they ask what they missed, what's unread, who is waiting on a reply, what needs attention today, or whom they forgot to answer. Read-only; it sends nothing and marks nothing read.
+---
+
+# WhatsApp inbox triage
+
+Deliverable: a short, ranked list of what needs the user, with everything else compressed to one line. The user should finish reading in under a minute.
+
+## Collect
+
+1. `get_recent_messages` with the window the user implied (default 24h; "this week" = 168). If the result says `sync: "in_progress"`, wait 5 seconds and call it again once.
+2. `list_chats` with `filter: "unread"` to catch chats whose activity predates the window.
+3. For follow-ups ("whom did I forget"): in `list_chats` results, an individual chat whose `last_message.from_me` is false and older than 2 days is an unanswered conversation. Read its last 5 messages with `read_messages` to confirm something was actually asked.
+
+Done collecting when every chat with unread messages appears in exactly one bucket below.
+
+## Triage
+
+Sort each chat into one bucket:
+
+- **Needs you**: a direct question to the user, a request, a mention of the user in a group (`sender` is not the user and the text addresses them or quotes one of their messages), or money/dates/decisions awaiting them.
+- **FYI**: information with no ask. Shipping updates, "ok thanks", group chatter that reached a conclusion.
+- **Noise**: promotions, broadcast lists, groups the user is muted in (`muted_until` in the future), forwards without a question.
+
+Rank *Needs you* by: people over groups, older unanswered over newer, money and deadlines first.
+
+## Report
+
+```
+Needs you (3)
+1. Ana — asks if Thursday 10:00 works for the notary. 5h ago.
+2. Bloc 12 group — Mihai needs your vote on the roof quote by Friday. 1d ago.
+3. Dan — sent the contract PDF, waiting for your comments. 2d ago.
+
+FYI: Curier (delivered), Mama (photos), Team (retro moved to Tuesday).
+Noise: 4 promo chats.
+```
+
+One line per item: who, what they want, how old. Include the `chat_id` only if the user is likely to act through another tool next. Offer to draft replies only for *Needs you* items; drafting and sending belong to the `whatsapp-send` skill.

package/skills/whatsapp-recall/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: whatsapp-recall
+description: Find something in the user's WhatsApp history. Use when they ask for an address, invoice, photo, document, link, phone number, date or a thing someone said or sent, or "what did X say about Y". Read-only.
+---
+
+# WhatsApp recall
+
+Deliverable: the exact message or file, quoted with who sent it and when, or a clear "not found" that says where you looked.
+
+## Narrow, then search
+
+1. If a person or group is named, resolve it with `search_contacts` (people) or `list_chats` with `filter: "groups"` (groups) and search inside that `chat_id`. Searching one chat beats searching everything.
+2. `search_messages` with the user's words. If nothing matches, run two more variants before giving up: a synonym or the other language the user writes in, and a narrower fragment (a street name instead of "the address", "factura" instead of "the invoice from March").
+3. Media has no searchable text beyond its caption and the `[image]`/`[document] name.pdf` placeholder. For "the photo of…" or "the PDF", search the placeholder and filename words, or `read_messages` on the chat with `limit: 100` and scan `type` and `media.filename`.
+4. Older than what is loaded: `read_messages` with `before` set to the oldest `message_id` you have, repeatedly, until the date the user remembers is covered or WhatsApp returns nothing more.
+
+Done searching when you have a match, or all three query variants and the pagination step came back empty.
+
+## Deliver
+
+- A message: quote the text verbatim, then sender, chat, timestamp. Example: *"Str. Lunii 14, ap. 3, interfon 31" — Ana, 12 Mar 14:05.*
+- A file or photo: `download_media` on the message, then open the saved file with your file-reading tool and answer from its contents when the user asked a question about it (an amount, a clause, a date). Give the saved path so the user can open it.
+- A link: return the URL as sent; do not fetch it unless asked.
+- Several candidates: list up to 5 with sender and date and ask which one, rather than guessing.
+- Not found: say which chats and which phrases you tried, and whether `MEDIA_UNAVAILABLE` blocked a download (the sender must resend).

package/skills/whatsapp-send/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: whatsapp-send
+description: Send, reply, forward, share a file, react, or create a poll on WhatsApp on the user's behalf. Use for any request that results in an outgoing WhatsApp message. Drafts first and sends after the user approves; messages leave from the user's own account and cannot be unsent.
+---
+
+# WhatsApp send
+
+A message sent here is indistinguishable from one the user typed. The rail: **the user sees recipient and exact text, says yes, then it goes.** One approval covers one message to one chat.
+
+## Resolve the recipient
+
+1. `search_contacts` with the name. Exactly one match: use its `chat_id`. Several: list them with numbers and ask. None: ask for the number in international format; `NOT_ON_WHATSAPP` means the number is wrong, not that you should retry.
+2. Groups come from `list_chats` with `filter: "groups"`. Before posting, `get_group_info`; if `announcement_only` is true and the user is not admin, say so instead of trying.
+3. A reply to a specific message needs its `message_id` from `read_messages`; pass it as `reply_to` so the quote shows.
+
+## Draft
+
+1. `read_messages` on the chat, `limit: 20`, and match the register already in use: language (Romanian or English), formality, emoji, length. A two-line chat gets a two-line reply.
+2. Write the message as the user, first person, without a signature or "sent by an assistant".
+3. Files: `send_media` needs a local `file_path` that exists on the machine running wazap, or a public URL. Check the path before drafting; pick `as_document: true` for PDFs and anything the recipient should keep at original quality, `as_voice: true` only for audio meant as a voice note.
+
+## Confirm, then send
+
+Show exactly this and wait for a yes:
+
+```
+To: Ana (+40 722 …)
+"Joi la 10 e perfect, ne vedem la notar. Aduc eu actele."
+```
+
+Send on the user's yes with `send_message` / `send_media` / `send_poll` / `send_location` / `forward_message`, and report the result with the `message_id` so the user can follow up with `edit_message` (own messages, 15 minutes) or `delete_message`.
+
+Approval is per message, even after "just send it" for a batch, when the recipient is a group, a number not in the user's contacts, or the content contains money, dates, or commitments. For a batch of plain messages the user already approved as a list, send them one by one and stop at the first error; `RATE_LIMITED` means wait the seconds in `fix`, then continue.
+
+## Out of scope
+
+`delete_message` with `for_everyone` and `manage_group` remove/leave run only on an explicit ask naming the message or person. Bulk sends to people who did not write first are the user's account at risk of a WhatsApp ban; say that once and let them decide.