@audienti/cli 0.2.0-exora.3 → 0.2.0-exora.5

package/skills/getting-started/references/campaign-draft.md

@@ -1,23 +1,44 @@
 # Campaign draft
 
-Fill this before you ask the owner anything. Mark each value with where it came from:
-`found` (quote or link), `inferred` (say from what) or `needed` (ask the owner).
+Fill this before you ask the user anything. Mark each value with where it came from:
+`found` (quote or link), `inferred` (say from what) or `needed` (ask the user).
 
 | Field | Where it goes | How to fill it |
 | --- | --- | --- |
-| Offer: what you sell | Offer | Website, pitch deck, proposals, email signature. Owner's words. |
-| Offer: problem it solves | Offer | Website, sent email, call notes. Owner's words. |
-| Offer: proof point | Offer | Only a result or customer the owner already states publicly or confirms. |
+| Offer: what you sell | Offer | Website, pitch deck, proposals, email signature. User's words. |
+| Offer: problem it solves | Offer | Website, sent email, call notes. User's words. |
+| Offer: proof point | Offer | Only a result or customer the user already states publicly or confirms. |
 | Company type, size, region | Audience filters | Current customers in the CRM or sent email; check values with `audience options`. |
-| Buyer title and seniority | Audience filters | Who replies to the owner or signs deals. |
+| Buyer function, seniority and title | Audience filters | The function that owns the problem the offer solves, then who replies to the user or signs deals. Always set a function. |
 | Who to avoid | Do-not-contact list | Current customers, partners, competitors (`dnc add` or `dnc import`). |
-| Premise | Campaign premise | One sentence: why these people, why now. |
-| Approach | Campaign approach pin | One published approach from `approach list`, with one line on why. |
+| Signals | Campaign `signals` | At least one. Events that make a company worth contacting now: hiring for a role, funding, a new leader, a tool change. Each one is a yes/no `research` question ([audience definition](audience.md) section 5). Never put these in the audience. |
+| Premise | Campaign premise | One sentence: why these people, why now. It names the signal and why the signal means they need the offer. |
+| Playbook | Campaign playbook pin | One playbook from `playbook list`, or a new one drafted with the playbook-design skill, with one line on why. When the list returns a `recommendation`, start from that starter playbook and name it with its `reason` in one line. |
 | Channels | Campaign channels | `email` and `linkedin`, only for accounts you reported. |
-| Test length | Campaign `schedule.endAt`, `schedule.maxCompanies` | 30 days from activation, or a company cap. |
-| Success measure | Approach goal stage | Meetings booked. |
+| Pace | Campaign pace | New people a day. Take the number and its reason from the **Pace line** in your queue task for the channels you propose: 25 a day per confirmed LinkedIn account, or the campaign's own number (50 by default) for email only. Write it as `Pace: 25 a day · 1 LinkedIn account · about 100 people a week`. Once the campaign is saved, `audienti campaign pace ID` returns its own line: use that line, so the card and the campaign page show the same number. The user can change it in their answer. |
+| Test length | Campaign `schedule.endAt`, `schedule.maxCompanies` | 30 days from activation or a company cap, whichever comes first. |
+| Success measure | Playbook goal stage | Meetings booked. |
+| Waits | Playbook step `wait` | What each step waits for (`accept`, `reply`, `meeting` or `timeout`) and for how many days; their sum fits the test length. A wait starts only when the agent reports a succeeded result for the plan action that carries the step's key as `playbookStepKey`, and any reply ends every wait (playbook-design `references/fields.md`). |
 
-Ask for at most two `needed` values in your first message. Fill the rest after the owner
+## Signals: the through line
+
+Prospect finding starts from signals: they find the companies that need the offer
+today. A campaign with no signal and no target list cannot start, so every campaign you
+draft has at least one. A signal is not "they might want to buy". It is an
+observable event that shows a company has the problem the offer solves, now. Build the
+line in this order:
+
+1. **Offer**: what it solves. "An outbound agency books meetings for B2B software teams."
+2. **Problem**: who has it. "The company needs pipeline and has no working outbound team."
+3. **Signal**: the event that shows the problem today. "The company is hiring SDRs or
+   BDRs": it has decided to invest in outbound but does not have the team yet.
+4. **Premise**: one sentence that joins them. "Companies hiring their first SDRs need
+   pipeline before the hires ramp; the agency books meetings in weeks."
+
+If you cannot name the event that shows the problem, ask the user what tells them a
+company needs the offer now. Do not leave the signals empty.
+
+Ask for at most two `needed` values in your first message. Fill the rest after the user
 replies.
 
 Name the campaign after the buyer and the test, for example "Heads of finance,
@@ -31,7 +52,27 @@ name or notes.
 | Offer | `audienti offer create --file OFFER.json --request-id UUID` | `offer_create` |
 | Audience | `audienti audience create --file AUDIENCE.json --request-id UUID` | `audience_create` |
 | Campaign | `audienti campaign create --file CAMPAIGN.json --request-id UUID` | `campaign_create` |
+| Pace | `audienti campaign pace ID --per-day derived`, or `--per-day N` with the user's number | `campaign_pace_set` |
 | Next test | `audienti campaign successor ID --file CAMPAIGN.json --request-id UUID` | `campaign_successor` |
 
-Run each command without arguments to see its fields, or read the API schema at
-`/api/v1/openapi.json`.
+Read each command's request fields in the API schema at `/api/v1/openapi.json`
+(search for the MCP tool name above). A campaign also needs the `audienceRevision`
+and `offerRevision` returned when you saved the audience and offer.
+
+## Example proposal
+
+The shape of a first proposal, not fixed copy:
+
+> I'm Arthur, your prospecting agent in Audienti. I find people who fit, research them
+> and draft first messages for you to review. I can use Gmail (read, draft), LinkedIn
+> through Composio, and web search. No CRM is connected, so records stay in Audienti.
+> Proposed first test, 30 days. Offer: late-invoice recovery for logistics firms (from
+> your website). Audience: finance function, Director and above, logistics companies,
+> 51 to 500 staff, UK (region inferred from your last 20 sent emails). Smart rule: the
+> company runs its own truck or freight fleet. Signal: the company is hiring a credit
+> controller or accounts receivable clerk. Premise: a company hiring for collections
+> has late invoices piling up now, and recovery gets cash back faster than a new hire. Playbook: problem-led email, then LinkedIn
+> follow-up. Pace: 25 a day · 1 LinkedIn account · about 100 people a week. Success:
+> meetings booked. Two questions: is the UK the right first region, and is there a
+> customer result I may cite? Answer "Go" to save it as a draft, or write your changes.
+> Nothing is sent until you approve it.

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

@@ -0,0 +1,214 @@
+# 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,
+      "inmail": { "available": true, "quotaPerMonth": 15 },
+      "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.
+- `inmail`: whether the LinkedIn account can send InMail, and its monthly quota. 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.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) | later |
+| `post.react` | linkedin, x, instagram, tiktok | send | React as the user (as the user) | later |
+| `post.publish` | linkedin, x, instagram, tiktok | send | Publish a post as the user (as the user) | later |
+
+### 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 | later |
+| `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 |
+
+### 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.

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,89 @@
+# 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.
+
+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,152 @@
+# 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` or `referral`. 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 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.
+
+## 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.
+
+## 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`.