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

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

@@ -4,12 +4,24 @@ An audience is a set of structured filters plus one smart rule. Discovery and fi
 read the structured filters first, so put everything you can into them. Free text is
 only for the one test the filters cannot express.
 
+An audience says **who** the buyer is: facts about the company and the person that stay
+true for months. It never says **why now**. Hiring, funding, a new leader, a tool
+change, a post or an intent to buy are events, and events are campaign signals (see
+section 5). An audience with an event in it matches almost no one.
+
 ## 1. Pick one buyer lane
 
 One audience describes one kind of buyer: one function at one seniority band, in one
 kind of company. If the offer sells to two different buyers (for example finance and
 operations), draft two audiences and two campaigns. Do not mix lanes in one audience.
 
+Every audience sets `person.functions`. Seniority alone is not a lane: "all VPs" reaches
+the VP of Finance and the VP of Engineering as well as the buyer. Pick the function that
+owns the problem the offer solves and signs for it. For example, an outbound or SDR
+agency sells to whoever owns pipeline: Sales, and Marketing when marketing owns
+pipeline. Add `currentTitles` such as "VP of Sales" or "Chief Revenue Officer" when the
+function is still too wide.
+
 ## 2. Resolve every value with `audience options`
 
 Never type a value from memory. Look each one up and copy the `providerId` and `name`
@@ -24,8 +36,19 @@ audienti audience options --kind functions --q finance
 audienti audience options --kind titles --q "head of finance"
 ```
 
-Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorities`,
-`functions`, `titles`. Over MCP, use `audience_options` with the same `kind`.
+Kinds: `industries`, `sizes`, `types`, `locations`, `seniorities`, `functions`, `titles`.
+Over MCP, use `audience_options` with the same `kind`. Name industries one by one: new
+audiences cannot add industry groups, because a group's industries do not match its name.
+
+- Search ignores case. Several terms in one query ("freight and logistics", or a
+  comma-separated list) return the matches for each term.
+- An industry search matches the industry's own name, not the group it sits in:
+  "logistics" returns the logistics industries, not airlines or rail.
+- Company size comes in LinkedIn's bands. A range in `--q` ("100 to 1000", "500+",
+  "under 50") returns every band it overlaps. Add all of them to `company.sizes`.
+- `functions` is LinkedIn's fixed list of 26 job functions. It needs no Sales Navigator
+  account.
+- A title that is not in the list can be saved as typed, without a `providerId`.
 
 ## 3. Fill the template
 
@@ -33,7 +56,7 @@ Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorit
 {
   "name": "Heads of finance, UK logistics, 51-500 staff",
   "company": {
-    "industries": [{ "providerId": "ID", "name": "Transportation, Logistics, Supply Chain and Storage" }],
+    "industries": [{ "providerId": "ID", "name": "Logistics and Supply Chain" }, { "providerId": "ID", "name": "Package/Freight Delivery" }],
     "sizes": [{ "providerId": "ID", "name": "51-200" }, { "providerId": "ID", "name": "201-500" }],
     "locations": [{ "providerId": "ID", "name": "United Kingdom" }]
   },
@@ -45,11 +68,14 @@ Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorit
   },
   "seniorityMatchMode": "at_least",
   "textCriteria": "The company runs its own truck or freight fleet.",
-  "notes": "Region and size inferred from the owner's last 20 sent emails; owner confirmed in Operator."
+  "notes": "Region and size inferred from the user's last 20 sent emails; user confirmed in Operator."
 }
 ```
 
 - `seniorityMatchMode: "at_least"` matches the chosen seniority and higher.
+- After saving, `audienti audience summary --audience ID` returns `sizes`: about how many
+  people the included industries, functions and regions reach, against the 1,000-person
+  minimum. Under 1,000, widen the industries, functions or regions.
 - Use `negative: true` on a value to exclude it (for example a competitor's industry).
 - `currentTitles` narrows the lane; keep it to the titles that buy, at most a few.
 
@@ -67,12 +93,51 @@ Good:
 Not allowed in the smart rule:
 
 - Provenance: "inferred from…", "based on the website", "found in sent email".
-- Hedges or open questions: "owner to confirm", "probably", "maybe", "TBD".
-- Values the filters already hold (industry, size, region, seniority, title).
+- Hedges or open questions: "user to confirm", "probably", "maybe", "TBD".
+- Values the filters already hold (industry, size, region, seniority, function, title).
 - More than one test joined with "and" or "or". Pick the one that matters most.
+- Events, timing or intent: "is hiring…", "recently raised…", "is considering…",
+  "is looking for…", "just changed…". These are campaign signals (section 5).
 
-Put provenance in `notes`. Put open questions to the owner in Operator with
+Put provenance in `notes`. Put open questions to the user in Operator with
 `audienti ask`, not in the audience.
 
+Saving refuses a smart rule that states the company's size or an event, and says where
+it belongs: size in `company.sizes`, events in a campaign signal.
+
 Check the rule before you save: `audienti audience improve --text "RULE"` returns a
 suggested rewrite when the rule is vague.
+
+## 5. Audience or signal?
+
+Ask of each condition: would it still be true of this company in six months?
+
+| Condition | Where it goes |
+| --- | --- |
+| Sells B2B software; 51 to 500 staff; based in the US | Audience filters |
+| Sells to hospitals; runs its own freight fleet | Audience smart rule |
+| Owns pipeline or revenue (VP of Sales, CRO) | Audience `person.functions`, `seniorities`, `currentTitles` |
+| Is hiring SDRs; is considering an outbound agency | Campaign signal |
+| Raised a round this quarter; new VP of Sales in the last 90 days | Campaign signal |
+
+A signal lives in the campaign's `signals` array. A `research` signal is a yes/no
+question a researcher answers from public evidence such as job posts, news or the
+company's site:
+
+```json
+{
+  "signalMatch": "any",
+  "signals": [{
+    "id": "UUID",
+    "kind": "research",
+    "scope": "company",
+    "question": "Is the company hiring SDRs or BDRs, or looking for an outbound agency?",
+    "expected": true,
+    "details": "Open SDR or BDR job posts, or a post asking for agency recommendations, in the last 90 days."
+  }]
+}
+```
+
+`signalMatch: "any"` lets a company qualify on any one signal; `"all"` needs every one.
+A signal narrows who is worth contacting now; it never replaces the audience, so the
+company and person still have to fit the audience.

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 approach from `approach list`, or a new one drafted with the approach-design skill, 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,8 +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` |
 
 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.