@audienti/cli 0.1.145 → 0.2.0-exora.10

package/skills/getting-started/references/capabilities.md

@@ -0,0 +1,237 @@
+# Capability report format
+
+Report what you can do for the user right now, as rows. One row per capability,
+provider, source and account. The capability ids come from Audienti's catalog
+([ADR 015](https://github.com/omalab/exora/blob/main/docs/decisions/015-capability-taxonomy.md));
+the full list is below.
+
+```json
+{
+  "runtime": { "name": "Claude Code", "model": "claude-opus-5-5" },
+  "capabilities": [
+    { "capability": "web.search", "provider": "web", "via": "native", "access": "read", "status": "connected" },
+    { "capability": "web.page.read", "provider": "web", "via": "native", "access": "read", "status": "connected" },
+    { "capability": "profile.message.send", "provider": "email", "via": "composio:gmail", "account": "owner@example.com", "access": "send", "status": "connected" },
+    { "capability": "profile.inbox.read", "provider": "email", "via": "composio:gmail", "account": "owner@example.com", "access": "read", "status": "connected" },
+    { "capability": "profile.read", "provider": "linkedin", "via": "composio:linkedin", "access": "read", "status": "connected" },
+    { "capability": "profile.message.send", "provider": "linkedin", "via": "composio:linkedin", "account": "linkedin.com/in/owner", "access": "send", "status": "connected", "limits": { "daily": 20 } },
+    { "capability": "crm.records.search", "provider": "salesforce", "via": "mcp:salesforce", "access": "read", "status": "needs_sign_in" }
+  ]
+}
+```
+
+```sh
+audienti agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE
+audienti agent capabilities --profile AGENT_PROFILE
+```
+
+The first command replaces your previous report. The second prints what Audienti now
+counts for you: the rows that work now, and the rows that work with Audienti's hosted
+tools in the selected workspace. Over MCP, use `agent_capabilities_report` and
+`agent_capabilities_list`. Over HTTP, `PUT` and `GET /api/v1/agent-capabilities`.
+
+## Fields
+
+- `runtime.name`: your product or runtime as the user knows it. `runtime.model` is
+  optional.
+- `capability`: an id from the list below. An unknown id is refused.
+- `provider`: which kind of profile the work touches. Required where the list names
+  providers; leave it out where it says "none". Where it says "any", leave it out or
+  name the one you use.
+- `via`: where you reach it. `native` for a connector built into your runtime;
+  `composio:<app>` (for example `composio:gmail`), `treg:<tool>` or `mcp:<server>` for
+  a hub or MCP server. Check your hubs first: list each app connected there as its own
+  row.
+- `account`: the user's own mailbox, LinkedIn account or handle you act through, such as
+  `owner@example.com` or `linkedin.com/in/owner`. Required for every verb that acts as
+  the user (marked "as the user" below).
+- `access`: `read`, `write` or `send`, as listed for the capability. `send` reaches
+  another person; drafting is `write`.
+- `status`: `connected` when you can call it now, `needs_sign_in` when it is installed
+  but signed out, `unavailable` when it exists but fails.
+- `cost`: leave it out. Your own tools are `owner`.
+- `limits`: optional `daily` and `hourly` caps you respect.
+- `identity`: optional, on an email or LinkedIn row that names an `account`. The
+  account's own stable id, as `{ "namespace": "...", "accountId": "..." }`, so Audienti
+  can match the LinkedIn account or mailbox to the one the user set up. Use the same identity on
+  every row for that account. Examples: `{ "namespace": "linkedin", "accountId":
+  "ACoAAB1234" }` for a LinkedIn account, `{ "namespace": "gmail", "accountId":
+  "108234567890" }` for a Gmail mailbox.
+
+At most 64 rows and 32 KiB.
+
+## LinkedIn accounts
+
+For each LinkedIn account you send as, add an entry to `seats` with what you know about
+it. Audienti shows it to the user on the LinkedIn account's page and plans around it.
+
+```json
+{
+  "seats": [
+    {
+      "provider": "linkedin",
+      "account": "linkedin.com/in/owner",
+      "checkEverySeconds": 21600,
+      "plan": "premium_business",
+      "inmail": { "available": true, "quotaPerMonth": 15, "creditsLeft": 11 },
+      "limits": { "connectionRequestsPerDay": 20, "connectionRequestsPerWeek": 100, "messagesPerDay": 50, "inmailPerMonth": 15 }
+    }
+  ]
+}
+```
+
+- `account`: the same LinkedIn account you name in your LinkedIn rows.
+- `checkEverySeconds`: how often you can check this LinkedIn account's sent invitations, at least
+  3600 (one hour). Audienti schedules outcome checks at this cadence; every 6 hours
+  when you leave it out. The user never changes it.
+- `plan`: the LinkedIn plan the account has, as the LinkedIn interface shows it: `free`,
+  `premium_career`, `premium_business`, `premium_all_in_one`, `sales_navigator_core`,
+  `sales_navigator_advanced` or `recruiter_lite`. Leave it out when you cannot tell; never guess.
+  The plan sets the InMail allowance. Audienti keeps connection notes to 200 characters for
+  now, whatever the plan.
+- `inmail`: whether the LinkedIn account can send InMail, its monthly quota, and `creditsLeft`,
+  the balance the interface shows now (Sales Navigator shows it in the compose window and on
+  Settings). With a balance, Audienti plans an InMail only while `creditsLeft` is above 0.
+  Report `profile.inmail.send` as well; a LinkedIn account counts as InMail-capable only with both.
+- `limits`: the safe limits for this LinkedIn account. Audienti never plans more LinkedIn sends on
+  it than its per-day and per-week limits. The user can lower a limit, never
+  raise it above the one you report.
+
+Report `profile.invitations.read` on the LinkedIn account too, so outcome checks can be assigned to
+you.
+
+## Rules
+
+- **Report, never connect.** List only what you can call now. Do not install or sign in
+  to anything to fill the list.
+- **Never invent.** Leave out anything you cannot call. A wrong row sends tasks to you
+  that you cannot do.
+- **Never report `via: audienti`.** Audienti adds rows for its own hosted tools itself
+  when the workspace has credits; a report that sends `audienti` is refused. Leave out
+  Audienti's hosted tools unless you reach them through another connector.
+- **Never include secrets** (tokens, cookies, keys) or personal data about the user's
+  contacts.
+- Report again when your tools change, and at least every seven days. The user sees
+  older rows as stale.
+
+## The catalog
+
+Launch rows can be required by queue tasks. Later rows are accepted and shown to the
+user, but no task requires them yet.
+
+### People and companies
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `people.search` | any | read | Find people from audience filters or a question | yes |
+| `people.discover` | any | read | Find look-alikes from a seed person or company | yes |
+| `person.profiles.discover` | any | read | Expand one person into their other profiles | yes |
+| `companies.search` | any | read | Find companies from filters | yes |
+| `company.enrich` | any | read | Fill size, industry, location, site | yes |
+| `company.posts.list` | linkedin, x, instagram, tiktok | read | What a company page has posted | yes |
+
+### Profile: research
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `profile.read` | linkedin, x, instagram, tiktok, github, web | read | Fetch one profile by URL or handle | yes |
+| `profile.enrich` | linkedin, email | read | Fill title, company, location, history from one handle | yes |
+| `profile.find` | email, phone | read | Find a person's handle on this provider | yes |
+| `profile.verify` | email | read | Check the handle is live and deliverable | yes |
+| `profile.posts.list` | linkedin, x, instagram, tiktok | read | What this profile has posted | yes |
+| `profile.comments.list` | linkedin, x, instagram, tiktok | read | Comments this profile wrote on others' posts | yes |
+| `profile.reactions.list` | linkedin, x, instagram, tiktok | read | Reactions this profile gave | yes |
+
+### Profile: as the user (needs `account`)
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `profile.message.send` | email, linkedin, whatsapp, phone, x, instagram | send | Send an approved message | email, linkedin |
+| `profile.inbox.read` | email, linkedin, whatsapp | read | Watch the user's inbox for replies | email, linkedin |
+| `profile.invitations.read` | linkedin | read | Read the user's sent invitations, to see which were accepted or closed | yes |
+| `profile.invitations.received` | linkedin | read | Read the invitations people sent to the user (as the user) | linkedin |
+| `profile.inmail.send` | linkedin | send | Send an approved InMail | yes |
+| `profile.connection.request` | linkedin | send | Send an approved connection request | yes |
+| `profile.connection.withdraw` | linkedin | send | Withdraw a pending request | yes |
+| `profile.connection.remove` | linkedin | send | Remove a connection | later |
+| `profile.follow` | linkedin, x, instagram, tiktok | send | Follow a person or company | linkedin |
+| `profile.unfollow` | linkedin, x, instagram, tiktok | send | Unfollow | linkedin |
+| `profile.mute` | x, instagram | send | Mute | later |
+| `profile.block` | x, instagram, linkedin | send | Block | later |
+| `profile.call` | phone | send | Call a prospect | later |
+
+### Posts and topics
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `topic.track` | any | read | Track a topic for signals | yes |
+| `posts.search` | linkedin, x, instagram, tiktok, web | read | Find posts about a topic | yes |
+| `post.read` | linkedin, x, instagram, tiktok | read | Fetch one post with its type | yes |
+| `post.comments.list` | linkedin, x, instagram, tiktok | read | Who commented, and what they said | yes |
+| `post.reactions.list` | linkedin, x, instagram, tiktok | read | Who reacted | yes |
+| `post.comment` | linkedin, x, instagram, tiktok | send | Comment as the user (as the user) | linkedin |
+| `post.react` | linkedin, x, instagram, tiktok | send | React as the user (as the user) | linkedin |
+| `post.publish` | linkedin, x, instagram, tiktok | send | Publish a post as the user (as the user) | linkedin |
+| `profile.visit` | linkedin | read | Visit a profile as a person would (as the user) | linkedin |
+| `profile.views.read` | linkedin | read | Read who viewed the user's profile (as the user) | linkedin |
+
+### Web, calendar, records, owner, integration
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `web.search` | web | read | Search the web | yes |
+| `web.page.read` | web | read | Read one page | yes |
+| `calendar.read` | google, microsoft | read | Free and busy time | later |
+| `calendar.freebusy.read` | google, microsoft | read | Read the user's free and busy times to offer slots in a reply | later |
+| `calendar.event.create` | google, microsoft | write | Create an event and send the invite from the user's calendar | later |
+| `meeting.book` | google, microsoft | write | Book or propose a meeting | later |
+| `meeting.reschedule` | google, microsoft | write | Move a booked meeting | later |
+| `meeting.cancel` | google, microsoft | write | Cancel a booked meeting | later |
+| `crm.records.search` | hubspot, salesforce, pipedrive, other | read | Find records in the user's CRM | yes |
+| `crm.record.read` | hubspot, salesforce, pipedrive, other | read | Read one CRM record | yes |
+| `crm.record.write` | hubspot, salesforce, pipedrive, other | write | Write back to one CRM record | yes |
+| `owner.notify` | push, slack, sms, email | send | Reach the user on their own channel | yes |
+| `webhook.receive` | none | read | Take a push instead of polling | later |
+| `webhook.send` | none | send | Post events to the user's URL | later |
+
+`owner.notify` means you can reach your user outside Audienti: chat, push, Slack, SMS or email. Report it
+and Audienti puts a **Tell your user about an alert** task in your queue for each alert it records in
+the workspace; the task carries the message and a link, and you mark it done once you delivered it. An
+agent that has not reported `owner.notify` gets no such task.
+
+### Tools you use for yourself
+
+| Capability | Providers | Access | What it does | Launch |
+| --- | --- | --- | --- | --- |
+| `tool.media.transcribe` | none | read | Video or audio to text | later |
+| `tool.image.read` | none | read | Read text and content out of an image | later |
+| `tool.proxy.session.start` | none | write | Sticky residential session for your own browser, metered by bandwidth | yes |
+| `tool.proxy.session.rotate` | none | write | New IP on the current session | yes |
+| `tool.proxy.config.read` | none | read | Read region, stickiness and bandwidth cap | yes |
+| `tool.proxy.config.write` | none | write | Set region, stickiness and bandwidth cap | yes |
+
+Your runtime's documents, spreadsheets, files, code, memory, tasks and chat are not
+capabilities. Leave them out.
+
+## Older reports
+
+`audienti agent inventory report` (categories such as `web_search` or `crm`) and the
+per-account `audienti agent capabilities report` with `provider` and `accountRef` are
+still accepted for one release. Audienti translates both into rows. Send the format above
+instead.
+
+Translated inventory reports match fewer queue tasks than before:
+
+- `company_data` alone matches none of the find, verify or enrich tasks.
+- `linkedin` alone no longer matches find or enrich tasks.
+- `web_search` alone no longer matches enrich tasks.
+- `people_data` alone no longer matches verify tasks.
+- `email` and `linkedin` match send tasks only for their own provider and only with
+  `send` access; `social` matches no send task.
+
+A LinkedIn message can carry a file. Upload it first with `audienti attachments upload FILE` (an image up to 5 MB,
+or a voice note up to 5 MB and 2 minutes; Audienti reads a WAV, M4A, OGG or MP3 voice note's length from the file; add `--duration SECONDS` only for a file it cannot read). Name the returned id in
+`content.attachments` of the `linkedin.send` action, and tag that action `profile.message.send`. A connection
+request carries no file. A voice note goes only to a connection. When you send from your own account, run
+`audienti attachments get ID --out PATH` to fetch the file, then attach it in LinkedIn. A managed account sends it
+for you.

package/skills/getting-started/references/mailbox-check.md

@@ -0,0 +1,64 @@
+# The mailbox test email (`mailbox.confirm`)
+
+Audienti never signs in to your user's mailbox. You send from it through your own email
+connector (Gmail or Outlook, through Composio, a Claude connector or similar), so you also
+prove it works. A mailbox counts for campaigns only once you sent a test email from it to
+itself, read it back and reported the code. Your user does nothing in this check: never ask
+them for the code, and never send them to Settings to confirm a mailbox.
+
+When your user connects a mailbox you reported, or asks for another test email in Settings →
+Sending, you get one `mailbox.confirm` task for it. Its `detail.test` gives the mailbox as
+you reported it (`mailbox`), its address as Audienti has it (`address`, or `null` when the
+mailbox was reported under a name or an account id that is no address), the code (`code`) and
+the subject to use (`subject`, `Audienti mailbox check` and the code).
+
+1. Claim the task: `audienti queue claim TASK_ID`.
+2. Send one email from that mailbox to its own address, and to nobody else. Use the address
+   your connector reports for the mailbox; `address` is only a hint, and if your connector
+   reports another, use that one. Use the subject the task gives and put the code in the body
+   too. Send nothing else.
+3. Read that mailbox's inbox with your connector until the email arrives: about once a
+   minute, for up to 15 minutes. Read only the test email. Note its message id and the time
+   it arrived.
+4. Report what you read, with the address you sent it to (`sentTo`):
+
+```json
+{ "results": [{ "kind": "mailbox.received", "code": "CODE", "sentTo": "ADDRESS_YOU_SENT_TO", "message": "MESSAGE_ID", "receivedAt": "2026-11-04T12:01:00Z" }] }
+```
+
+```sh
+audienti outcomes report TASK_ID --file RESULTS.json
+```
+
+5. Delete both copies of the test email, the sent one and the received one, then report it:
+   `{ "results": [{ "kind": "mailbox.deleted", "message": "MESSAGE_ID" }] }`.
+6. Report the task done: `audienti queue done TASK_ID --note "test email confirmed"`.
+
+Use the code exactly as you read it back from the email; the dash and case do not matter.
+Only the task's own code confirms the mailbox. A code of an older test email is refused
+(`stale_code`), any other code too (`wrong_code`), and so is an email that arrived before
+the task asked for it (`received_before_asked`), and so is an email sent to another of your
+user's mailboxes (`other_mailbox`). Reporting the same email again returns
+`already_recorded`.
+
+You can do this check even if you can only read the workspace: your own test email is the
+one result a read-only agent may report.
+
+## When you cannot send or read
+
+Report which step failed, with a short reason, then report the task done:
+
+```json
+{ "results": [{ "kind": "mailbox.failed", "step": "send", "reason": "No Gmail connector" }] }
+```
+
+- `send`: you have no connector that can send from the mailbox, or the send failed. Tell
+  your user exactly: "I need a Gmail or Outlook connector to send from your mailbox."
+- `read`: the email went out but you cannot read the mailbox's inbox, or it did not arrive
+  in 15 minutes. Tell your user exactly: "I need a Gmail or Outlook connector that can read
+  your mailbox's inbox."
+
+Settings → Sending and Capabilities then show your user which step failed. No new task comes
+until they fix your connector and choose Send another test email. The task cannot be
+reported done until you reported `mailbox.received` or `mailbox.failed`
+(`mailbox_not_reported`).

package/skills/getting-started/references/outcome-checks.md

@@ -0,0 +1,114 @@
+# Outcome checks
+
+An outcome check is a queue task (`outcomes.check`) that asks you whether the people
+you invited on one of the user's LinkedIn accounts have accepted. Audienti schedules it
+for you at the cadence you reported for that LinkedIn account (`checkEverySeconds`, every 6 hours
+when you report none), and only while someone on that LinkedIn account waits for an accept. Each
+task lists at most 100 people, so a LinkedIn account with more people waiting gets several tasks
+in the same interval, and every waiting person is on one of them. You never decide when to check, and you never check
+anyone the task does not list.
+
+## What the task gives you
+
+The task's `detail` holds:
+
+- `seat`: the LinkedIn account to check (`account` is the LinkedIn account you reported, for example
+  `linkedin.com/in/owner`).
+- `waiting`: the people to check, at most 100. The list stays as it is while you hold
+  the task, so you can report on everyone it lists; no other check lists them meanwhile,
+  even one for the next interval. Each has `person` (the Audienti person
+  id you report against), `name`, `profileUrl` and `invitedAt` (when the invitation was
+  sent).
+
+The task requires `profile.invitations.read` on that LinkedIn account. If you hold it, the task is
+assigned to you.
+
+## The procedure
+
+1. Claim the task: `audienti queue claim TASK_ID`.
+2. Read the LinkedIn account's own sent invitations with your tool, or read each listed person's
+   profile to see the connection degree. Look up only the people in `waiting`. Do not
+   list, search or open anyone else, and do not page through the user's whole network.
+3. Keep to the limits you reported for this LinkedIn account. Spread reads out if your tool asks
+   you to. If you cannot check now (signed out, rate limited), release the task with a
+   note: `audienti queue release TASK_ID --note "why"`.
+4. Write what you found to a file and report it:
+
+```json
+{
+  "results": [
+    { "kind": "linkedin.accept", "person": "PERSON_ID", "at": "2026-11-01T09:30:00Z" },
+    { "kind": "linkedin.invite_closed", "person": "PERSON_ID", "reason": "withdrawn" },
+    { "kind": "linkedin.profile_degree", "person": "PERSON_ID", "degree": 2 }
+  ]
+}
+```
+
+```sh
+audienti outcomes report TASK_ID --file RESULTS.json
+```
+
+5. Report the task done: `audienti queue done TASK_ID --note "3 checked, 1 accepted"`.
+
+## Result kinds
+
+- `linkedin.accept {person, at}`: the person accepted. `at` is when they accepted, as
+  close as your tool tells you. Audienti ends the person's wait and plans the next step
+  of the playbook, which appears in your queue.
+- `linkedin.invite_closed {person, reason}`: the invitation is no longer pending.
+  `reason` is `withdrawn` (the user or you withdrew it) or `expired` (LinkedIn closed
+  it). Audienti records the fact; the wait still ends at its timeout.
+- `linkedin.profile_degree {person, degree}`: optional evidence, the connection degree
+  you read on the profile (1, 2 or 3). A 1 means connected; report it as an accept as
+  well when you know the time.
+
+A `steps.run` task (a comment, react, withdraw, follow or unfollow step of a playbook, for one person) takes these
+results instead. The task names the step in `detail.step` and tells you how to find the post.
+
+- `linkedin.comment {person, postUrl}`: you commented on the post. Comment only when you can add
+  material value; otherwise react.
+- `linkedin.reaction {person, postUrl, reaction}`: you reacted. `reaction` is `like` (the default),
+  `celebrate`, `support`, `love`, `insightful` or `funny`.
+- `linkedin.follow {person}` and `linkedin.unfollow {person}`: for a follow or unfollow step. Audienti records
+  that your account now follows the person, or no longer does. It skips a later Follow step for someone you
+  already follow, and an Unfollow step for someone you do not.
+- `linkedin.step_skipped {person, reason}`: nothing to engage with, or your user declined.
+- `linkedin.invite_closed {person, reason: withdrawn}`: for a withdraw step.
+
+Audienti records the step as run, and the playbook goes on to its next step.
+
+An `invitations.receive` task (every 6 hours, only on a seat whose connector can read received invitations)
+asks you to read the connection requests people sent to your user. Read only the pending received list. Never
+accept, decline or open anyone. Report each pending request:
+
+- `linkedin.invitation_received {ref, profileUrl, name, sentAt}`: give `ref` (the request id your connector shows,
+  otherwise the person's profile address) or `profileUrl`; `name` and `sentAt` when you have them. Audienti records
+  each request once and tells your user once. Report the same request again and it returns `already_recorded`.
+
+Report done with no results when no request is pending.
+
+Leave out anyone still pending. They stay on the next check until they accept or the
+wait times out.
+
+## What the report returns
+
+`results` has one entry per result you sent, in the same order. Each person is recorded
+on their own, so one person who cannot be recorded does not hold back the others.
+
+- `status`: `recorded` (written now), `already_recorded` (an earlier report wrote it;
+  `eventId` is that earlier event) or `not_recorded` (nothing was written).
+- `reason`: why, when there is one. `participation_ended` or
+  `participation_unavailable` means the fact was recorded but nobody moves, because
+  the person's campaign participation ended or its playbook cannot be read.
+  `not_found` with `not_recorded` means the person is no longer in the workspace.
+- `next`: the person's next step after the report, when there is one.
+- `failed`: the accept was recorded, but planning the next step failed. Audienti shows
+  the failure on the person's timeline; `reason` holds its code. Sending the same
+  accept again returns the same failure until it is resolved.
+
+## Errors
+
+- `not_claimed`: claim the task first, or your lease expired. Read the queue again.
+- `not_on_list`: you reported a person the task does not list. Report only the listed
+  people.
+- `validation_error`: a result has a wrong kind, person id or time.

package/skills/getting-started/references/replies.md

@@ -0,0 +1,186 @@
+# Handling a reply
+
+A reply task (`replies.handle`) means a prospect answered. The inbound itself is never
+approved: inbound wins, and you record it. What the user approves is your answer.
+
+## What to do
+
+1. Read the conversation: `audienti prospects conversation list PERSON --workspace ID`.
+2. Classify the reply as one of `interested`, `question`, `later`, `out_of_office`,
+   `stop`, `bounce`, `referral` or `wrong_person` (the prospect is the wrong person and
+   names no one else). A stop, a bounce or a referral must carry its typed
+   `result`, or the report is refused; see [Stop, bounce and referral](#stop-bounce-and-referral).
+3. Draft the answer from the mailbox or LinkedIn account the reply came to (the assignee's).
+   - Bind the recipient and the sender, or the answer waits in Blocked: the recipient's
+     `contactId` comes from `audienti prospects contacts list PERSON`, and the
+     `senderAccountId` is the user's confirmed sender account for that mailbox or LinkedIn account
+     (`audienti sender accounts list`).
+   - If you report `calendar.freebusy.read`, read the user's free times and offer up
+     to six slots in the answer. Put the same times in `slots`, so the user sees them on
+     the card: "Slots from your calendar · Thu 10:00, 14:30 ET". A scheduling tool that
+     reports only `calendar.read` is not the user's calendar and offers no slots.
+   - Without a calendar, ask the prospect for a time that suits them, and leave `slots`
+     out. The user's card says no agent has a calendar and links to the Capabilities
+     screen.
+4. Record the classification and the draft in one result, keeping the reply open:
+
+   ```sh
+   audienti prospects replies set PERSON --workspace ID --evidence EVIDENCE --file RESULT.json
+   ```
+
+   ```json
+   {
+     "requestId": "a new UUID for each result",
+     "expectedVersion": 0,
+     "status": "needs_handling",
+     "outcome": null,
+     "reason": "Interested and asked for a time on Thursday.",
+     "responseEvidenceId": null,
+     "classification": "interested",
+     "draft": {
+       "type": "email.send",
+       "content": { "subject": "Re: Late invoices", "body": "Thursday works. I have 10:00 or 14:30 ET. Which suits you?" },
+       "recipient": { "prospectId": "PERSON", "email": "jane@example.com", "contactId": "CONTACT" },
+       "sender": { "provider": "email", "accountRef": "owner@example.com", "senderAccountId": "SENDER" },
+       "reason": "Offers the two free slots on Thursday the prospect asked for.",
+       "slots": [
+         { "start": "2026-11-05T15:00:00Z", "end": "2026-11-05T15:30:00Z", "timeZone": "America/New_York" },
+         { "start": "2026-11-05T19:30:00Z", "end": "2026-11-05T20:00:00Z", "timeZone": "America/New_York" }
+       ]
+     }
+   }
+   ```
+
+   `expectedVersion` is the reply's current version (`audienti prospects replies get`).
+   The draft becomes a revision the user reviews in Operator. Nothing is sent until the
+   user approves it. A second result for the same reply replaces a draft the user has
+   not decided yet.
+5. Report the task done.
+
+The owner can also close a reply in Operator with "Mark handled" or "Not a reply". That records the same
+state as `replies set` with status `handled` or `not_reply`, and withdraws any answer you drafted for it
+that no agent has claimed to send. Read `replies get` before you set a reply again.
+
+To close a reply for the owner by CLI, pass the version you read as `expectedVersion`. Handled with no
+answer is `{"requestId":"<uuid>","expectedVersion":1,"status":"handled","outcome":"closed_without_response","reason":"The owner answered by phone."}`.
+Not a reply is `{"requestId":"<uuid>","expectedVersion":1,"status":"not_reply","reason":"An automatic message."}`;
+it has no outcome. Give `--file` an absolute path.
+
+The classification records a `replied` event on the person's active campaigns, except
+for `bounce` and `out_of_office`, which are not replies from the person.
+An `out_of_office` reply records an auto-reply instead. The playbook's out-of-office rule
+snoozes the person: the wait and the next step hold for 7 days, or until the return date
+when you pass `returnsOn`. Nothing is sent meanwhile and the person does not move. A
+`wrong_person` reply that names no one stops the sends and leaves the reply for the user to
+settle: ask who the right person is. When the reply names the right person, classify it as a
+`referral` with its typed `result`.
+
+## Stop, bounce and referral
+
+These three need no decision from the user. Classify the reply, report the typed
+`result` next to the classification it matches, and Audienti records it against the
+person. The classification without its result is refused with 400 naming the result it
+needs (`reply.stop`, `email.bounce` or `reply.referral`). Use the prospect's words,
+verbatim, for `quote`.
+
+- **Stop** (`stop`): the prospect asked not to be contacted. Report status `handled`,
+  outcome `suppressed` and no draft:
+
+  ```json
+  { "classification": "stop", "status": "handled", "outcome": "suppressed",
+    "result": { "type": "reply.stop", "scope": "person", "quote": "Please remove me from your list." } }
+  ```
+
+  The person is suppressed for good on every channel, their pending sends and open
+  tasks are withdrawn, and they leave their campaigns. The user cannot override it.
+  Use `"scope": "company"` only when they asked to stop for their whole company:
+  everyone at the company's domain is suppressed, and so is anyone added later. The
+  domain goes on the do-not-contact list marked "Asked to stop", and no one can remove it.
+  Never contact a person who asked to stop again, on any channel.
+- **Bounce** (`bounce`): a delivery failure came back instead of a reply. Report
+  status `not_reply` and no draft:
+
+  ```json
+  { "classification": "bounce", "status": "not_reply", "outcome": null,
+    "result": { "type": "email.bounce", "address": "priya@example.com", "kind": "hard", "evidence": "550 5.1.1 User unknown" } }
+  ```
+
+  `address` is the address that bounced: the person's own address, or one nobody in the
+  workspace holds. An address another person holds is refused with 409
+  `address_belongs_to_another_person`; report the bounce on the reply that came back
+  about that person instead.
+  `hard` means the address does not exist or refuses mail: it is marked bounced and
+  blocked in every campaign, and the person leaves the campaign as Bounced. `soft`
+  means a full mailbox or a temporary failure: the address is held for 24 hours, then
+  a retry task asks you to send the message once more. Retried once means exactly one
+  send: after the 24 hours the address takes one send, and every other send to it is
+  refused with `recipient_contact_bounced` until that send's outcome is known. A second
+  bounce within 14 days of the retry counts as hard; with no bounce in that time the
+  address opens again. Put the bounce message and its status code in `evidence`.
+- **Referral** (`referral`): the prospect is the wrong person and named someone else.
+  Report status `needs_handling` with a thank-you as the draft, and name the person:
+
+  ```json
+  { "classification": "referral", "status": "needs_handling", "outcome": null,
+    "result": { "type": "reply.referral", "name": "Sam Lee", "title": "Finance lead",
+      "email": "sam@example.com", "quote": "Wrong person, try Sam Lee in finance." },
+    "draft": { "type": "email.send", "content": { "subject": "Re: Late invoices", "body": "Thank you, Jane. I will reach out to Sam." }, "...": "recipient, sender and reason as above" } }
+  ```
+
+  Give `linkedinUrl` or `email` when the prospect gave them. Audienti finds or adds the
+  named person (an email someone in the workspace already holds names that person), links
+  the two records, and leaves the referrer as Not a fit with the note "referred to Sam
+  Lee". When the email and the LinkedIn profile belong to different people, the referral
+  is refused with 409 `identity_conflict`. Reporting the same referral again, from
+  another reply, changes nothing. The named person is not in the queue yet: a
+  `prospects.verify` task asks you to check them against the campaign's audience
+  first. The thank-you is an answer like any other: the user approves it in Operator
+  before it is sent.
+
+Every first email you draft ends with one plain sentence that lets the prospect opt
+out, such as "If this is not for you, reply and I will not write again." When they do,
+report it as a stop.
+
+## After the user approves
+
+A `work.execute` task with `action: send_reply` follows. Claim it, send the answer in
+the thread the prospect wrote in, report the result, then close the reply with status
+`handled`, outcome `response_recorded` and the sent message's evidence as
+`responseEvidenceId`.
+
+## When a meeting is booked
+
+- The prospect picks a slot: send the invite from the user's calendar
+  (`calendar.event.create`), then record `"meeting": { "at": "…Z", "source": "sent_invite" }`
+  in a `replies set` result.
+- The prospect sent an invite: set `"invite": true` with the classification. A
+  `meetings.confirm` task follows, assigned to one agent of the person's assignee that
+  is allowed to make workspace changes and reports `calendar.event.create` or
+  `meeting.book`. It accepts the invite on the
+  assignee's calendar and records `"source": "received_invite"`. If the assignee has no
+  such agent, no task appears.
+- The meeting moves the person to the playbook's goal stage. Record it once.
+
+## Before a meeting is booked
+
+Record where an unbooked meeting stands with `"meetingState"` in a `replies set` result:
+
+- `requested`: a time was asked for or offered.
+- `accepted`: they agreed, and no time is fixed yet.
+- `declined`: they said no to the meeting. A plain no is not a request to stop; classify the
+  reply on its own.
+
+Each state is written once, and only when it differs from the last one. Nothing is written after
+a booking. If a playbook step waits for a meeting and the wait runs out while the request is
+`requested` or `accepted`, Audienti first asks you for a follow-up, up to 3 times (the playbook
+can change the count and the wait; the default wait is 5 days). Write each follow-up yourself
+after you read the whole conversation, and send it on the thread's channel. Do not use a fixed
+template unless the user put one in your instructions. Save it as a plan action with the
+`playbookStepKey` the task names. After the last wait runs out, Audienti records
+`meeting_no_answer` itself and tells the owner. Do not record it.
+
+## Taken over
+
+When the user takes a person over, every open task and draft for them is withdrawn
+and no new task about them appears, in any campaign. There is no hand back. Do not
+contact them again. A draft for them is refused with `taken_over`.

package/skills/getting-started/references/reply-checks.md

@@ -0,0 +1,54 @@
+# Mailbox checks
+
+Audienti never signs in to your user's mailbox. You send from it through your own email
+connector (Gmail or Outlook, through Composio, a Claude connector or similar), so you also
+prove it works and read it for replies. Two queue tasks ask for that. If you have no email
+connector, tell your user exactly: "I need a Gmail or Outlook connector to send from your
+mailbox." Never send them to Settings to connect a mailbox.
+
+## The test email (`mailbox.confirm`)
+
+A mailbox counts for campaigns only once you sent a test email from it to itself, read it
+back and reported its code. [The mailbox test email](mailbox-check.md) gives the steps. Your
+user does nothing in that check. It proves the mailbox sends and that you can read its
+inbox, which the reply checks below need too.
+
+## The reply check (`replies.check`)
+
+Before any next step goes to someone you emailed, in a campaign or not, Audienti asks you to
+check the mailbox the email went out from for their reply. Until you report each person, no
+next step is planned or sent for them. Each task lists at most 100 people in `waiting`, each
+with `person`, `name`, `participation` (null when the step is in no campaign), `attempt`
+(the email) and `sentAt` (when it went out). A task for a mailbox you confirm is assigned to
+you.
+While you hold the task, its list stays as it was when you claimed it, even after a reply
+you record. Report everyone on it.
+
+1. Claim the task.
+2. Search the mailbox with your connector for mail from the listed people since their
+   `sentAt` only. Do not read anything else.
+3. Record each reply you find the way you record any reply: `audienti prospects
+   conversation append PERSON --workspace ID --file ITEM.json` with `direction: inbound`
+   and `conversationType: direct`. It returns the evidence id. Audienti then ends the
+   person's wait, holds their sends and gives you a reply task, as for any reply.
+4. Report every listed person:
+
+```json
+{
+  "results": [
+    { "kind": "email.no_reply", "person": "PERSON_ID" },
+    { "kind": "email.reply", "person": "PERSON_ID", "evidence": "EVIDENCE_ID" }
+  ]
+}
+```
+
+```sh
+audienti outcomes report TASK_ID --file RESULTS.json
+```
+
+5. Report the task done. If you cannot read the mailbox now, release the task with a note.
+
+An `email.reply` whose evidence is not an inbound message of that person is not recorded
+(`reply_not_recorded`): record the reply first. A person you leave out comes back on the
+next check, about an hour later. Reporting the same person again for the same email returns
+`already_recorded`.