From a9fa44d39effdd109a857d50a8f82f56d833048c Mon Sep 17 00:00:00 2001
From: Luna <clawy@reversed.dev>
Date: Wed, 6 May 2026 10:45:19 +0200
Subject: [PATCH] Initial commit: publish wacli skill

---
 README.md              |  12 +++++
 SKILL.md               | 119 +++++++++++++++++++++++++++++++++++++++++
 scripts/wacli-local.sh |   3 ++
 3 files changed, 134 insertions(+)
 create mode 100644 README.md
 create mode 100644 SKILL.md
 create mode 100755 scripts/wacli-local.sh

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37c6303
--- /dev/null
+++ b/README.md
@@ -0,0 +1,12 @@
+# wacli-skill
+
+Agent skill for using the local `wacli` WhatsApp CLI instead of browser automation.
+
+## Contents
+
+- `SKILL.md` — skill instructions and command patterns
+- `scripts/wacli-local.sh` — tiny wrapper that execs the local `wacli` binary
+
+## Source
+
+Published from Luna's local OpenClaw workspace.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..f1a9995
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: wacli
+description: Build and use the local wacli WhatsApp CLI for QR pairing, syncing, chat/message reads, and sending messages without browser DOM automation.
+---
+
+# wacli
+
+Use this when the task is about WhatsApp via the local `wacli` CLI instead of WhatsApp Web DOM automation.
+
+## What it is
+
+`wacli` is built locally from `/root/projects/wacli` and the binary lives at:
+
+- `/root/projects/wacli/dist/wacli`
+
+Local Go 1.25 was installed at:
+
+- `/usr/local/go1.25.0/bin/go`
+
+## Use this, not the browser, when
+
+- you need to pair WhatsApp with a QR code
+- you need to list chats
+- you need to read recent messages from the local sync store
+- you need to search messages offline
+- you need to send text, replies, reactions, or files
+
+## Safe defaults
+
+- For read-only inspection, prefer `--json --read-only`.
+- For sending or syncing, omit `--read-only`.
+- Prefer machine-readable output for agent use.
+- The default store is `/root/.local/state/wacli`.
+- Prefer `wacli` from PATH now that it is installed globally.
+- Prefer the CLI over WhatsApp Web DOM automation whenever the task is supported by `wacli`.
+
+## Command patterns
+
+### Read-only status
+
+```bash
+wacli --json --read-only auth status
+wacli --json --read-only doctor
+```
+
+### Pair/login
+
+```bash
+wacli auth
+```
+
+Notes:
+- `auth` is the command that shows the QR code and bootstraps initial sync.
+- `sync` never shows a QR; it only works after auth succeeds.
+
+### Sync
+
+```bash
+wacli sync --follow
+wacli sync --once
+```
+
+Notes:
+- `sync --once` really connects, syncs, then exits after an idle window.
+- `sync` warns when local storage is uncapped; prefer `--max-messages` or `--max-db-size` for long-running use.
+
+### Chats
+
+```bash
+wacli --json --read-only chats list --limit 50
+wacli --json --read-only chats show --jid <chat-jid>
+```
+
+Real-world note:
+- After auth + sync, chat metadata and recent timestamps are available offline from the local DB.
+
+### Messages
+
+```bash
+wacli --json --read-only messages list --chat <chat-jid> --limit 20
+wacli --json --read-only messages search "<query>"
+wacli --json --read-only messages context --chat <chat-jid> --id <message-id> --before 3 --after 3
+```
+
+Real-world note:
+- `messages context` is good enough to inspect a reply chain around a specific message without opening WhatsApp Web.
+
+### Send
+
+```bash
+wacli send text --to <recipient> --message "..."
+wacli send file --to <recipient> --file <path> --caption "..."
+wacli send react --to <recipient> --id <message-id> --reaction "👍"
+```
+
+Recipients can be:
+- JID
+- phone number
+- synced contact/group/chat name
+
+If a name is ambiguous, use a JID or add selection flags supported by `wacli`.
+
+Known local alias:
+- `jonna` → Jonna
+
+## Agent notes
+
+- For new environments, verify the binary exists before using it.
+- If a build is needed again, use Go 1.25 from `/usr/local/go1.25.0/bin`.
+- If module fetches fail because of flaky DNS, retry before assuming the repo is broken.
+- Do not claim messages are available until a real auth + sync happened.
+
+## Useful verification
+
+```bash
+wacli version
+wacli auth status
+wacli doctor
+```
diff --git a/scripts/wacli-local.sh b/scripts/wacli-local.sh
new file mode 100755
index 0000000..097197e
--- /dev/null
+++ b/scripts/wacli-local.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec /root/projects/wacli/dist/wacli "$@"