@floomhq/signaldash 0.11.2 → 0.13.0

package/README.md

@@ -11,6 +11,14 @@ the server's Unipile access key.
 You need Node.js 20 or newer and a single-use SignalDash invite code. Ask the
 SignalDash administrator for an invite code, then run:
 
+```bash
+npx -y @floomhq/signaldash <invite-code>
+```
+
+This agent-first setup logs in, installs the bundled operating skill, registers
+the MCP server with Claude Code when available, and prints hosted-auth links for
+the human to complete. The equivalent manual sequence is:
+
 ```bash
 npx -y @floomhq/signaldash login <invite-code>
 npx -y @floomhq/signaldash connect linkedin
@@ -74,18 +82,22 @@ The MCP server uses the user token created by `login`. It cannot access a
 LinkedIn, WhatsApp, or email account until that channel has been connected for
 the same logged-in user.
 
-## Give the agent the safety skill
+## Give the agent the operating skill
+
+The canonical [`signaldash` skill](skills/signaldash/SKILL.md) teaches an agent
+when to use SignalDash, how to persist the skill, complete setup, interpret
+connection state, operate every tool, handle server guards, and run safe worked
+flows. It is also served as raw Markdown for agents at:
 
-Before allowing the agent to send messages, give it the bundled
-[`signaldash-safe-usage` skill](skills/signaldash-safe-usage/SKILL.md). The
-skill requires the agent to resolve the exact chat, read recent thread
-history, check for duplicates, and obtain approval when the recipient or text
-has not already been approved.
+```text
+https://signaldash.dev/SKILL.md
+```
 
-The MCP registration does not automatically load the skill yet. Copy
-`skills/signaldash-safe-usage/SKILL.md` into the agent's skills directory or
-attach its contents to the agent instructions. Keep this requirement in both
-Claude Code and Cursor.
+The one-command setup installs the bundled copy into Claude Code. Other clients
+must save the skill in their documented skill directory and reload skill
+discovery. The narrower
+[`signaldash-safe-usage` skill](skills/signaldash-safe-usage/SKILL.md) remains
+available for clients that separate operating and send-safety instructions.
 
 ## MCP tools
 
@@ -100,13 +112,23 @@ SignalDash exposes:
 - `email_list(limit)`
 - `email_read(thread_id, limit)`
 - `email_send(to, subject, body)`
+- `li_my_posts(limit, member_id)`
+- `li_post_reactions(post_id, limit)`
+- `li_post_comments(post_id, limit)`
+- `li_draft_post(text, publish)`
 
 Every operation runs through the hosted SignalDash backend. Agents never
 receive the Unipile access key.
 
+The CLI also provides a paced, resumable LinkedIn connections export:
+
+```bash
+npx -y @floomhq/signaldash connections linkedin-connections.csv
+```
+
 ## Safety limits
 
-SignalDash enforces a daily send cap. The safe-usage skill adds the human
+SignalDash enforces a daily send cap. The operating skill adds the human
 workflow around that runtime control:
 
 - Every successful send includes `rate_limit.limit`, `used`, `remaining`, and

package/bin/sd.mjs

@@ -22,6 +22,9 @@ async function ui() {
 }
 
 const DEFAULT_BACKEND = process.env.SIGNALDASH_BACKEND || "https://signaldash-api.floom.dev";
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
 
 function configPaths() {
   const directory = process.env.SIGNALDASH_HOME || `${homedir()}/.signaldash`;
@@ -70,9 +73,20 @@ export async function cmdLogin(code, backend, dependencies = {}) {
   cfg.backend = backend || cfg.backend || DEFAULT_BACKEND;
   saveCfg(cfg);
   const r = await request("/login", { code }, { auth: false });
-  if (r.status !== 200) { error("login failed:", r.json.error || r.status); process.exitCode = 1; return; }
+  if (r.status !== 200) {
+    const msg = String(r.json.error || r.status);
+    if (/used|invalid/i.test(msg) && loadCfg().token) {
+      log("You are already set up on this machine. Run `signaldash status` to see what is connected.");
+      return;
+    }
+    error("login failed:", msg);
+    if (/used/i.test(msg)) error("Invite codes are single-use. If you already ran this, try: signaldash status");
+    process.exitCode = 1; return;
+  }
   cfg.token = r.json.token; saveCfg(cfg);
-  log("Logged in to SignalDash. Token stored (no channel keys on your side).");
+  log(`Logged in to SignalDash (${cfg.backend}).`);
+  log("Your LinkedIn/WhatsApp/email credentials live on that server, not on this");
+  log("machine, and are never exposed to your agent. Only you can see your data.");
 }
 
 export async function cmdLogout(dependencies = {}) {
@@ -378,6 +392,22 @@ export async function cmdConnections(outPath, dependencies = {}) {
   if (!done) log("  " + chalk.dim("sync still running; run this again later to get the rest"));
 }
 
+
+function printHelp(log = console.log) {
+  log(`SignalDash \u2014 secure LinkedIn, WhatsApp and email access for your AI agent.
+
+  signaldash <invite-code>              set up everything in one go
+  signaldash status                     show what is connected
+  signaldash connect linkedin|whatsapp|email
+  signaldash connections [file.csv]     export your LinkedIn connections
+  signaldash skill                      install the agent skill
+  signaldash mcp                        run the MCP server (used by your agent)
+  signaldash logout                     revoke this device
+
+Your channel credentials stay on the SignalDash server. They are never stored on
+this machine and never shown to your agent, which only holds a scoped token.`);
+}
+
 export async function main(argv = process.argv.slice(2), dependencies = {}) {
   const [cmd, a, b, c] = argv;
   const log = dependencies.log || console.log;
@@ -390,9 +420,10 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   else if (cmd === "mcp") await runMcp(dependencies);
   else if (cmd === "status") await cmdStatus(dependencies);
   else if (cmd === "connections" || (cmd === "export" && a === "connections")) await cmdConnections(cmd === "export" ? b : a, dependencies);
-  else if (cmd === "--version" || cmd === "-v") log("0.7.0");
-  else if (cmd && cmd !== "help" && !/^[0-9a-f]{8,}$/i.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
+  else if (cmd === "--version" || cmd === "-v") log(PACKAGE_VERSION);
   else if (cmd === "skill") await cmdSkill(dependencies);
+  else if (cmd === "logout") await cmdLogout(dependencies);
+  else if (cmd && !["help","--help","-h"].includes(cmd) && !/^[0-9a-f]{8,}$/i.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
   else printHelp(log);
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.11.2",
-  "description": "Secure LinkedIn and WhatsApp MCP access for AI agents",
+  "version": "0.13.0",
+  "description": "Secure LinkedIn, WhatsApp, and email access for AI agents",
   "type": "module",
   "bin": {
     "signaldash": "bin/sd.mjs"

package/skills/signaldash/SKILL.md

@@ -1,103 +1,638 @@
 ---
 name: signaldash
-description: Give this agent secure access to the user's LinkedIn, WhatsApp, and email accounts through SignalDash. Use whenever the user asks to check, read, triage, draft, reply to, or send LinkedIn/WhatsApp messages or email. Also covers first-time setup.
+description: Operate the user's SignalDash connection to LinkedIn, WhatsApp, and email. Use this skill whenever the user says or implies "check my LinkedIn", "who messaged me", "triage my inbox", "read the thread with X", "reply to X", "send this message", "check WhatsApp", "check my email", "draft a LinkedIn post", "who engaged with my post", "who liked or commented", or "export my LinkedIn connections". Covers durable installation, invite-based setup, connection diagnosis, safe reading, drafting, approved sends, post engagement analysis, and paced connection export.
 ---
 
-# SignalDash: LinkedIn, WhatsApp, and email for this agent
+# Operate SignalDash
 
-SignalDash is the gate between you and the user's real messaging accounts. The
-user's channel credentials live on the SignalDash server, never on their machine
-and never in your context. You act through SignalDash tools only.
+SignalDash gives this agent account-scoped access to the user's LinkedIn,
+WhatsApp, and email through a hosted service. Channel credentials remain on the
+SignalDash server. The local client stores only a scoped SignalDash session
+token.
 
-## Setup (run this when the SignalDash tools are not available yet)
+Treat SignalDash as an operating capability, not an API reference. Resolve the
+exact account object, read the relevant history, explain what you found, draft
+the action, obtain approval when required, act once, and verify the result.
 
-You are an agent, so there is no interactive terminal. Run the command, then
-RELAY THE LINKS TO THE HUMAN. They must click them; you cannot.
+## Before you set this up (say this to the human first)
+
+You are about to wire the user's REAL LinkedIn, WhatsApp and email into a
+persistent MCP server, on the strength of a link and a code someone sent them.
+Name that plainly before you run anything:
+
+> "This will connect your real LinkedIn/WhatsApp to an MCP server I'll register
+> locally, using an invite code from Federico (signaldash-api.floom.dev holds the
+> credentials, not this machine). I can read and draft messages; I won't send
+> anything without showing you the exact text first. OK to proceed?"
+
+Wait for a clear yes. If the user does not know who sent the link, or is unsure,
+stop and let them verify first. Do not soften this to get through setup faster.
+
+## Ensure the skill is saved and enabled
+
+Do this first when you are reading this file from a URL or pasted text. Do not
+rely on the current conversation to retain it.
+
+1. Save the complete, unmodified `SKILL.md` in a skill directory that the
+   current agent discovers. Prefer the agent's documented global directory so
+   the skill works in future projects. Common locations are:
+
+   - Claude Code: `~/.claude/skills/signaldash/SKILL.md`
+   - Codex: `~/.codex/skills/signaldash/SKILL.md`
+   - Portable project scope: `.agents/skills/signaldash/SKILL.md`
+
+2. When shell access is available, fetch the raw form explicitly:
+
+   ```bash
+   mkdir -p ~/.claude/skills/signaldash
+   curl -fsSL -H 'Accept: text/plain' https://signaldash.dev/SKILL.md \
+     -o ~/.claude/skills/signaldash/SKILL.md
+   test -s ~/.claude/skills/signaldash/SKILL.md
+   ```
+
+   Replace the destination with the current agent's canonical skill directory
+   when it is not Claude Code.
+
+3. Confirm that the saved file begins with `name: signaldash` and contains the
+   `Before every send` section. A partial copy is not installed.
+
+4. Enable or reload skills according to the current agent. Start a new agent
+   session when the client discovers skills only at startup. After SignalDash
+   setup, restart the MCP connection as well.
+
+5. The package can install its bundled copy for Claude Code:
+
+   ```bash
+   npx -y @floomhq/signaldash skill
+   ```
+
+   Expected success:
+
+   ```text
+   Installed the SignalDash skill to /home/user/.claude/skills/signaldash/SKILL.md
+   Your agent now knows how to use LinkedIn + WhatsApp safely through SignalDash.
+   ```
+
+Persisting the skill is part of setup. Do not continue with a session-only copy
+and tell the user setup is complete.
+
+## When to reach for SignalDash
+
+Use SignalDash without waiting for the user to name it when their request
+involves their connected messaging accounts or their own LinkedIn activity.
+Typical trigger phrases include:
+
+- "Check my LinkedIn", "who messaged me?", "anything unread?", "triage my
+  inbox", or "what needs a reply?"
+- "Read the thread with Amina", "reply to Marco", "send this on LinkedIn", or
+  "follow up with the person who asked about pricing."
+- "Check WhatsApp", "what did the team say?", "find my chat with Sara", or
+  "reply with this."
+- "Check my email", "summarize the thread", "draft a response", or "send the
+  approved email."
+- "Draft a post", "turn this into a LinkedIn post", or "publish this post."
+- "Who engaged with my last post?", "who liked it?", "what did people comment?",
+  or "which warm signals need action?"
+- "Export my connections", "download my LinkedIn network", or "make me a
+  connections CSV."
+
+Do not use SignalDash for public LinkedIn research, invitations, profile
+enrichment, scraping, bulk outreach, or a new email to someone with no existing
+thread. SignalDash exposes no LinkedIn invitation tool.
+
+## The operating model
+
+There are two surfaces:
+
+1. The CLI handles login, account connection, status, skill installation, MCP
+   startup, logout, and the paced LinkedIn connections export.
+2. MCP tools handle account reads, message sends, email, LinkedIn posts, and
+   post engagement.
+
+The CLI command used by the MCP registration is:
+
+```bash
+npx -y @floomhq/signaldash mcp
+```
+
+MCP tool results arrive as JSON text. An MCP result marked `isError: true`, an
+HTTP-style `code`, or an `error` field is not a successful action.
+
+## First-time setup
+
+The user needs a single-use SignalDash invite code from Federico. Ask the user
+for that code when none is present. Never invent one, search private files for
+one, or reuse somebody else's code.
+
+### 1. Run the one-command setup
+
+After the user provides the code, run:
 
 ```bash
 npx -y @floomhq/signaldash <invite-code>
 ```
 
-This logs in, installs this skill, registers the MCP server, and prints one
-`account.unipile.com` link per channel. Then:
-
-1. **Show the human the links** and tell them plainly: open this to connect
-   LinkedIn / WhatsApp. WhatsApp is a QR scan from WhatsApp > Linked Devices.
-2. After they say they have authenticated, confirm with:
-   `npx -y @floomhq/signaldash connect linkedin` (or `whatsapp`, or `email`)
-3. Check what is connected any time: `npx -y @floomhq/signaldash status`
-4. Restart the MCP connection (or the editor) so the tools load.
-
-If the human has no invite code, they need one from Federico. Without it,
-nothing else in this skill works.
-
-## Tools
-
-| Tool | What it does |
-|---|---|
-| `li_list_chats` | list the user's LinkedIn chats |
-| `li_read_messages` | read a LinkedIn thread (`chat_id`) |
-| `li_send_message` | send a LinkedIn message (`chat_id`, `text`) |
-| `wa_list_chats` | list the user's WhatsApp chats |
-| `wa_read_messages` | read a WhatsApp thread (`chat_id`) |
-| `wa_send_message` | send a WhatsApp message (`chat_id`, `text`) |
-| `email_list` | list the newest message from each recent email thread (`limit`) |
-| `email_read` | read an email thread (`thread_id`, `limit`) |
-| `email_send` | send one email (`to`, `subject`, `body`) |
-
-## Enforced by the server (you cannot bypass these)
-
-- **Read before send.** Sending to a chat you have not read recently returns
-  `428 read_before_send_required`. Call `*_read_messages` on that chat first.
-  Email sends require a recent `email_read` whose thread contains the exact
-  recipient address.
-- **No double-send.** An identical message to the same chat returns
-  `409 duplicate_send`. The same guard fingerprints email recipient, subject,
-  and body.
-- **Daily send cap + pacing.** Exceeding it returns `429 rate_limit_exceeded`.
-
-These are server-side guards, not suggestions. Do not try to work around them.
-
-## The rules you MUST follow
-
-These protect the user's accounts from being restricted or banned, and protect
-them from you sending something wrong. They are not optional.
-
-1. **Never send without the user's explicit approval of the exact recipient and
-   exact text.** Draft it, show it, wait. Discussion is not approval.
-2. **Read the thread before you send.** Always `*_read_messages` on that exact
-   chat or `email_read` on the exact mail thread first: check who it is, what
-   they last said, and whether this was already sent. Never send blind. Never
-   double-send.
-3. **Never bulk.** No mass messaging, no "message everyone who…", no bulk
-   profile fetching. LinkedIn restricts accounts for exactly this. Hard ceiling
-   is roughly 15-20 LinkedIn sends per day; the server enforces a daily cap and
-   spacing, do not try to work around it or parallelize sends.
-4. **One message at a time, human pace.** Let the server's pacing do its work.
-5. **Stop on any warning.** A checkpoint, restriction, "unusual activity"
-   prompt, 403 or 429 means halt all activity on that account and tell the user.
-   Do not retry.
-6. **Personalize.** Read the thread and write a specific reply. Templated
-   identical messages get reported as spam.
-
-## Email-specific rules
-
-- `email_send` accepts exactly one recipient. Do not split bulk sends into
-  repeated calls.
-- Obtain explicit approval for the exact recipient, subject, and body.
-- Read the recipient's recent thread immediately before sending. If there is no
-  existing thread, do not send through SignalDash.
-- Stop on provider authentication errors, HTTP 403, or HTTP 429. Do not retry an
-  ambiguous timeout until the mailbox and sent history have been re-read.
-
-## Good vs bad requests
-
-Good: "list my unread LinkedIn chats and draft replies for my approval" ·
-"read the thread with Mircea and suggest an answer" · "what came in on WhatsApp
-from people I've spoken to before?"
-
-Bad (refuse or push back): "connection-request everyone who liked my post" ·
-"message all my connections about X" · "pull every profile in my network".
-
-Rule of thumb: if a human could not plausibly do it by hand in a day, do not do
-it. Account health beats throughput.
+The invite is a hexadecimal string. The command logs in, installs the bundled
+skill, registers the MCP server with Claude Code when available, and begins
+LinkedIn and WhatsApp connection.
+
+Expected initial output resembles:
+
+```text
+SignalDash  secure LinkedIn + WhatsApp access for your agent
+
++ logged in
++ agent skill installed
++ MCP registered with Claude Code
+
+Opening your browser. If it does not open, use this link:
+https://account.unipile.com/...
+
+ACTION REQUIRED (human): open the link above to connect linkedin.
+Then run: npx @floomhq/signaldash connect linkedin
+```
+
+In a non-interactive agent shell, the command prints hosted-auth links. The
+agent cannot complete those pages, sign in as the user, or scan a WhatsApp QR
+code.
+
+### 2. Relay every printed link to the human
+
+Tell the user which provider each link connects and what human action it needs:
+
+- LinkedIn: open the hosted-auth link and finish LinkedIn authentication.
+- WhatsApp: open the link and scan the live QR code from WhatsApp > Linked
+  Devices.
+- Email: run `npx -y @floomhq/signaldash connect email`, relay its link, and let
+  the human choose Google, Outlook, or IMAP when available.
+
+Do not hide a link in a summary. Send the full URL in a clickable form. Do not
+click, scan, enter passwords, or claim connection on the user's behalf.
+
+### 3. Verify with status
+
+After the human says authentication is complete, run:
+
+```bash
+npx -y @floomhq/signaldash status
+```
+
+`status` is the source of truth after every `connect` attempt.
+
+Connected output:
+
+```text
+SignalDash  https://signaldash-api.floom.dev
++ linkedin  Federico De Ponte
++ whatsapp  Federico
+- email     not connected
+```
+
+Not-connected output:
+
+```text
+SignalDash  https://signaldash-api.floom.dev
+- linkedin  not connected
+- whatsapp  not connected
+- email     not connected
+```
+
+A `connect` command printing another hosted-auth URL, even one that looks
+identical to the previous output, does not prove the provider is connected.
+Only the `+ <provider> <name>` line from `status`, or a direct
+`Connected <provider>: <name>` result, proves connection.
+
+### 4. Continue or diagnose each provider
+
+Note: the one-command setup connects LinkedIn and WhatsApp. Email is opt-in and
+needs its own call: `npx -y @floomhq/signaldash connect email`.
+
+Run a missing provider explicitly:
+
+```bash
+npx -y @floomhq/signaldash connect linkedin
+npx -y @floomhq/signaldash connect whatsapp
+npx -y @floomhq/signaldash connect email
+```
+
+Interpret output as follows:
+
+- Success: `Connected linkedin: <name>` or `status` shows `+ linkedin`.
+- Pending human action: a hosted-auth URL plus `ACTION REQUIRED (human)`.
+  Relay the URL and wait for the human to finish.
+- Still pending in an interactive terminal: `Not connected yet. The link above
+  stays valid...`. Do not treat the timeout as a failed login and do not create
+  a rapid loop of new links.
+- Login failure: `Not logged in. Run: signaldash login <invite-code>` or
+  `login failed: ...`. Stop and resolve the session or invite.
+- Provider failure: `connect failed: ...` or `connect status failed: ...`.
+  Report the exact error without claiming connection.
+
+If automatic account detection cannot bind the newly authenticated account,
+the CLI prints this manual fallback:
+
+```bash
+npx -y @floomhq/signaldash connect linkedin claim <account_id>
+```
+
+Use `claim` only with the exact account ID produced for this user's just-created
+connection. Never guess an account ID.
+
+### 5. Reload and prove tool availability
+
+Restart the MCP connection or agent session after registration. Confirm the
+expected SignalDash tools are present, then perform a read-only check such as:
+
+```text
+li_list_chats({"limit": 5})
+```
+
+If the tools are missing but `status` is connected, the account is ready and
+the MCP client is not loaded. Fix the MCP registration or restart the client;
+do not reconnect the account.
+
+## Numbered workflow for every account task
+
+Use this sequence unless the request is read-only and ends before approval:
+
+1. **Confirm connection.** Run `npx -y @floomhq/signaldash status` when channel
+   state is unknown. A connected status is required.
+2. **Choose the narrowest list tool.** List recent chats, email threads, or the
+   user's recent posts. Use a modest limit.
+3. **Resolve the exact object.** Match the full chat name, thread, or post.
+   When names collide or identity is unclear, show the candidates and ask the
+   user. Never infer from a partial name.
+4. **Read before interpreting.** Read enough recent history to understand the
+   latest inbound message, earlier context, and existing outbound messages.
+   For sends, read at least 10 recent items and use the exact chat or thread.
+5. **Return findings or draft.** Summarize concrete facts. Separate suggested
+   replies from messages already sent.
+6. **Obtain explicit approval.** Before any message or public post, show the
+   exact channel, recipient, and complete text. For email include subject and
+   body. Discussion, editing, "looks good", or approval of a different draft is
+   not approval of the final action.
+7. **Re-read immediately before sending.** Re-read the exact thread to catch a
+   human reply, a manual send, or a duplicate that appeared after drafting. If
+   context changed, revise and obtain approval again.
+8. **Act once.** Send one approved message or publish one approved post. Never
+   parallelize sends and never loop over recipients.
+9. **Verify.** Read the exact thread again after a successful send. Confirm the
+   outbound text is present once. If the outcome was ambiguous, re-read before
+   any retry.
+10. **Report guard state.** Include rate-limit remaining/reset information when
+    returned. Stop on warnings, 403, or 429.
+
+Expected states:
+
+- Read/list success: JSON containing `items`, often with a `cursor`.
+- Draft success: `{"drafted":true,"published":false,...}`.
+- Send success: provider result plus `rate_limit`, often including a message ID.
+- Validation failure: `invalid_request` or a clear required-argument error.
+- Safety rejection: 428, 409, or 429 as documented below.
+- Provider warning/restriction: stop all activity on that account.
+
+## Where your session lives
+
+The CLI stores a SignalDash session token at `~/.signaldash/config.json`
+(mode 0600). It is a scoped SignalDash token, NOT a LinkedIn/WhatsApp/email
+credential: those stay on the server. Override the location with
+`SIGNALDASH_HOME=/path` (useful for sandboxing or multiple accounts). Revoke a
+device with `npx -y @floomhq/signaldash logout`.
+
+## Tool catalog
+
+Use the exact tool names and argument keys below. Limits are optional.
+
+| Tool | Arguments | When to use it |
+|---|---|---|
+| `li_list_chats` | `limit` integer 1-100, default 20 | Find recent LinkedIn chats, unread counts, and exact `chat_id` values without opening profiles. |
+| `li_read_messages` | `chat_id` required; `limit` 1-100, default 30 | Read one resolved LinkedIn conversation before summarizing, drafting, or sending. |
+| `li_send_message` | `chat_id` required; `text` required, max 5000 characters | Send one approved LinkedIn reply after an immediate read of that exact chat. |
+| `wa_list_chats` | `limit` integer 1-100, default 20 | Find an existing WhatsApp conversation and exact `chat_id`. |
+| `wa_read_messages` | `chat_id` required; `limit` 1-100, default 30 | Verify a WhatsApp contact and recent history before summarizing, drafting, or sending. |
+| `wa_send_message` | `chat_id` required; `text` required, max 5000 characters | Send one approved reply in an existing WhatsApp conversation after an immediate re-read. |
+| `email_list` | `limit` integer 1-100, default 20 | List the newest message in each recent email thread and obtain `thread_id`. |
+| `email_read` | `thread_id` required; `limit` 1-100, default 30 | Read an email thread and authorize its exact participant addresses for a later send. |
+| `email_send` | `to` required as an array of exactly one valid address; `subject` required, max 998; `body` required, max 5000 | Send one approved email to a participant in a recently read existing thread. |
+| `li_my_posts` | `limit` default 10, max 50; `member_id` optional | Find the user's latest posts and post IDs. Omit `member_id` to use the connected user's own ID. |
+| `li_post_reactions` | `post_id` required; `limit` default 50, max 100 | Identify who reacted to one post and assess warm signals. A reaction does not authorize outreach. |
+| `li_post_comments` | `post_id` required; `limit` default 50, max 100 | Read comments and authors for one post; prioritize questions and substantive responses. |
+| `li_draft_post` | `text` required, max 3000; `publish` optional, default false | Create a server-confirmed draft. Use `publish:true` only after explicit approval of the final public text. |
+
+Representative calls:
+
+```text
+li_list_chats({"limit":20})
+li_read_messages({"chat_id":"chat_li_7f3a","limit":20})
+li_send_message({"chat_id":"chat_li_7f3a","text":"Yes. I’ll send it this afternoon."})
+wa_list_chats({"limit":20})
+wa_read_messages({"chat_id":"chat_wa_91b2","limit":20})
+wa_send_message({"chat_id":"chat_wa_91b2","text":"16:30 works. See you then."})
+email_list({"limit":20})
+email_read({"thread_id":"thread_email_c402","limit":30})
+email_send({"to":["amina@example.com"],"subject":"Re: Case study","body":"Hi Amina,\n\nHere is the case study."})
+li_my_posts({"limit":5})
+li_post_reactions({"post_id":"post_urn_8821","limit":50})
+li_post_comments({"post_id":"post_urn_8821","limit":50})
+li_draft_post({"text":"Most agents need better context, not more autonomy."})
+```
+
+List and read success returns JSON with `items` and often a `cursor`. A message
+send success returns a provider message ID and `rate_limit` data. The draft
+result is deterministic:
+
+```json
+{
+  "drafted": true,
+  "published": false,
+  "text": "Most agents need better context, not more autonomy.",
+  "note": "Draft only. Re-send with publish:true after the human approves."
+}
+```
+
+Publishing is public and irreversible. Never interpret "draft a post" as
+permission to publish. `email_send` cannot start a cold thread and must never be
+looped over recipients.
+
+### LinkedIn connections export via CLI
+
+This is the fourteenth operation. It is intentionally a paced CLI workflow, not
+an MCP bulk-read tool.
+
+```bash
+npx -y @floomhq/signaldash connections linkedin-connections.csv
+```
+
+Use it when the user asks to export or download their LinkedIn connections.
+The server retrieves one page at a time in a resumable background sync. Do not
+replace it with per-profile reads or parallel requests.
+
+Progress and success resemble:
+
+```text
+Syncing connections (paced to keep your account safe)...
+Synced 300 connections (3 pages)...
+842 connections
++ saved linkedin-connections.csv
+```
+
+If the sync pauses, the CLI can save the rows fetched so far and prints that
+the sync is still running. Running the same command later resumes it. If it
+prints `nothing fetched yet, run again later to resume`, no CSV was produced
+and the command exits with failure.
+
+## Server-enforced guards: these will reject you
+
+These controls run on the server. Prompt instructions, a new session, or a
+different calling order cannot bypass them.
+
+### 428 `read_before_send_required`
+
+Meaning: this user has not successfully read the exact chat recently, or the
+email recipient was not present in a recently read thread. The default read
+window is 30 minutes.
+
+Comply:
+
+1. Call the matching read tool on the exact chat or email thread.
+2. Inspect at least the last 10 items for identity, context, and duplicates.
+3. If the context changed, revise the draft and obtain approval again.
+4. Send once while the read is recent.
+
+Do not satisfy this guard by reading a different chat with a similar name.
+
+### 409 `duplicate_send`
+
+Meaning: the exact message was already sent to that chat, or the exact email
+recipient, subject, and body combination was already sent.
+
+Comply:
+
+1. Do not retry.
+2. Re-read the exact thread or sent history.
+3. Tell the user when the matching outbound item was sent, using `sent_at` when
+   returned.
+4. Draft different text only when the user has a genuine follow-up intent, then
+   obtain new approval.
+
+Changing whitespace or punctuation to evade the duplicate guard is prohibited.
+
+### 429 `rate_limit_exceeded`
+
+Meaning: the persisted daily action cap is exhausted. The response includes
+`rate_limit.limit`, `used`, `remaining`, and `resets_at`, plus `Retry-After` and
+matching rate-limit headers.
+
+Comply:
+
+1. Stop all sends on that account.
+2. Report the limit and reset time.
+3. Wait until the reset. Do not switch tokens, sessions, channels, or machines
+   to work around the cap.
+4. Do not queue a burst for the reset boundary.
+
+Any upstream 429, provider warning, checkpoint, restriction, unusual-activity
+prompt, or HTTP 403 also means stop. Do not retry.
+
+## Before every send
+
+These rules apply to LinkedIn, WhatsApp, email, and public LinkedIn posts.
+
+1. Never send or publish without explicit human approval of the exact
+   recipient or audience and the exact final text.
+2. Read the exact thread immediately before the action. Check the recipient,
+   latest inbound message, prior context, and whether the proposed text already
+   exists as an outbound item.
+3. Never infer a recipient from a partial name. Resolve duplicate names with
+   the user.
+4. Never bulk-send, fan out, loop over people, or parallelize actions.
+5. Never turn reactions, comments, connections, or exported rows into an
+   unsolicited outreach list.
+6. Send one message at human pace. Let server pacing finish.
+7. Stop on a provider warning, checkpoint, restriction, authentication
+   anomaly, delivery anomaly, HTTP 403, or HTTP 429.
+8. Never retry an ambiguous timeout before re-reading the exact thread or sent
+   history. A timeout can hide a successful send.
+9. Confirm delivery by reading the thread after the action.
+10. Account health outranks throughput and task completion.
+
+The hosted backend defaults to 20 action attempts per authenticated user per
+UTC day, shared across message sends, email sends, and post publishing. A
+deployment can configure a different cap. Never promise a particular remaining
+allowance until the response reports `rate_limit.limit` and `remaining`.
+
+## Worked flows
+
+### Flow 1: triage unread LinkedIn chats and draft replies
+
+User: "Check my unread LinkedIn chats and draft replies."
+
+1. Confirm LinkedIn is connected with `signaldash status` when unknown.
+2. Call:
+
+   ```text
+   li_list_chats({"limit":20})
+   ```
+
+3. Select only items with `unread_count > 0`. Do not claim that the list tool
+   alone contains full conversation context.
+4. Read each selected conversation one at a time:
+
+   ```text
+   li_read_messages({"chat_id":"chat_li_7f3a","limit":20})
+   ```
+
+5. Return a compact triage:
+
+   ```text
+   Amina Rahman, 2 unread
+   Last message: asks for the case study.
+   Suggested reply: "Yes. I’ll send it over this afternoon."
+
+   Marco Silva, 1 unread
+   Last message: confirms Tuesday at 10:00.
+   Suggested reply: "Tuesday at 10:00 works. See you then."
+   ```
+
+6. Stop. Drafting is not sending. Ask for approval of each exact reply.
+7. For any approved reply, re-read that exact chat, send once, and read again
+   to verify. Do not send all drafts in a loop.
+
+### Flow 2: find who engaged with the last post and recommend action
+
+User: "Who engaged with my last LinkedIn post, and what should I do?"
+
+1. Call:
+
+   ```text
+   li_my_posts({"limit":5})
+   ```
+
+2. Select the newest post by its provider timestamp, not by list position when
+   timestamps disagree. Record its exact `post_id`.
+3. Call:
+
+   ```text
+   li_post_reactions({"post_id":"post_urn_8821","limit":50})
+   li_post_comments({"post_id":"post_urn_8821","limit":50})
+   ```
+
+4. Group the result:
+
+   - Direct questions in comments: respond publicly or draft a reply.
+   - Existing contacts with substantive engagement: warm follow-up candidate,
+     but no message without thread verification and approval.
+   - Reactions without context: signal only, no automatic outreach.
+   - Spam or irrelevant engagement: no action.
+
+5. Return names, the evidence for prioritization, and proposed next actions.
+   Do not invent profile facts absent from the result.
+6. If the user asks to message one person, locate the exact existing chat,
+   read it, draft a contextual message, obtain exact approval, re-read, and
+   send once. SignalDash cannot invite or mass-message reactors.
+
+### Flow 3: find and reply to a WhatsApp thread
+
+User: "Find my WhatsApp thread with Sara and reply that 16:30 works."
+
+1. Call:
+
+   ```text
+   wa_list_chats({"limit":20})
+   ```
+
+2. Resolve the exact Sara. If multiple chats or group/direct variants match,
+   show the candidates and ask which one.
+3. Read:
+
+   ```text
+   wa_read_messages({"chat_id":"chat_wa_91b2","limit":20})
+   ```
+
+4. Confirm that the latest context is about scheduling and draft:
+
+   ```text
+   Recipient: Sara Conti, WhatsApp
+   Text: "16:30 works for me. See you then."
+   ```
+
+5. Ask for exact approval unless the user's original request already approved
+   that exact recipient and exact final text. Paraphrasing the user's words
+   creates a new draft that needs approval.
+6. Immediately re-read `chat_wa_91b2`.
+7. Send once:
+
+   ```text
+   wa_send_message({
+     "chat_id":"chat_wa_91b2",
+     "text":"16:30 works for me. See you then."
+   })
+   ```
+
+8. Read the chat again and confirm the text appears once as an outbound
+   message.
+
+### Flow 4: export LinkedIn connections
+
+User: "Export my LinkedIn connections to CSV."
+
+1. Confirm LinkedIn is connected.
+2. Choose a user-visible output path. Never overwrite an existing file without
+   explicit authorization.
+3. Run:
+
+   ```bash
+   npx -y @floomhq/signaldash connections linkedin-connections.csv
+   ```
+
+4. Let the paced sync run. Do not start another export in parallel.
+5. Success is the `+ saved <path>` line and a non-empty CSV with this header:
+
+   ```text
+   name,headline,public_id,profile_url,connected_at
+   ```
+
+6. Report the saved path and row count. If the CLI reports a paused or partial
+   sync, say that the export is partial and rerun later to resume.
+
+## Read-only requests and drafts
+
+Read-only work does not require send approval. You can list, read, summarize,
+analyze engagement, and create a non-published post draft as requested. Still
+use narrow limits, protect private content, and avoid bulk collection.
+
+For every draft, label it clearly as a draft. Never present a suggested reply
+as sent. Never present `{"drafted":true,"published":false}` as a published post.
+
+## Logout
+
+When the user explicitly asks to disconnect this local SignalDash session, run:
+
+```bash
+npx -y @floomhq/signaldash logout
+```
+
+Success:
+
+```text
+Logged out of SignalDash. The session was revoked.
+```
+
+Logout revokes the current SignalDash session and removes its local token. It
+does not authorize deleting provider accounts or messages.
+
+## Final checklist
+
+Before reporting completion, verify:
+
+- The skill is persisted in a discovered skill directory.
+- `status` proves the required provider is connected.
+- The exact chat, thread, post, or export path was resolved.
+- Every send used a fresh exact-thread read and exact human approval.
+- No duplicate, bulk, parallel, warning, 403, or 429 path was bypassed.
+- A send was confirmed by a post-send read.
+- A post draft remained unpublished unless `publish:true` was explicitly
+  approved.
+- An export ended with `+ saved` and a non-empty CSV.
+
+If any item is unverified, state exactly what remains incomplete.