@wirecat/whatsapp-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,28 @@
-# wa — WhatsApp CLI for AI agents
+<p align="center">
+  <img src="https://raw.githubusercontent.com/WireCatLabs/whatsapp-cli/main/docs/images/social-preview.png" alt="WhatsApp CLI for AI agents" width="100%">
+</p>
 
-Your personal WhatsApp in the terminal, searchable on your computer, and ready for Claude Code, Codex, Cursor or any
-agent — within limits you set.
+# wa — WhatsApp CLI for AI agents
 
-> **Early.** `wa` links, reads into its local store, sends text and files, edits, deletes for everyone, reacts and
-> runs groups. What comes next is on the [roadmap](docs/roadmap.md).
+<p align="center">
+  Your personal WhatsApp in the terminal, searchable on your computer, and ready for Claude Code,
+  Codex, Cursor or any agent — within limits you set.
+</p>
+
+<p align="center">
+  <a href="https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/README.md">Docs</a> ·
+  <a href="https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/recipes.md">Examples</a> ·
+  <a href="https://wirecat.dev">WireCat</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@wirecat/whatsapp-cli"><img src="https://img.shields.io/npm/v/@wirecat/whatsapp-cli" alt="npm"></a>
+  <a href="https://github.com/WireCatLabs/whatsapp-cli/actions/workflows/main.yml"><img src="https://github.com/WireCatLabs/whatsapp-cli/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@wirecat/whatsapp-cli" alt="Node"></a>
+  <a href="https://bun.sh/"><img src="https://img.shields.io/badge/bun-tested-f9f1e1" alt="Bun"></a>
+  <a href="https://www.npmjs.com/package/@wirecat/whatsapp-cli"><img src="https://img.shields.io/npm/dm/@wirecat/whatsapp-cli" alt="npm downloads"></a>
+  <a href="https://github.com/WireCatLabs/whatsapp-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache 2.0"></a>
+</p>
 
 An example conversation (invented people, illustrative output):
 
@@ -18,6 +36,15 @@ Agent:  Draft to Alice Example: "Yes, 8 pm." Send it?
 You:    Yes.
 ```
 
+> ⚠️ **`wa` is an unofficial client of your real WhatsApp account.** WhatsApp's terms forbid unofficial clients, and
+> WhatsApp may ban an account that uses one. It also bans accounts that send in bulk or write to people who do not
+> know them. `wa` writes only when a command asks, sends at most 30 messages an hour by default, and holds every
+> write when WhatsApp says to slow down or restricts the account. Do not send in bulk, and do not write to strangers.
+> You use `wa` at your own risk. More: [limits](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/limits.md)
+
+**Early.** `wa` is new, and some of what it does has not yet been checked against real WhatsApp. The
+[backlog](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/dev/BACKLOG.md) lists the checks still to run.
+
 ## Quick start
 
 ```sh
@@ -34,7 +61,7 @@ chats and installs the agent skill.
 It needs **Node 22.16+ or 24+** on macOS, Linux or Windows. npm also installs the engine, the small program that
 speaks WhatsApp's protocol, as a separate package for your system.
 
-More: [installation guide](docs/installation.md) · [linking](docs/sessions.md)
+More: [installation guide](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/installation.md) · [linking](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/sessions.md)
 
 ## What can you do?
 
@@ -59,6 +86,13 @@ wa personal review --new                  # what changed since the last review -
 wa personal tasks list state:open
 ```
 
+**Run your groups.** *"Use wa CLI. Which questions in Hiking has nobody answered?"*
+
+```sh
+wa personal review chat:Hiking --unanswered
+wa personal chats events Hiking 'time>=7d'   # who joined, left, was added or removed
+```
+
 **Answer, when you say so.**
 
 ```sh
@@ -69,37 +103,104 @@ wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyone
 wa personal chats mark-read "Book club"   # the other side sees it
 ```
 
-More: [recipes, with a schedule for each](docs/recipes.md) · [using wa](docs/usage.md)
+More: [recipes, with a schedule for each](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/recipes.md) · [using wa](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/usage.md)
 
 ## Built for AI agents
 
+Your agent. Your WhatsApp. Your rules.
+
 - **Agents with a terminal** (Claude Code, Codex, Gemini CLI) run `wa` commands themselves. The bundled
-  [skill](skills/whatsapp-cli/SKILL.md) tells them how: `wa personal setup --agent …` or `wa skill install` puts it in
-  place, and `wa skill show` prints it before linking. An agent links with `--qr-file` and shows you the picture; it
-  never asks for your phone number or a code.
-- **Apps without a terminal** (Claude Desktop, Cursor and other MCP clients) connect to `wa personal mcp`.
+  [skill](https://github.com/WireCatLabs/whatsapp-cli/blob/main/skills/whatsapp-cli/SKILL.md) tells them how: `wa personal setup --agent …` or `wa skill install` puts it in
+  place, and `wa skill show` prints it before linking. An agent links by QR: it pastes the code into the chat as text for you
+  to scan, and never asks for your phone number or a code.
+- **Apps without a terminal** (Claude Desktop, Cursor and other MCP clients) connect to `wa personal mcp`. It
+  comes with ready prompts: `/catch-up`, `/review`, `/reply`, `/find` and more.
 
 ```sh
 wa personal mcp setup claude-code   # or: wa personal mcp setup codex
 wa personal mcp config              # the entry for Claude Desktop, Cursor and others
 ```
 
-More: [the MCP server](docs/mcp.md) · [from the browser](docs/remote.md)
+The profile can send by default, so `mcp setup` stops first. Check the profile's permissions, then run it again with
+`--allow-writes`.
 
-## How it differs from tg and max
+More: [the MCP server](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/mcp.md) · [from the browser](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/remote.md)
 
-`wa` is part of the [WireCat](https://wirecat.dev) family, beside [tg](https://github.com/WireCatLabs/tg-cli) for
-Telegram and [max](https://github.com/WireCatLabs/max-cli) for MAX. All three share their commands, their store and
-their agent tools, so what you learn in one works in the others. WhatsApp is different in three ways:
+## Why wa?
 
-- **History comes from your phone.** WhatsApp's servers keep no history to ask for. Your phone sends your recent
-  chats once, when `wa` links, and `wa serve` keeps receiving new ones. Older messages of one chat can be asked of the
-  phone, 50 at a time, while WhatsApp is open on it (`wa personal messages sync`). Every read answers from the local
-  store and never connects.
-- **One connection per device.** WhatsApp allows one. While `wa serve` runs, other commands for the same profile,
-  a send included, run through its connection. On Windows they are refused until `serve` stops, for now.
-- **Unofficial.** WhatsApp's terms forbid unofficial clients, and WhatsApp may ban an account that uses one. `wa`
-  never sends in bulk or to strangers, never sends "online" or "typing", and marks nothing read unless you ask.
+- **Your own account, as a linked device.** `wa` links the way WhatsApp Web does. It sees your chats, groups and
+  contacts, and speaks as you, not as a business account or a bot.
+- **Local-first search.** Everything received is kept on your computer. Every read and search answers from there and
+  never connects.
+- **Made for agents.** One operation per call, the same JSON shape every time with `--json`, a fixed exit code for
+  each kind of failure, an MCP server and a skill.
+- **Safe by default.** Reading marks nothing read and sends no "online" or "typing". A profile decides which actions
+  an agent may take, which chats it may send to, and how many messages an hour (30 by default). When a send's outcome
+  is unknown, `wa` says so and never repeats it by itself.
+
+## Your account
+
+`wa` works in your name, as one more linked device of your WhatsApp account.
+
+```sh
+wa personal chats list --limit 5
+wa personal messages list "Book club" --limit 20
+wa personal messages send "Book club" "The minutes" --file minutes.pdf
+wa personal polls create "Book club" "Which day?" Monday Tuesday
+wa personal messages download "Book club" 3EB0A1B2C3D4E5F6A7B8 --output-dir ~/Downloads
+wa personal messages transcribe "Book club" 3EB0A1B2C3D4E5F6A7B8 --local  # a voice note as text
+```
+
+The message id `3EB0A1B2C3D4E5F6A7B8` is made up; take a real one from `messages list -v`.
+
+- **Read.** Chats and messages from the local store, one message with its neighbours, other people's unread
+  messages (`wa personal inbox`), everything since the last review (`wa personal review`), new messages as they
+  arrive (`wa personal watch`), older messages of one chat asked of your phone (`wa personal messages sync`), and
+  the posts of the channels you follow (`wa personal chats join` with a channel link, then `messages sync`).
+- **Write.** Markdown, replies, one file, photo, video or voice note per message, a photo and a video as one album,
+  edits of your own messages within 20 minutes, forwards, reactions, polls and votes, pins (each one tells the
+  members), deleting for you or for everyone, and marking a chat read.
+- **Your chat list.** Mute, archive, pin or mark a chat unread, star a message, and delete or clear a chat on your
+  own devices; nobody in the chat is told.
+- **Voice on your computer.** WhatsApp has no speech recognition of its own, so `wa` runs a speech model on this
+  machine, downloaded only when you ask.
+- **People.** A person's profile, blocking, whether a number has WhatsApp, the phone's address book into the store,
+  and your own names and notes for people.
+- **Your account.** Your own name, about line and profile photo (`wa personal account update`).
+- **Privacy.** Who sees your last seen, online, profile photo and about line, whether you send read receipts, who
+  may add you to groups and whose calls ring (`wa personal account privacy`).
+
+More files in one message than a photo and a video are not built yet:
+[not in wa yet](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/usage.md#not-in-wa-yet).
+
+More: [using wa](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/usage.md) · [privacy](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/usage.md#privacy) · [one person](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/people.md)
+
+## Log in and profiles
+
+`wa` links to your account as a device, the way WhatsApp Web does. There is no password and no app to register: you
+link once, from the phone, and the device keys go to one file only your user can read.
+
+```sh
+wa personal session start               # a QR code: WhatsApp → Settings → Linked devices → Link a device
+wa personal session start phone         # or your number, then a pairing code you type on the phone
+wa personal account show                # who this profile is linked as
+wa account list                         # every profile here, and who each is linked as
+wa personal session end                 # unlink, and delete the device keys here
+```
+
+Several accounts are several profiles, and the profile is **the first word**, not an option:
+
+```sh
+wa personal chats list     # profile "personal"
+wa work chats list         # profile "work"
+export WA_PROFILE=work     # or for the whole shell session
+```
+
+`wa` never picks a profile for you, not even the only one: a command that uses an account and has no profile named
+stops and lists the profiles on this computer. Name one or set `WA_PROFILE`. Each profile is a linked device of its
+own, with its own one connection.
+
+More: [linking, devices and profiles](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/sessions.md) · [profiles](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/profiles.md)
 
 ## The local store and search
 
@@ -114,13 +215,15 @@ wa personal messages evidence "Project Alpha" --json   # bounded evidence for a
 wa personal store backup ~/wa-backup.db   # a copy, safe while the store is in use
 ```
 
-More: [search](docs/search.md) · [the local store](docs/archive.md) · [query language](docs/query-language.md)
+More: [search](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/search.md) · [the local store](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/archive.md) · [query language](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/query-language.md)
 
 ## Groups you run
 
 ```sh
 wa personal review chat:Hiking --unanswered          # questions nobody answered
 wa personal review 'chat:Hiking date>7d'             # the week: decisions, promises, open questions
+wa personal chats events Hiking 'time>=7d'           # who joined, left, was added or removed, and by whom
+wa personal chats inspect https://chat.whatsapp.com/AAAAAAAAAAAAAAAAAAAAAA  # where an invite leads, without joining
 wa personal stats chats show Hiking --offline        # the group's activity, from the local store
 wa personal chats create "Hiking 2027" 100000000000002@lid   # a new group, with people you know
 wa personal chats members add 120363000000000001@g.us 100000000000002@lid
@@ -128,54 +231,49 @@ wa personal chats update 120363000000000001@g.us --join-approval on
 wa personal chats requests list 120363000000000001@g.us
 ```
 
-Renaming a group, members and admins, the invite link, join requests and who may send or add people are commands
-too. The members see each change, so each passes the profile's permissions and hourly limit. `wa` adds only people in
-your address book or that you have written to: WhatsApp bans accounts that add strangers.
+Renaming a group, its photo, members and admins, the invite link, join requests and who may send or add people are
+commands too. The members see each change, so each passes the profile's permissions and hourly limit. `wa` adds only
+people in your address book or that you have written to: WhatsApp bans accounts that add strangers.
 
-More: [groups](docs/groups.md)
+More: [groups](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/groups.md)
 
-## Output for scripts and agents
+## Agent setup in detail
 
-With `--json` a command prints only data, as one JSON value. `--jsonl` prints one object per line. Every list has
-one shape:
+**The skill.** Claude Code reads `~/.claude/skills/whatsapp-cli/`; Codex and Gemini CLI read
+`~/.agents/skills/whatsapp-cli/`. Start a new agent session if it does not see the skill.
 
-```json
-{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }
+```sh
+wa skill install --for all        # both folders, without linking
+wa skill show                     # the complete instructions, without installing them
 ```
 
-An error goes to stderr as one line, with stdout empty, and the command exits with a fixed code: `4` link the
-profile, `5` the profile may not do this, `6` chat or message not found, `8` a limit, `12` another command holds the
-device, `14` unknown whether a message went. `wa commands --json` is the whole command tree.
+**The MCP server.** The profile's `permissions` decide which tools it offers. `readonly` stops the agent from
+changing anything; at `ask` the server shows no form, so set up approval in your agent app.
 
-More: [CLI contract](docs/cli-contract.md) · [every command and exit code](docs/commands.md)
+```sh
+claude mcp add wa -- wa personal mcp  # Claude Code, by hand
+wa personal mcp doctor                # check the local MCP server
+```
 
-## Log in and profiles
+**From the browser.** ChatGPT or Claude in the browser reach `wa personal mcp --http --public-url` behind your tunnel,
+after a login with a one-time access code from your terminal.
 
-`wa` links to your account as a device, the way WhatsApp Web does. There is no password and no app to register: you
-link once, from the phone, and the device keys go to one file only your user can read.
+More: [the MCP server](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/mcp.md) · [from the browser](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/remote.md)
 
-```sh
-wa personal session start               # a QR code: WhatsApp → Settings → Linked devices → Link a device
-wa personal session start phone         # or your number, then a pairing code you type on the phone
-wa personal session start --qr-file login.png  # the QR code as a picture, for an agent to show you
-wa personal account show                # who this profile is linked as
-wa account list                         # every profile here, and who each is linked as
-wa personal session end                 # unlink, and delete the device keys here
-```
+## Output for scripts and agents
 
-Several accounts are several profiles, and the profile is **the first word**, not an option:
+With `--json` a command prints only data, as one JSON value. `--jsonl` prints one object per line. Every list has
+one shape:
 
-```sh
-wa personal chats list     # profile "personal"
-wa work chats list         # profile "work"
-export WA_PROFILE=work     # or for the whole shell session
+```json
+{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }
 ```
 
-`wa` never picks a profile for you, not even the only one: a command that uses an account and has no profile named
-stops and lists the profiles on this computer. Name one or set `WA_PROFILE`. Each profile is a linked device of its
-own, with its own one connection.
+An error goes to stderr as one line, with stdout empty, and the command exits with a fixed code: `4` link the
+profile, `5` the profile may not do this, `6` chat or message not found, `8` a limit, `12` another command holds the
+device, `14` unknown whether a message went. `wa commands --json` is the whole command tree.
 
-More: [linking, devices and profiles](docs/sessions.md) · [profiles](docs/profiles.md)
+More: [CLI contract](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/cli-contract.md) · [every command and exit code](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/commands.md)
 
 ## Settings and permissions
 
@@ -185,10 +283,11 @@ wa personal config set permissions.messages.send ask   # a question in the termi
 wa personal config set sends_per_hour 10               # at most 10 sends an hour (30 by default)
 wa personal recipients add "Book club"                 # the first add turns the recipient list on
 wa personal sends list                                 # every attempt: sent, refused, failed or not known
+wa personal config show                                # what is set, and where it came from
 ```
 
-More: [permissions](docs/permissions.md) · [profiles](docs/profiles.md) · [configuration](docs/configuration.md) ·
-[limits](docs/limits.md)
+More: [permissions](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/permissions.md) · [profiles](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/profiles.md) · [configuration](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/configuration.md) ·
+[limits](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/limits.md)
 
 ## Limits
 
@@ -197,7 +296,7 @@ from what WhatsApp bans. A profile sends at most 30 messages an hour by default.
 profile; another one is refused with exit code `12` and names the holder, unless `serve` runs and carries it on its
 connection. There is nothing to download in bulk: reads answer from the local store.
 
-More: [limits and waits](docs/limits.md)
+More: [limits and waits](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/limits.md)
 
 ## Security
 
@@ -208,7 +307,7 @@ More: [limits and waits](docs/limits.md)
   text.
 - Nothing `wa` sends to WhatsApp names this tool: it links as a desktop browser.
 
-To report a vulnerability: [SECURITY.md](SECURITY.md). More: [security](docs/security.md)
+To report a vulnerability: [SECURITY.md](https://github.com/WireCatLabs/whatsapp-cli/blob/main/SECURITY.md). More: [security](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/security.md)
 
 ## When something goes wrong
 
@@ -218,40 +317,60 @@ wa personal doctor --online # also connect once and read the account
 wa personal runs list       # recorded runs
 ```
 
-More: [troubleshooting by symptom](docs/troubleshooting.md) · [diagnostics](docs/diagnostics.md)
+More: [troubleshooting by symptom](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/troubleshooting.md) · [diagnostics](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/diagnostics.md)
+
+## How it differs
+
+`wa` shares its commands, its store and its agent tools with tg and max, so what you learn in one works in the
+others. WhatsApp is different in three ways:
+
+- **History comes from your phone.** WhatsApp's servers keep no history to ask for. Your phone sends your recent
+  chats once, when `wa` links, and `wa serve` keeps receiving new ones. Older messages of one chat can be asked of the
+  phone, 50 at a time, while WhatsApp is open on it (`wa personal messages sync`). Every read answers from the local
+  store and never connects.
+- **One connection per device.** WhatsApp allows one. While `wa serve` runs, other commands for the same profile,
+  a send included, run through its connection. On Windows they are refused until `serve` stops, for now.
+- **Unofficial.** The risk of a ban is in the warning at the top of this page. `wa` never sends "online" or
+  "typing", and marks nothing read unless you ask.
+
+## Part of WireCat
+
+[WireCat](https://wirecat.dev) is an open-source, local-first context layer for AI agents. `wa` sits beside
+[tg](https://github.com/WireCatLabs/tg-cli) for Telegram and [max](https://github.com/WireCatLabs/max-cli) for MAX, in
+the same local store.
 
 ## Technical docs
 
-Every page is in [`docs/`](docs/README.md):
+Every page is in [`docs/`](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/README.md):
 
 | Page | Answers |
 |---|---|
-| [index](docs/index.md) | The docs site's start page: what `wa` is, the first minute, where to go next |
-| [installation](docs/installation.md) | How do I install it, and what does it need? |
-| [usage](docs/usage.md) | How do I link, read, send and change a message — in that order? |
-| [sessions](docs/sessions.md) | How does linking work: QR or pairing code, one connection per device, profiles, unlinking? |
-| [archive](docs/archive.md) | What does the local store keep, how is it filled, and how do I export and back it up? |
-| [search](docs/search.md) | How do I find a message by its words, sender, chat, date, file or label, save a search and count? |
-| [attachments](docs/attachments.md) | Sending, saving and forwarding files; their text, and voice notes as text |
-| [query-language](docs/query-language.md) | Every search field, operator, preset, limit and the JSON answer |
-| [groups](docs/groups.md) | How do I keep up with a group, and run one? |
-| [people](docs/people.md) | One person: what the store holds about them, your own names and notes |
-| [mcp](docs/mcp.md) | How do I connect Claude Desktop, Cursor or another client without a terminal? |
-| [remote](docs/remote.md) | ChatGPT or Claude in the browser, through a login and a tunnel |
-| [recipes](docs/recipes.md) | What can an agent do for me every day, and how do I run it on a schedule? |
-| [commands](docs/commands.md) | Every command, option and exit code — **generated** from the program |
-| [configuration](docs/configuration.md) | How do I configure common behaviour? |
-| [permissions](docs/permissions.md) | What a profile may read, what asks first, and what may go ahead |
-| [profiles](docs/profiles.md) | Several accounts on one computer, and how a command picks one |
-| [configuration-reference](docs/configuration-reference.md) | Every key, default, scope and variable |
-| [cli-contract](docs/cli-contract.md) | Invocation, output, errors, headless runs, bounds and previews |
-| [limits](docs/limits.md) | Limits, waits and the one connection per device |
-| [diagnostics](docs/diagnostics.md) | What did a command do, and what is never recorded? |
-| [troubleshooting](docs/troubleshooting.md) | Something does not work: what the screen says, and what to do |
-| [security](docs/security.md) | What does `wa` keep on my computer, and what can go wrong? |
-| [roadmap](docs/roadmap.md) | What is coming next? |
-
-What each version changed: [CHANGELOG.md](CHANGELOG.md).
+| [index](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/index.md) | The docs site's start page: what `wa` is, the first minute, where to go next |
+| [installation](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/installation.md) | How do I install it, and what does it need? |
+| [usage](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/usage.md) | How do I link, read, send and change a message — in that order? |
+| [sessions](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/sessions.md) | How does linking work: QR or pairing code, one connection per device, profiles, unlinking? |
+| [archive](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/archive.md) | What does the local store keep, how is it filled, and how do I export and back it up? |
+| [search](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/search.md) | How do I find a message by its words, sender, chat, date, file or label, save a search and count? |
+| [attachments](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/attachments.md) | Sending, saving and forwarding files; their text, and voice notes as text |
+| [query-language](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/query-language.md) | Every search field, operator, preset, limit and the JSON answer |
+| [groups](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/groups.md) | How do I keep up with a group, and run one? |
+| [people](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/people.md) | One person: what the store holds about them, your own names and notes |
+| [mcp](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/mcp.md) | How do I connect Claude Desktop, Cursor or another client without a terminal? |
+| [remote](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/remote.md) | ChatGPT or Claude in the browser, through a login and a tunnel |
+| [recipes](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/recipes.md) | What can an agent do for me every day, and how do I run it on a schedule? |
+| [commands](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/commands.md) | Every command, option and exit code — **generated** from the program |
+| [configuration](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/configuration.md) | How do I configure common behaviour? |
+| [permissions](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/permissions.md) | What a profile may read, what asks first, and what may go ahead |
+| [profiles](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/profiles.md) | Several accounts on one computer, and how a command picks one |
+| [configuration-reference](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/configuration-reference.md) | Every key, default, scope and variable |
+| [cli-contract](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/cli-contract.md) | Invocation, output, errors, headless runs, bounds and previews |
+| [limits](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/limits.md) | Limits, waits and the one connection per device |
+| [diagnostics](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/diagnostics.md) | What did a command do, and what is never recorded? |
+| [troubleshooting](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/troubleshooting.md) | Something does not work: what the screen says, and what to do |
+| [security](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/security.md) | What does `wa` keep on my computer, and what can go wrong? |
+| [roadmap](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/roadmap.md) | What is coming next? |
+
+What each version changed: [CHANGELOG.md](https://github.com/WireCatLabs/whatsapp-cli/blob/main/CHANGELOG.md).
 
 ## Development
 
@@ -260,13 +379,13 @@ pnpm install
 pnpm lint && pnpm typecheck && pnpm test
 pnpm engine:build && pnpm engine:test   # the Go engine; needs Go
 pnpm generate                           # rewrites docs/commands.md from the command tree
-bin/wa personal chats list              # everything under .wa/ in this checkout, never the real profile
+bin/wa personal chats list              # config, state and device under .wa/; a worktree's store too
 ```
 
 Everything that is not specific to WhatsApp — the commands, the store, the send guard, the MCP server — lives in
 [cli-core](https://github.com/WireCatLabs/cli-core), shared with tg and max.
 
-More: [ARCHITECTURE](docs/dev/ARCHITECTURE.md) · [TESTING](docs/dev/TESTING.md)
+More: [ARCHITECTURE](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/dev/ARCHITECTURE.md) · [TESTING](https://github.com/WireCatLabs/whatsapp-cli/blob/main/docs/dev/TESTING.md)
 
 ## Contributing
 
@@ -276,8 +395,8 @@ Custom automation with WhatsApp, other messengers and AI agents: [info@neirox.ai
 
 ## License
 
-The CLI is [Apache-2.0](LICENSE). The engine is not: the Go program in [`engine/`](engine/) and the
-`@wirecat/whatsapp-engine-*` packages that carry it are [GPL-3.0-only](engine/LICENSE), because the engine links
+The CLI is [Apache-2.0](https://github.com/WireCatLabs/whatsapp-cli/blob/main/LICENSE). The engine is not: the Go program in [`engine/`](https://github.com/WireCatLabs/whatsapp-cli/tree/main/engine) and the
+`@wirecat/whatsapp-engine-*` packages that carry it are [GPL-3.0-only](https://github.com/WireCatLabs/whatsapp-cli/blob/main/engine/LICENSE), because the engine links
 go.mau.fi/libsignal, which is under the GNU General Public License 3.0, through whatsmeow. The two are separate
 programs: `wa` starts the engine as a child process and talks to it only over stdin and stdout. Each engine package
 says where its source is and lists every Go module it links in `THIRD_PARTY_NOTICES`.

package/dist/adapter/adapter.d.ts

@@ -1,9 +1,13 @@
 import { type MarkdownFormatting } from "@wirecat/cli-core";
-import type { LiveUpdates, MessageEditing, MessageMedia, MessageReactions, MessengerCore, PushedHistory, ReadState, ServerReads, StoredMessages } from "@wirecat/cli-core/cli";
+import type { LiveUpdates, MessageEditing, MessageMedia, MessagePins, MessageReactions, MessageStars, MessengerCore, PassiveUpdates, PushedHistory, ReadState, ServerReads, StoredMessages } from "@wirecat/cli-core/cli";
 import { type WhatsAppEngine } from "../engine/contract.js";
-import { type Words } from "./checks.js";
+import type { Words } from "./checks.js";
 import { type GroupAdapter } from "./groups.js";
 import { type PollAdapter } from "./polls.js";
-export type WhatsAppAdapter = MessengerCore & LiveUpdates & PushedHistory & Pick<MessageEditing, "edit" | "delete" | "forward"> & Pick<MessageMedia, "download"> & MessageReactions & ReadState & Pick<ServerReads, "history"> & MarkdownFormatting & PollAdapter & GroupAdapter;
-export declare const whatsAppAdapter: (engine: WhatsAppEngine, stored?: StoredMessages, words?: Words) => WhatsAppAdapter;
+import { type PrivacyAdapter } from "./privacy.js";
+import { type SettingsAdapter } from "./settings.js";
+export type WhatsAppAdapter = MessengerCore & LiveUpdates & PassiveUpdates & PushedHistory & Pick<MessageEditing, "edit" | "delete" | "forward"> & Pick<MessageMedia, "download"> & MessageReactions & MessageStars & ReadState & Pick<ServerReads, "history"> & MarkdownFormatting & PollAdapter & GroupAdapter & PrivacyAdapter & MessagePins & SettingsAdapter;
+export declare const whatsAppAdapter: (engine: WhatsAppEngine, stored?: StoredMessages, words?: Words, 
+/** Where a skipped pushed event is said — a warning, so `--quiet` drops it. The diagnostic stream if not given. */
+warn?: (message: string) => void) => WhatsAppAdapter;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,kBAAkB,EAKxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,SAAS,EAGT,WAAW,EACX,cAAc,EACf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,aAAa,CAAA;AAGnD,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,aAAa,CAAA;AAE7D,OAAO,EAAE,KAAK,WAAW,EAA2C,MAAM,YAAY,CAAA;AAEtF,MAAM,MAAM,eAAe,GAAG,aAAa,GACzC,WAAW,GACX,aAAa,GACb,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC,GACnD,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAC9B,gBAAgB,GAChB,SAAS,GACT,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5B,kBAAkB,GAClB,WAAW,GACX,YAAY,CAAA;AAsId,eAAO,MAAM,eAAe,WAClB,cAAc,WACd,cAAc,UACf,KAAK,KACX,eA+PF,CAAA"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EAGT,WAAW,EACX,cAAc,EACf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,aAAa,CAAA;AAa7D,OAAO,EAAE,KAAK,WAAW,EAA2C,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,KAAK,cAAc,EAAkB,MAAM,cAAc,CAAA;AAClE,OAAO,EAAuB,KAAK,eAAe,EAAkC,MAAM,eAAe,CAAA;AAEzG,MAAM,MAAM,eAAe,GAAG,aAAa,GACzC,WAAW,GACX,cAAc,GACd,aAAa,GACb,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC,GACnD,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAC9B,gBAAgB,GAChB,YAAY,GACZ,SAAS,GACT,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5B,kBAAkB,GAClB,WAAW,GACX,YAAY,GACZ,cAAc,GACd,WAAW,GACX,eAAe,CAAA;AAqMjB,eAAO,MAAM,eAAe,WAClB,cAAc,WACd,cAAc,UACf,KAAK;AACZ,mHAAmH;OAC7G,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC9B,eAwcF,CAAA"}