@floomhq/signaldash 0.13.0 → 0.22.0

package/skills/signaldash/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: signaldash
-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.
+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", "send a connection request", "create an invitation batch", "check invitations", "accept this invitation", "auto-accept my invitations", "check auto-accept status", "withdraw this invitation", "search my LinkedIn connections", "find people in my network", "find people beyond my network", "suppress this contact", "check contact state", "check my action budget", "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, local-first connection search, capped paid discovery, immutable human-approved invitation batches, opt-in rate-capped invitation auto-accept, exact contact state and suppression, authoritative LinkedIn action-budget status, safe reading, drafting, approved sends, exact invitation actions, post engagement analysis, and paced connection export.
 ---
 
 # Operate SignalDash
@@ -91,14 +91,41 @@ Typical trigger phrases include:
 - "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."
+- "Send a connection request to this exact person", "check my invitations",
+  "accept this invitation", or "withdraw this pending invitation."
+- "How many LinkedIn actions remain?", "check my action budget", or "can a
+  campaign act today?"
+- "Auto-accept my LinkedIn invitations", "turn invitation auto-accept off", or
+  "did auto-accept hit any errors?" Use the persistent per-user setting and
+  status tools; it is off until explicitly enabled.
+- "Search my LinkedIn connections", "find founders in my network", or "who at
+  Acme am I connected to?" Use the local connection snapshot before any
+  external or paid discovery.
+- "Find platform engineers beyond my network" or "discover people at Acme in
+  Berlin." Use `li_discover_people` only after the completed local snapshot
+  returns no matches. Preview the exact paid request and cost before confirming
+  one capped provider page.
+- "Schedule this message", "follow up automatically", or "send these as a
+  sequence." Explain the narrow campaign time boundary below; do not invent a
+  queue or claim those unsupported actions were scheduled.
+- "Create a LinkedIn invitation batch for these exact profiles." Structure the
+  human's request into exact URLs, reasons, and notes, create the immutable
+  preview, and relay its human review path. Never approve through MCP.
 - "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.
+Do not use SignalDash for general public LinkedIn research, full-profile
+enrichment, email finding, unreviewed bulk outreach, unapproved automatic
+invitation processing, or a new email to someone with no existing thread.
+`li_discover_people` is the narrow exception for one capped page of public
+search cards after own-network search. Its results are planning evidence only.
+Invitation tools act on one exact provider member or invitation at a time and
+never authorize a list-wide loop. The only automatic incoming-invitation
+exception is the explicitly enabled, filterable, rate-capped auto-accept worker.
+The only multi-target outbound exception is an immutable 1–10-target invitation
+batch with separate exact browser approval and server-controlled execution.
 
 ## The operating model
 
@@ -106,8 +133,10 @@ 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.
+2. MCP tools handle account reads, local connection search, capped paid
+   discovery, message sends, immutable invitation-batch create/inspect/cancel,
+   exact LinkedIn invitation actions, email, LinkedIn posts, and post
+   engagement.
 
 The CLI command used by the MCP registration is:
 
@@ -257,23 +286,30 @@ 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.
+2. **Choose the narrowest list or preview tool.** List recent chats, email
+   threads, invitation inboxes, or the user's recent posts. Preview an outbound
+   invitation through `li_send_invitation` with `confirm` omitted. Use a modest
+   limit.
+3. **Resolve the exact object.** Match the full chat name, thread, invitation,
+   provider member, 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.
+   For message sends, read at least 10 recent items and use the exact chat or
+   thread. For invitation maintenance, list the exact current invitation. For
+   a new invitation, inspect the server-confirmed exact target and note preview.
 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.
+7. **Re-read immediately before acting.** Re-read the exact thread or current
+   invitation list to catch a human action, reply, duplicate, acceptance, or
+   withdrawal that appeared after drafting. New invitation sends repeat the
+   exact previewed payload with `confirm:true`; the server rechecks relationship
+   and pending invitation state.
 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
@@ -308,6 +344,21 @@ Use the exact tool names and argument keys below. Limits are optional.
 | `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. |
+| `li_send_invitation` | `provider_id` required; `note` optional, max 300 exact characters; `confirm` optional, default false | First preview one exact target and note. The server verifies relationship, both invitation directions, and absence of an existing one-to-one chat. After exact approval, repeat the identical call with `confirm:true`; jitter completes before the final preflight and action reservation. |
+| `li_invitations_received` | `limit` integer 1-100, default 50; `cursor` optional | List one bounded page of received invitations. This read authorizes only the exact returned invitation IDs for a later accept. |
+| `li_accept_invitation` | `invitation_id` required; `confirm:true` required | Accept one exact currently pending received invitation after a fresh `li_invitations_received` read and approval. |
+| `li_invitations_sent` | `limit` integer 1-100, default 50; `cursor` optional | List one bounded page of sent invitations. This read authorizes only the exact returned invitation IDs for a later withdrawal. |
+| `li_withdraw_invitation` | `invitation_id` required; `confirm:true` required | Withdraw one exact currently pending sent invitation after a fresh `li_invitations_sent` read and approval. |
+| `sd_contact_state` | `channel` required (`linkedin`, `whatsapp`, or `email`); `identifiers` required array of 1-8 exact `{kind,value}` objects; `action` optional (`get` default or `suppress`); suppression also requires an allowed `reason` and `confirm:true` | Inspect exact tenant/channel-scoped contact history or add a protective suppression. It never infers that identifiers on different channels belong to one person. |
+| `sd_budget_status` | no arguments | Read the current sender binding, daily total/manual/campaign/unknown attempts, total and combined-campaign capacity, weekly invitation usage, lock state, and UTC resets from the authoritative server ledger. |
+| `sd_settings_get` | no arguments | Read the authenticated user's persistent SignalDash settings. Auto-accept is the first supported setting and is false for every existing user until explicitly changed. |
+| `sd_settings_set` | `auto_accept_linkedin` required boolean; `auto_accept_linkedin_filters` optional object with `public_identifiers` and `description_keywords`; `confirm:true` required | Update the general per-user settings surface after exact human approval. This changes no future or unknown setting implicitly. |
+| `sd_auto_accept_status` | no arguments | Inspect whether auto-accept is enabled, its exact filters, accepted today and this week, failed attempts today, dedicated and shared capacity, repeated-error stop state, and sanitized unparseable invitation records. |
+| `li_search_connections` | `query` required string, max 200; `filters` optional object with `company`, `headline_keyword`, `connected_after`, and `connected_before`; `limit` integer 1-100, default 20 | Search only the authenticated user's stored LinkedIn connection snapshot and join exact local contact state. This makes no LinkedIn, Unipile, HarvestAPI, or other paid discovery call. |
+| `li_discover_people` | `query` required role/title string, max 200; `filters` optional object with `company` and `location`; `limit` integer 1-10, default 10; `confirm` optional, default false | After a completed local snapshot returns no matches, preview one paid HarvestAPI profile-search page. Obtain approval for the exact query and maximum reserved cost, then repeat with `confirm:true`. |
+| `li_create_invitation_batch` | `source_label` required exact string, max 120 code points; `time_zone` required IANA timezone; `targets` required array of 1-10 exact `{profile_url,inclusion_reason,note?}` objects; reason max 240 and note max 200 Unicode code points | Create one immutable durable preview from canonical LinkedIn Classic `/in/` URLs. The agent structures an explicit human request; the server never generates targets or text. |
+| `li_get_invitation_batch` | `batch_id` required | Inspect every stored target, exact note, exclusion, hash, timing, capacity, and result. Use the returned browser review path for human approval. This read also authorizes a later exact cancel. |
+| `li_cancel_invitation_batch` | `batch_id` required; `approval_view_hash` required string or null exactly as inspected; `confirm:true` required | Permanently cancel unstarted targets in one freshly inspected batch. It cannot recall an executing invitation, and restarting requires a new preview and approval. |
 | `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. |
@@ -325,6 +376,24 @@ Representative calls:
 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."})
+li_send_invitation({"provider_id":"ACoAAExactMember","note":"Hi Amina, I enjoyed your post on agent safety."})
+li_send_invitation({"provider_id":"ACoAAExactMember","note":"Hi Amina, I enjoyed your post on agent safety.","confirm":true})
+li_invitations_received({"limit":20})
+li_accept_invitation({"invitation_id":"invite_received_42","confirm":true})
+li_invitations_sent({"limit":20})
+li_withdraw_invitation({"invitation_id":"invite_sent_91","confirm":true})
+sd_contact_state({"channel":"linkedin","identifiers":[{"kind":"provider_id","value":"ACoAAExactMember"}]})
+sd_contact_state({"channel":"email","identifiers":[{"kind":"email","value":"amina@example.com"}],"action":"suppress","reason":"opt_out","confirm":true})
+sd_budget_status({})
+sd_settings_get({})
+sd_settings_set({"auto_accept_linkedin":true,"auto_accept_linkedin_filters":{"public_identifiers":["amina-rahman"],"description_keywords":["Founder"]},"confirm":true})
+sd_auto_accept_status({})
+li_search_connections({"query":"founder agents","filters":{"company":"Acme","headline_keyword":"Founder","connected_after":"2025-01-01","connected_before":"2026-01-01"},"limit":20})
+li_discover_people({"query":"Platform Engineer","filters":{"company":"Acme","location":"Berlin"},"limit":5})
+li_discover_people({"query":"Platform Engineer","filters":{"company":"Acme","location":"Berlin"},"limit":5,"confirm":true})
+li_create_invitation_batch({"source_label":"Approved Berlin founder shortlist","time_zone":"Europe/Berlin","targets":[{"profile_url":"https://www.linkedin.com/in/amina-rahman/","inclusion_reason":"Named by the user for this exact batch","note":"Hi Amina, I enjoyed your post on agent safety."}]})
+li_get_invitation_batch({"batch_id":"00000000-0000-4000-8000-000000000000"})
+li_cancel_invitation_batch({"batch_id":"00000000-0000-4000-8000-000000000000","approval_view_hash":"exact-64-character-hash-from-the-read","confirm":true})
 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."})
@@ -354,10 +423,267 @@ 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.
 
+### Exact contact state and suppression
+
+`sd_contact_state` is local and account-scoped. It makes no Unipile, LinkedIn,
+WhatsApp, or email provider request. Exact identifiers are keyed separately by
+user and channel, and the response does not echo their values.
+
+Allowed identifier kinds:
+
+- LinkedIn: `provider_id`, `public_identifier`, canonical `profile_url`,
+  `member_urn`, or `chat_id`.
+- WhatsApp: `chat_id` or an E.164 `phone`.
+- Email: normalized `email`.
+
+One fresh provider response can supply several exact identifiers for the same
+channel. Pass those together to get the conservative union of their state.
+Never combine identifiers based on a name, employer, headline, similar profile,
+phone guess, or email guess. SignalDash does not infer cross-channel identity
+and does not claim person-wide suppression.
+
+Use `action:"get"` before outreach planning. `campaign_eligible:false` and
+`blocking_reasons` report known replies, earlier outbound touches,
+already-connected state, or suppression. Automated campaign actions are
+rejected after a known reply or earlier touch. Manual approved replies remain
+available unless an exact identifier is suppressed.
+
+Use `action:"suppress"` only after the human explicitly asks to suppress the
+exact identifier. Show the channel, identifier kind, and reason, then repeat
+with `confirm:true`. Allowed reasons are `opt_out`, `not_interested`,
+`provider_block`, `manual`, and `legal`. MCP cannot clear a suppression.
+
+### LinkedIn action budget status
+
+`sd_budget_status` is read-only and account-scoped. Use it before planning
+manual LinkedIn work or any campaign action. It reports attempts that
+SignalDash has committed in its authoritative SQLite ledger:
+
+- the total daily cap (`H`);
+- the campaign-excluded portion (`R = min(4, H)`);
+- the combined ceiling across all campaigns (`C = H - R`);
+- total, manual, campaign, and unknown attempts for the UTC policy day;
+- raw total and combined-campaign capacity remaining;
+- actions available now after connection and sender-lock state;
+- weekly LinkedIn invitation usage and its Monday 00:00 UTC reset.
+
+`R` is capacity campaigns cannot consume. It is not a reserve or guaranteed
+manual allowance: manual activity can consume the total cap first, and a later
+manual action can still be rejected at `H`. Campaign capacity is shared across
+all campaigns and is additionally bounded by the total remaining capacity.
+
+The result counts SignalDash-recorded attempts only. Native LinkedIn activity
+is not fully counted, so never describe the result as a LinkedIn-safe
+allowance. A disconnected, unverified, or locked sender reports zero safe
+actions even when raw counter capacity remains. It reports the durable pacing
+time and work window after a campaign action has established them. The
+scheduler, persisted tenant-breaker, active-batch, and target-count fields
+reflect the current invitation-batch runtime.
+
+### Opt-in invitation auto-accept
+
+`sd_settings_get` is the single read surface for persistent SignalDash
+settings. `sd_settings_set` changes persistent behavior for only the
+authenticated SignalDash user. Auto-accept is the first supported setting;
+every existing and newly created user is disabled by default. Show the exact
+setting and filters, obtain explicit human approval, then call the setter once
+with `confirm:true`. Disabling also uses `confirm:true`. Never infer changes to
+future or unknown settings.
+
+With no filters, every parseable pending LinkedIn invitation is eligible. The
+optional `public_identifiers` list is an exact lowercase allowlist. Optional
+`description_keywords` are case- and accent-insensitive substring matches
+against the provider's inviter description. When both groups are present, both
+must match. Names are never used as identity filters.
+
+The server worker is the action authority. By default it reads one bounded
+page, accepts no more than five invitations per run and ten per UTC day,
+jitters before every fresh preflight, serializes writes per sender, consumes
+the shared LinkedIn daily budget, and stops on a warning, 403, 429, unknown
+outcome, sender lock, or three consecutive errors. Successful acceptance is
+written to the action audit and exact LinkedIn contact state as inbound,
+invited, and connected, so later campaigns see the relationship.
+A healthy worker run resets the consecutive provider-error streak; malformed
+invitations remain visible in status even after later healthy runs.
+
+Unipile currently places acceptance proof at `specifics.shared_secret` and
+inviter data at
+`inviter.{inviter_name,inviter_public_identifier,inviter_description}`.
+SignalDash also reads the legacy top-level secret and old inviter fields. It
+never returns or logs the secret. An invitation missing its ID, acceptance
+proof, or an exact inviter identifier is not accepted: the server emits a
+high-visibility error, stores only sanitized missing-field evidence, and
+exposes it through `sd_auto_accept_status`. Three consecutive parse or provider
+errors disable automation with `disabled_reason:"repeated_errors"`.
+
+Use `sd_auto_accept_status` after changing the setting and whenever the user
+asks whether it is healthy. Report `enabled`, exact filters, accepted today and
+this week, failed attempts today, remaining dedicated and shared capacity,
+`consecutive_errors`, `disabled_reason`, and every recent unparseable record.
+Never describe a disabled or erroring worker as active.
+
+### Campaign time boundary
+
+SignalDash does not expose a general message scheduler. The first executable
+campaign scope has no user-selected future start date, recurring schedule,
+automatic follow-up, acceptance-triggered message, or multi-message
+("double text") sequence. Do not claim that any such action was queued.
+
+The common server write authority enforces the design-approved time controls
+for every campaign action:
+
+- a valid sender IANA timezone is mandatory;
+- actions run only Monday through Friday, 09:00-17:00 sender-local time;
+- every attempted action atomically stores the next per-sender pacing time,
+  randomized from 90 to 180 seconds;
+- timing is checked before final provider preflight and again in the same
+  SQLite transaction that reserves budget and acquires the sender lease;
+- one provider write may be in flight per sender;
+- downtime, a work-window boundary, or a UTC reset never creates a catch-up
+  burst.
+
+Manual one-object tools keep their existing exact-read, approval, duplicate,
+rate, ownership, contact-state, and sender-lock guards. A later message after
+an invitation or reply is new context and requires a fresh thread read, exact
+draft, and human approval.
+
+### Human-approved invitation batches
+
+An invitation batch is the only executable campaign form. It contains 1–10
+exact canonical LinkedIn Classic profile URLs, one exact inclusion reason per
+target, and one optional exact invitation note per target. The note limit is
+200 Unicode code points. Source labels, reasons, and notes reject leading or
+trailing whitespace; notes normalize line endings and reject control or format
+characters.
+
+The human can describe the desired batch naturally, but the agent must
+structure only facts the human explicitly supplied. Never infer or generate a
+profile URL, inclusion reason, or note. Search, discovery, reactions, comments,
+and connection exports are not batch target sources. The server performs no
+runtime target or text generation.
+
+Use the batch tools in this order:
+
+1. Call `li_create_invitation_batch` once with the exact source label, sender
+   IANA timezone, and complete ordered target list.
+2. Poll only with `li_get_invitation_batch` until the durable preview is
+   `previewed` or terminal. Inspect every target, including exclusions.
+3. Relay the returned `approval_url` to the human. The human opens it in a
+   browser, reauthenticates with the SignalDash invite credential, checks each
+   desired target (none are preselected), acknowledges the consequences, and
+   approves. MCP and agent bearer tokens cannot approve. Five failed credential
+   attempts durably block that batch's authentication surface for 15 minutes.
+4. Continue read-only status checks with `li_get_invitation_batch`. The worker
+   submits selected targets in fixed order only while the 24-hour approval,
+   sender binding, weekday work window, pacing, budgets, exact identity,
+   contact state, invitation state, chat absence, and tenant breaker remain
+   valid.
+5. To stop, first inspect the batch, show the exact state and hash, obtain
+   cancellation approval, then call `li_cancel_invitation_batch` once with
+   that hash and `confirm:true`.
+
+Cancel permanently terminates the batch and affects only unstarted targets.
+It cannot recall an executing provider action. A restart requires a new batch,
+preview, and human approval. There is no pause/resume, priority, future start,
+recurring schedule, automatic follow-up, acceptance polling, acceptance
+message, multi-message sequence, or action after a successful invitation.
+
+Unknown outcomes, provider warnings, checkpoints, HTTP 403, and HTTP 429 stop
+the batch and lock the sender. Two campaign `outcome_unknown` writes on
+different senders within five minutes open the persisted tenant breaker.
+Tenant provider authentication failures open it immediately. While open, the
+breaker rejects new batch creation and stops queued preview work before any
+provider read.
+Definite provider rejections consume attempts but can leave later exact targets
+eligible to run. SignalDash limits are not LinkedIn-safe thresholds, and
+native LinkedIn activity can still race the final reads.
+
+### Search your stored LinkedIn network
+
+`li_search_connections` is the primary list-building path before any external
+discovery. It is account-scoped and searches the stored connection sidecar
+only. The request path performs zero LinkedIn, Unipile, HarvestAPI, or other
+paid API calls and never starts or resumes a sync.
+
+The required `query` matches accent-insensitive terms across name, headline,
+and stored company. Optional `company` and `headline_keyword` filters are
+case-insensitive substrings. `connected_after` and `connected_before` use
+inclusive `YYYY-MM-DD` bounds. Legacy v1 relation rows do not contain a
+separate company field, so their company filter is transparently matched
+against the returned headline.
+
+Each result contains only:
+
+- `name`, `headline`, `public_id`, `profile_url`, and `connected_at`;
+- `already_in_contact`, based on exact recorded inbound, outbound, reply, or
+  invitation history;
+- the joined `contact_state`, `campaign_eligible`, and `blocking_reasons`.
+
+The join checks only the row's exact LinkedIn public identifier and canonical
+profile URL for this SignalDash user. It does not infer a person, merge aliases,
+or inspect another tenant. Search results are planning evidence, not permission
+to message or invite anyone. A later action still requires its exact
+one-object read/preview, human review, approval, fresh preflight, and server
+guards. The executable invitation-batch design does not accept a search result
+as a target input.
+
+When no connection rows are stored, the tool returns
+`connections_not_synced` or `connections_sync_pending` and points to:
+
+```bash
+npx -y @floomhq/signaldash connections linkedin-connections.csv
+```
+
+Use that paced, resumable sync. Never replace the missing snapshot with a burst
+of profile reads.
+
+### Capped discovery beyond the stored network
+
+`li_discover_people` is the only supported paid discovery path. It searches
+public LinkedIn profile cards through HarvestAPI without using the connected
+LinkedIn sender. It does not fetch full profiles, find email addresses, send
+anything, or create invitation-batch targets.
+
+The server enforces local-first behavior. A completed paced connection snapshot
+is mandatory. SignalDash searches that snapshot with the requested role/title
+and company before any paid request. When local matches exist, it returns those
+matches with `source:"own_network"` and `provider_requests:0`; use
+`li_search_connections` to refine them. An incomplete snapshot returns
+`connections_sync_required` and starts no provider request.
+
+When there are no local matches:
+
+1. Call `li_discover_people` without `confirm`. The response previews the exact
+   query, filters, result limit, ten-profile maximum billing exposure, maximum
+   reserved cost, and 30-minute expiry. It makes zero paid requests.
+2. Show the human that exact paid request and maximum reserved cost. Obtain
+   explicit approval.
+3. Repeat the identical arguments once with `confirm:true`.
+
+The hosted server then makes at most one serialized
+`GET /linkedin/profile-search` request for page 1. It reserves the configured
+worst-case page cost in integer micro-dollars before the request and enforces a
+durable per-user cooldown, per-user daily request cap, tenant-wide daily
+request cap, and tenant-wide daily cost cap. The reservation consumes the exact
+preview atomically. Another paid request, including one after a failed or
+ambiguous provider result, requires a fresh preview and approval. Failed or
+ambiguous provider requests retain their reservation and are never retried
+automatically.
+
+SignalDash removes hidden `"LinkedIn Member"` cards, malformed or ambiguous
+identities, duplicates, exact stored connections, and exact contact-state rows
+already marked connected. Returned cards contain only name, headline,
+location, public identifier, canonical profile URL, and exact local contact
+state. No fuzzy or cross-channel identity merge occurs.
+
+Discovery results are planning evidence only. `CAMPAIGN-DESIGN.md` excludes
+searches and discovery as invitation-batch target sources. A later action on
+one exact person begins the complete one-object preview, approval, fresh
+preflight, contact-state, duplicate, ownership, and rate-limit flow.
+
 ### LinkedIn connections export via CLI
 
-This is the fourteenth operation. It is intentionally a paced CLI workflow, not
-an MCP bulk-read tool.
+This is intentionally a paced CLI workflow, not an MCP bulk-read tool.
 
 ```bash
 npx -y @floomhq/signaldash connections linkedin-connections.csv
@@ -389,8 +715,9 @@ 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.
+email recipient was not present in a recently read thread, or an invitation
+write lacks its exact recent preview/list read. The default read window is 30
+minutes.
 
 Comply:
 
@@ -417,6 +744,41 @@ Comply:
 
 Changing whitespace or punctuation to evade the duplicate guard is prohibited.
 
+### 409 `contact_suppressed`
+
+Meaning: one of the exact channel identifiers for this contact has an active
+suppression. Message and invitation writes stop before the provider write.
+
+Comply:
+
+1. Stop the action.
+2. Inspect the exact state with `sd_contact_state`.
+3. Do not switch identifiers, channels, accounts, or sessions to evade it.
+4. Escalate a mistaken suppression to the SignalDash operator. MCP cannot clear
+   it.
+
+Campaign-mode actions also reject `recipient_replied` and `already_contacted`.
+These blocks prevent automated follow-up after a known inbound message and
+prevent another campaign from touching the same exact identifier. They do not
+claim that SignalDash has resolved a person across channels.
+
+### 409 invitation and context preflight blocks
+
+`thread_changed`, `already_connected`, `existing_conversation`,
+`conversation_state_incomplete`, `invitation_already_pending`,
+`inbound_invitation_pending`, `invitation_not_pending`,
+`invitation_state_incomplete`, and `relationship_unverified` mean the exact
+provider state no longer authorizes the action. New-invitation preflight checks
+up to 250 sent invitations, up to 100 received invitations, and the exact
+target's attendee-scoped chats. Any pagination cursor makes absence unproved.
+
+Comply:
+
+1. Stop the action.
+2. Re-read the exact thread or invitation list.
+3. Do not expand pagination or fetch profiles in a loop.
+4. Obtain new approval only for a newly previewed exact action.
+
 ### 429 `rate_limit_exceeded`
 
 Meaning: the persisted daily action cap is exhausted. The response includes
@@ -431,21 +793,54 @@ Comply:
    to work around the cap.
 4. Do not queue a burst for the reset boundary.
 
+Invitation sends also return `invitation_rate_limit_exceeded` when the separate
+weekly policy is exhausted. The default policy is 100 attempts per sender,
+resetting Monday at 00:00 UTC. It is a SignalDash policy, not a claim about a
+LinkedIn-safe threshold.
+
+Paid discovery returns `paid_discovery_cooldown`,
+`paid_discovery_user_daily_cap`, `paid_discovery_tenant_daily_cap`, or
+`paid_discovery_cost_cap` before the HarvestAPI request when its pacing,
+request, or spend boundary is reached. Stop and use `retry_at` or the UTC reset
+reported by the server. Do not switch users, sessions, or machines to bypass a
+paid-provider cap.
+
+### 423 sender locks and 502 `outcome_unknown`
+
+A provider warning, HTTP 403, HTTP 429, sender identity mismatch, or ambiguous
+provider outcome locks all later LinkedIn writes for that logical sender. An
+ambiguous result returns `outcome_unknown`, consumes the action budget, and is
+never retryable.
+
+Comply:
+
+1. Do not retry or switch sessions.
+2. Inspect the provider account manually for a restriction and verify whether
+   the action landed.
+3. Escalate for human reconciliation. Only the hosted operator can clear the
+   durable lock after verification.
+
 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.
+These rules apply to LinkedIn messages and invitations, 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.
+   recipient or audience and the exact final text. The only standing-action
+   exception is invitation auto-accept after explicit approval of its exact
+   persistent setting and filters.
+2. Read the exact thread immediately before a message action. For invitations,
+   preview the exact target and note or list the exact current invitation.
+   Check the recipient, latest inbound message, prior context, relationship,
+   pending state, and whether the proposed action already exists.
 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.
+4. Never loop or parallelize single-object send tools. Only the immutable
+   invitation-batch runner may submit more than one target, and only after the
+   separate exact browser approval.
 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.
@@ -456,9 +851,11 @@ These rules apply to LinkedIn, WhatsApp, email, and public LinkedIn posts.
 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
+The hosted backend defaults to 20 LinkedIn action attempts per stable logical
+sender per UTC day, shared across messages, invitations, invitation
+maintenance, and post publishing. Invitation sends also use the default
+100-attempt weekly policy. Email and WhatsApp retain their hosted send caps. A
+deployment can configure different caps. Never promise a particular remaining
 allowance until the response reports `rate_limit.limit` and `remaining`.
 
 ## Worked flows
@@ -529,7 +926,9 @@ User: "Who engaged with my last LinkedIn post, and what should I do?"
    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.
+   send once. If the user explicitly asks to invite one exact reactor, resolve
+   the exact provider ID, run the invitation preview, obtain exact approval,
+   and send once. Engagement never authorizes an invitation or a loop.
 
 ### Flow 3: find and reply to a WhatsApp thread
 
@@ -572,7 +971,106 @@ User: "Find my WhatsApp thread with Sara and reply that 16:30 works."
 8. Read the chat again and confirm the text appears once as an outbound
    message.
 
-### Flow 4: export LinkedIn connections
+### Flow 4: send, accept, or withdraw one LinkedIn invitation
+
+For a new invitation:
+
+1. Resolve one exact `provider_id`. A display name or fuzzy match is
+   insufficient.
+2. Preview without confirmation:
+
+   ```text
+   li_send_invitation({
+     "provider_id":"ACoAAExactMember",
+     "note":"Hi Amina, I enjoyed your post on agent safety."
+   })
+   ```
+
+3. Show the server-confirmed sender, target, exact note, and character count.
+4. Obtain approval for that exact target and note.
+5. Repeat the identical payload once with `"confirm":true`.
+6. Stop on relationship, existing-conversation, incomplete-state,
+   pending-invitation, cap, warning, lock, or `outcome_unknown` errors. Never
+   retry an ambiguous result.
+
+For received or sent invitation maintenance:
+
+1. Call `li_invitations_received` or `li_invitations_sent`.
+2. Resolve the exact invitation ID and show the exact person and action.
+3. Obtain approval.
+4. Call `li_accept_invitation` or `li_withdraw_invitation` once with that ID
+   and `"confirm":true`.
+5. List again to verify that the invitation is no longer pending.
+
+Never loop over the returned page. Incoming acceptance and stale withdrawal
+are human-approved, single-object operations only.
+
+### Flow 4b: enable and inspect invitation auto-accept
+
+User: "Auto-accept LinkedIn invitations from these exact public IDs when their
+description contains Founder."
+
+1. Call `sd_settings_get({})`, then show the exact persistent setting:
+
+   ```text
+   Enabled: true
+   Public identifiers: amina-rahman, marco-silva
+   Description keywords: Founder
+   Matching rule: exact public ID AND description keyword
+   ```
+
+2. Obtain explicit approval, then call once:
+
+   ```text
+   sd_settings_set({
+     "auto_accept_linkedin":true,
+     "auto_accept_linkedin_filters":{
+       "public_identifiers":["amina-rahman","marco-silva"],
+       "description_keywords":["Founder"]
+     },
+     "confirm":true
+   })
+   ```
+
+3. Verify with:
+
+   ```text
+   sd_auto_accept_status({})
+   ```
+
+4. Report the setting, accepted count today and this week, failed attempts
+   today, both remaining capacities, repeated-error state, and every
+   unparseable invitation. If the worker disabled itself, stop and surface the
+   exact `disabled_reason` and missing fields. Do not silently re-enable it.
+5. To disable, obtain explicit approval and call
+   `sd_settings_set({"auto_accept_linkedin":false,"confirm":true})`, then
+   verify both `sd_settings_get({})` and status.
+
+### Flow 5: search LinkedIn connections locally
+
+User: "Find product leaders at Acme in my LinkedIn network."
+
+1. Call:
+
+   ```text
+   li_search_connections({
+     "query":"product leader",
+     "filters":{"company":"Acme"},
+     "limit":20
+   })
+   ```
+
+2. Confirm the response has `local_only:true` and `provider_requests:0`.
+3. Return only the stored profile fields and exact contact-state result. Do not
+   add inferred profile facts or cross-channel identity.
+4. If the response says `connections_not_synced` or
+   `connections_sync_pending`, relay its paced-sync instruction. Do not trigger
+   profile reads or discovery as a substitute.
+5. Stop after the read-only results. A later action on one exact person starts
+   the complete guarded one-object flow with fresh provider context and
+   approval. Never turn the result page into a send loop.
+
+### Flow 6: export LinkedIn connections
 
 User: "Export my LinkedIn connections to CSV."
 
@@ -595,11 +1093,88 @@ User: "Export my LinkedIn connections to CSV."
 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.
 
+### Flow 7: discover people beyond the stored network
+
+User: "Find platform engineers at Acme in Berlin beyond my network."
+
+1. Call without confirmation:
+
+   ```text
+   li_discover_people({
+     "query":"Platform Engineer",
+     "filters":{"company":"Acme","location":"Berlin"},
+     "limit":5
+   })
+   ```
+
+2. If it returns `source:"own_network"`, return those local matches and stop.
+   The paid provider was not called.
+3. If it returns `connections_sync_required`, run or resume the paced
+   connections sync and stop. Do not bypass it.
+4. If it returns a paid preview, show the exact query, filters, result limit,
+   and `maximum_cost_reserved_usd`. Obtain explicit approval.
+5. Repeat the identical payload once with `"confirm":true`.
+6. Report only the returned public profile-card fields and exact contact state.
+   State that hidden/unusable and exact already-connected cards were excluded.
+7. Stop after the read-only results. Do not enrich profiles, find emails,
+   create a batch, or loop into invitations or messages.
+
+### Flow 8: create, review, or cancel one invitation batch
+
+User: "Invite these two exact LinkedIn profiles with these notes."
+
+1. Confirm the human supplied every canonical profile URL, exact inclusion
+   reason, exact optional note, source label, and sender timezone. Ask for any
+   missing value. Do not fill gaps with search or generation.
+2. Call:
+
+   ```text
+   li_create_invitation_batch({
+     "source_label":"User-approved event follow-up",
+     "time_zone":"Europe/Berlin",
+     "targets":[
+       {
+         "profile_url":"https://www.linkedin.com/in/amina-rahman/",
+         "inclusion_reason":"The user met Amina at the named event",
+         "note":"Hi Amina, great meeting you at the agent safety meetup."
+       }
+     ]
+   })
+   ```
+
+3. Store the exact `batch_id`. Call `li_get_invitation_batch` until its state
+   is `previewed` or terminal. Report every excluded row and reason.
+4. Show the sender, source, ordered targets, full profile URLs, reasons, exact
+   notes, reused-copy counts, current limits, timing, expiry, cancellation
+   limit, and residual native-activity race.
+5. Relay the exact `approval_url`. Do not fetch, submit, or automate that
+   browser page. The human reauthenticates and selects the desired unchecked
+   rows.
+6. Inspect the batch to report `approved`, `running`, or terminal progress.
+   Never interpret an approval-page visit as approval; only server state proves
+   it.
+7. For cancellation, inspect immediately, show the exact state and
+   `approval_view_hash`, obtain explicit cancellation approval, then call:
+
+   ```text
+   li_cancel_invitation_batch({
+     "batch_id":"00000000-0000-4000-8000-000000000000",
+     "approval_view_hash":"the exact hash from the fresh read",
+     "confirm":true
+   })
+   ```
+
+8. Report that planned targets were cancelled and any executing action was not
+   recalled. Never claim the batch was paused or can 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.
+Read-only account work does not require send approval. You can list, read,
+search the stored connection snapshot, summarize, analyze engagement, and
+create a non-published post draft as requested. Paid discovery separately
+requires approval of its exact preview and maximum reserved cost. Still use
+narrow limits, protect private content, and avoid bulk collection. Search and
+discovery results do not authorize an outbound action.
 
 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.
@@ -628,11 +1203,60 @@ 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.
+- A connection search reported `local_only:true`, made zero provider requests,
+  and did not authorize an outbound action.
+- A paid discovery had a completed connection snapshot, returned no own-network
+  matches, used an unexpired exact preview and approval, made at most one
+  serialized provider request, reported its cost budget, and remained planning
+  evidence only.
 - Every send used a fresh exact-thread read and exact human approval.
+- Every invitation send used an exact server preview and exact approval.
+- Every invitation accept or withdrawal used a fresh exact invitation-list
+  read and exact approval.
+- Invitation auto-accept was explicitly enabled for the exact user, preserved
+  both the dedicated and shared caps, stopped on repeated errors, and exposed
+  every unparseable invitation through `sd_auto_accept_status`.
+- Every invitation batch used only exact user-supplied canonical profile URLs,
+  reasons, and notes; exposed every target; used the separate browser approval;
+  and never approved through MCP.
+- Every batch cancel followed a fresh exact batch read and stated that an
+  executing action cannot be recalled.
 - No duplicate, bulk, parallel, warning, 403, or 429 path was bypassed.
+- No sender lock or `outcome_unknown` result was retried.
 - 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.
+
+## How to write the message (this is where agents fail hardest)
+
+Agents pad. Padding is the clearest tell that a human did not write it, and on
+LinkedIn or WhatsApp it gets ignored. Less is more, always.
+
+- **Short.** A reply is usually 1-3 sentences. If they wrote one line, reply
+  with one line. Match the length and register of the thread.
+- **One idea per message.** Do not stack context, ask and pleasantry into one
+  block. Split into 2-3 short consecutive sends instead of one paragraph.
+- **No preamble, no summary-back.** Never "I hope this finds you well", never
+  restate what they just said, never a formal sign-off in a chat.
+- **No em dashes.** Use commas, periods, colons.
+- **No hype filler.** Cut "excited to", "reaching out", "just wanted to",
+  "circling back", "leverage", "synergies", and any eager closer.
+- **Their language.** German thread stays German, with real umlauts (für, not
+  fuer). Never translate their language away.
+- **Read the thread first, then sound like the user.** Their own recent messages
+  in that thread are the style reference. Copy that register, not a template.
+
+Before/after, same intent:
+
+> Bad: "Hi Mircea, I hope you're doing well! Thanks so much for reaching out
+> about scheduling a call. I'd be delighted to connect and would love to explore
+> how we might be able to work together. Please let me know what times work best
+> for you and I'll do my best to accommodate your schedule."
+
+> Good: "hey Mircea, ja gerne. hier mein link: [cal]"
+
+If a draft is longer than the thread's own messages, cut it before showing it.
+