@audienti/cli 0.2.0-exora.2 → 0.2.0-exora.21

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

@@ -0,0 +1,265 @@
+# 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`.
+
+## Label a message with its words
+
+A label says what a message means. Read the names with `audienti intent list`. A label goes on a message
+that is stored as evidence. Get its `EVIDENCE` ID from `audienti prospects conversation append` (when you
+store the message yourself) or `audienti prospects conversation list PERSON` (for one already stored); intake
+returns it too. Record one to three labels, each with the `quote` that supports it (at most 300 characters,
+copied from the message) and a plain `reason` (at most 200 characters, no IDs or error codes):
+
+```
+audienti intent record --person PERSON --evidence EVIDENCE \
+  --label interested --quote "we are interested in a demo" --reason "They ask for a demo next week."
+```
+
+Flags carry one label. Use `--file LABELS.json` for several labels or a typed detail (the `result` of a
+stop, bounce or referral; `meeting` for `meeting_booked`; `returnsOn` for `out_of_office`). A stop that
+asks for everything to end looks like this:
+
+```
+[{"label": "stop", "quote": "please stop writing to me", "reason": "They ask us to stop.",
+  "result": {"type": "reply.stop", "scope": "person"}}]
+```
+
+`audienti intent --help` prints this example. Give the same `--request-id` to repeat a call safely. Add
+`confidence` (`high`, `medium` or `low`) when you are unsure; it is stored only when you give it, and it
+does not change what the label does yet. A message keeps the labels it has: a second request that repeats
+one is refused with `already_recorded`, and one that would give the message a second reading is refused.
+
+Audienti checks every label and writes nothing if one fails. A refusal names the `field`, the `allowed`
+values and the `next` step. The checks:
+
+- The message is stored with its text. A message stored without a body cannot carry a label: submit the text as evidence.
+- The name is on the list, and fits the message direction and channel (`bounce` is email only).
+- The quote is in the message (subject and body), ignoring case and spacing.
+- The reason is plain words a person can read.
+- The labels fit together: `stop`, `bounce` and `out_of_office` stand alone; a message has one reading of the
+  reply and at most one meeting label.
+- The typed detail is present: a `stop`, `bounce` or `referral` needs its `result`; `meeting_booked` needs `meeting`.
+
+`replies set` records the same labels. Add `"intent": {"quote": "...", "reason": "..."}` next to `classification`
+or `meetingState` and it runs the same checks and stores the words on the event. Without `intent` it works as before.
+
+## Label a message you sent
+
+A message you sent can carry a label too. Today one fits: `meeting_requested`, for a message that asks for a
+meeting or offers a time ("could we find 20 minutes next week?"). Without it Audienti does not know a meeting
+was asked for, so the playbook's meeting wait cannot follow it up. With it the timeline shows the request, the
+wait sends up to 3 follow-ups, and a request nobody answers is marked No answer. No reply is needed.
+
+Do it after the send, in two calls. Store what you sent, then label it:
+
+```
+audienti prospects conversation append PERSON --workspace ID --file ITEM.json
+audienti intent record --person PERSON --evidence EVIDENCE \
+  --label meeting_requested --quote "find 20 minutes next week" --reason "We ask for a call next week."
+```
+
+`ITEM.json` holds a new `requestId` and the sent message. Give it the text exactly as you sent it:
+
+```
+{ "requestId": "<uuid>",
+  "item": {
+    "source": { "provider": "email", "accountRef": "you@yourcompany.com", "itemId": "<the provider's message ID>", "threadId": null },
+    "payload": { "direction": "outbound", "conversationType": "direct", "occurredAt": "2026-11-06T14:00:00Z",
+                 "subject": "Ten minutes on late invoices?", "body": "Hi Jordan, could we find 20 minutes next week?", "participants": null } } }
+```
+
+The call returns `EVIDENCE`. If you stored the message already, to report the send (`account_evidence`) or as
+the `responseEvidenceId` of an answer, use that same ID. The `quote` must be words from what you sent.
+The same checks apply: a message with no stored text, a quote that is not in it, or a label that does not fit a sent message (`interested` fits a reply, not an ask) is refused and writes nothing.
+
+- Label only a message that asks for or offers a meeting. A message that does not is not labeled.
+- A follow-up that asks again needs no label: the request is already on the timeline, so a repeat writes nothing.
+  The same message cannot take the label twice (`already_recorded`).
+- The label goes on the person's running campaign. A person runs in one campaign per workspace, so you need no option; `--participation ID` names the run if you want it explicit. The answer to `work execution send` or `report` carries that `participationId` when the send started a playbook step and the person still runs in the campaign run the send started, also when you repeat the call. A person who left and rejoined has a new run: a repeat of the old send names none. The label works without it.
+- An answer to a reply that offers times is labeled the same way, with the evidence of the answer you sent.
+
+## 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`. If your answer offers times for a meeting, label that sent message
+`meeting_requested` with the same evidence ("Label a message you sent").
+
+## 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. When the prospect writes about it, use `"meetingState"` in a
+`replies set` result. When you ask for the meeting in a message you sent, label that message
+`meeting_requested` (see "Label a message you sent"):
+
+- `requested`: a time was asked for or offered, by them or by you.
+- `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`.

package/skills/playbook-design/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: playbook-design
+description: Create, reuse or revise an Audienti playbook, the stages and steps a prospect moves through from first touch to the goal. Use during getting started, when a campaign has no playbook, and whenever you or the user have a new outreach idea.
+---
+
+# Playbook design
+
+A playbook is what a campaign follows: the stages a prospect moves
+through, the steps in each stage (channel, action, wait), the goal stage, the ways out
+(off-ramps) and the voice. Audienti stores every playbook with revisions, so a good one
+is written once and reused by many campaigns. Planning tasks (`prospects.plan`) read the
+campaign's playbook to decide each prospect's next step, so a campaign without one
+cannot be worked.
+
+Use this skill when:
+
+- You are getting started and the workspace has no playbook yet.
+- A queue task says a campaign needs a playbook (**Draft a playbook**, or a
+  **Get campaign ready** task that says "pick a playbook").
+- You or the user have a new idea for how to reach people: a new channel order, a
+  different first touch, a new voice, a new goal.
+
+## Rules
+
+- Reuse before you create. Most new campaigns fit a playbook that already exists.
+- Use only channels you can cover with accounts you reported (LinkedIn, Email). For anything you cannot do yourself, such as a call, a voicemail, a handwritten note, a video or a gift, use a `Custom` step: you prepare it and a person does it. A Custom step can wait for a named event the person records (`wait.until` `event`), for example "Gift delivered".
+  Do not draft a phone step if no one can call.
+- One playbook is one strategy. A correction to the same strategy (a wait, a step's
+  wording, a missing off-ramp) is a new revision. A different strategy is a new
+  playbook, so the two can be compared in Analytics.
+- Saving a playbook never changes campaigns already pinned to it. Pin the new
+  revision on purpose.
+- Never invent results or proof points for the voice. Use the user's words.
+- Every first email 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." Say so in the first
+  email step's `instructions`. A prospect who opts out is suppressed for good.
+- Ask the user before a new playbook is used for outreach. Nothing is sent without
+  their approval.
+
+## 1. Reuse first
+
+1. `audienti playbook list` shows one page of summaries: name, latest revision and stage and step
+   counts. Follow `nextCursor` for more; `--limit N` sets the page size.
+   Every workspace has three starter playbooks (`system: true`): Email first, LinkedIn
+   first and Email only. When your reported channels point to one, the list marks it
+   `recommended: true` and returns a `recommendation` with its `reason`. A confirmed
+   LinkedIn account gives LinkedIn first: the user registered it as a sender account and
+   authorized you on it, and your report for it is healthy and includes `send_message`.
+   Email with LinkedIn not yet confirmed gives Email first; email alone gives Email only.
+2. `audienti playbook show ID` shows the stages, steps, goal and voice.
+3. If one fits the campaign's offer, audience and your channels, use it. Say in one
+   line why it fits, then go to step 4 (pin it). A starter playbook can be pinned as it
+   is, but it is read-only: to change it, save its fields as a new playbook (no `id`,
+   `expectedRevision` 0) with a new name, and revise that copy. Saving a starter
+   playbook with its `id` fails with 409 `starter_playbook`.
+
+## 2. Draft a new playbook
+
+Start from the user's offer, the audience and the channels you have. A good default
+for founder-led or agent-led outbound has five to six stages:
+
+1. **Ready** (Agent): the prospect is in the campaign. No steps.
+2. **Warming** (Agent, optional): view the profile, like a recent post. Skip it when
+   LinkedIn is not available.
+3. **Outreach underway** (Agent): the touches, in order, with waits. For example a
+   connection request (wait 21 days), a message "Only if connected" (wait 5), a first
+   email (wait 4). Completes to the **Unresponsive** off-ramp when every step is done
+   and nobody replied.
+4. **In conversation** (Assignee): the prospect replied. A person drafts or approves
+   the reply. Completion `stay`.
+5. **Meeting requested** (Assignee).
+6. **Meeting booked** (Assignee, goal, `goalDays` 0).
+
+Write `instructions` on each step as coaching for whoever does it: what to say, what
+evidence to lead with, what to avoid. Write `voice` as two or three sentences in the
+user's style. See [fields and an example request](references/fields.md) for every
+field and the rules Audienti checks.
+
+## 3. Save it
+
+1. Write the request to a file: `expectedRevision` 0 and no `id` for a new playbook;
+   the playbook's `id` and its current revision number to revise one. Use a fresh
+   `requestId` (a UUID) and fresh UUIDs for every stage, step and off-ramp `key`.
+   Keep the same keys when you revise, so progress already recorded stays on its stage.
+2. `audienti playbook save --file REQUEST.json`. Over MCP use `playbook_save`.
+3. If the save fails, read the error: `field` is the path of the wrong value, `allowed` the
+   values that work and `next` what to do. Fix that field and retry with the same
+   `requestId`. Run `audienti playbook actions` for the step action ids, channels and event
+   names. If `next` says to ask your user (for example to turn on Allow workspace changes),
+   ask with `audienti ask` and carry on with what you can. If it reports a revision conflict, the error gives `currentRevision`: run
+   `playbook show ID`, apply your change to that revision and save with that `expectedRevision`.
+
+## 4. Ask the user and pin it
+
+1. Ask in Audienti, not in chat: `audienti ask "Use this playbook for CAMPAIGN?"
+   --context "SUMMARY" --option "Use it" --option "Change it"`. Put the stages, the
+   touches with their waits, the goal and the voice in the context as a short list.
+2. When they answer, apply their changes as a new revision.
+3. Pin it to the campaign with `playbookPin` `{ "id": PLAYBOOK_ID, "revision": N }`:
+   in `audienti campaign create` for a new campaign, or in the campaign's draft update
+   for a draft. An active campaign keeps its pin; to try a new playbook, make a
+   successor (below).
+
+## New ideas
+
+When you or the user have a new idea for how to reach people:
+
+1. Write the idea as one change: "Lead with email instead of a connection request",
+   "Add a phone step after the second email", "Offer a teardown, not a demo".
+2. If it is a correction, save a new revision of the same playbook.
+3. If it is a different strategy, save a new playbook named for the idea.
+4. Test it with `audienti campaign successor ID` that changes only the playbook, so
+   the old and new campaigns can be compared. Name what changed in the campaign notes.
+5. Ask the user before the successor starts.
+
+## Record progress and ask when the rules cannot decide
+
+Read the playbook before doing work for a campaign pinned to it: `audienti playbook
+show PLAYBOOK_ID`. Stage plays are instructions for you, the external agent; they are
+not a hosted sequence that runs by itself.
+
+- Progress: `audienti playbook record --file PATH` with exactly one of `stageKey`,
+  `offRampKey` or `finishStage: true`, the participation's pinned playbook version and
+  its current expected progress version, and stored evidence. Do not invent outcomes.
+  `audienti playbook` prints the command usage; the API schema has the required fields.
+- When you see something that moves a person (a reply, an accept, a booked meeting), record
+  that event; the playbook's rules decide the move. If the rules cannot decide, ask the
+  user with `audienti ask "QUESTION"`. The question appears in Operator.
+- None of these commands sends a message to a provider.
+
+## Done
+
+Close your queue task with a note that names the playbook, its revision and the
+campaign it is pinned to: `audienti queue done TASK --note "Saved Founder-led outbound
+r1, pinned to Logistics UK test"`.

package/skills/playbook-design/references/fields.md

@@ -0,0 +1,145 @@
+# Playbook fields
+
+`audienti playbook save --file REQUEST.json` accepts one object:
+
+| Field | Rule |
+| --- | --- |
+| `id` | Omit for a new playbook. The playbook ID to revise one. |
+| `expectedRevision` | 0 for a new playbook, otherwise the latest revision number. |
+| `requestId` | A fresh UUID. Reuse it only when you retry the same save. |
+| `fields` | The playbook itself, below. |
+
+## fields
+
+| Field | Rule |
+| --- | --- |
+| `name` | 1 to 120 characters. Name the strategy, not the campaign. |
+| `stages` | 2 to 30 stages, in order. Leave it out for the default skeleton (see Defaults). |
+| `goalKey` | The `key` of the goal stage. Not the first stage. Left out, it is the last stage (with `stages` left out too, the skeleton's last stage). |
+| `offRamps` | Up to 30 ways out: `{ key, name, reason }`. `reason` is `rejected`, `not_fit`, `nurture`, `unresponsive` or `other`. The system sets `taken_over`, `bounced` and `skipped` itself; do not choose them. "Bad data" and "repair" are not off-ramps. |
+| `voice` | How messages should sound, in the user's style. |
+| `eventRules` | Optional: what happens when an event reaches a person, for any stage and step. A new playbook starts with three (below); leave the field out to keep them, or send the whole list to replace it. See Event rules. |
+| `rules` | Optional: `allowBackward` (boolean, default false): let a move go to an earlier stage. Approval of a move is a setting on the account, not a playbook rule. |
+
+## Defaults
+
+When you change a playbook you already have, a part you leave out (`stages`, `goalKey`, `offRamps`, `voice`) stays as it is. For a new playbook, leave a field out and the server fills the best-practice value, the same on the CLI, MCP, REST and in the editor. What you write is kept, even a weak choice; the Playbook check warns about those.
+
+| Left out | Value |
+| --- | --- |
+| `stages` | Ready, Outreach underway (no steps; people who finish it leave as Unresponsive), In conversation (worked by a person) and Meeting booked as the goal. `playbook save` with only a `name` makes this. |
+| `offRamps` | Unresponsive, Not interested and Not a fit. |
+| an off-ramp `reason` | Guessed from the name (Not interested is `rejected`, Not a fit is `not_fit`, Unresponsive is `unresponsive`), else `other`. |
+| `voice` | One plain, short sentence. A blank voice gets it too. |
+| a stage `goalDays` | The waits of its main steps plus 2 days, at least 3. The goal stage gets 0. |
+| a stage `completion` | A stage with steps that an agent works, other than the goal, closes people out as Unresponsive. Other stages stay. |
+| a step `condition` | `Only if connected` for a LinkedIn message, else `Always`. |
+| a step `instructions` | One coaching sentence for the kind of action. |
+| a main step `wait` | Only for a step that is new in this save. A step that sends waits 3 days for a reply; a connection request waits 7 days for the accept; a step that sends nothing has no wait. A step the playbook already has keeps what it has, and `"wait": null` means no wait. |
+
+## The Playbook check
+
+Every read and save of a playbook returns `warnings`, a deterministic check that needs no agent. An item
+is `{ id, level, message, stageKey, stepKey, fix }`. A save is refused with `playbook_cannot_work` (422,
+the list in `errors`) when `offRamps` is empty or a stage has `on: []` and nothing sends people to it.
+The other items are warnings; read them after each save and clear them:
+
+| Item `id` | Meaning and default fix |
+| --- | --- |
+| `stage_never_ends` | A stage with steps and `completion` `stay`. Use `off_ramp` with the Unresponsive off-ramp. |
+| `stage_by_hand_only` | Nothing opens a stage but a person or agent. Give it an `on` event ("Jump forward to here when") or finish the stage before it with `next`. The first stage after Ready is not flagged. |
+| `send_without_wait` | A send step with no `wait`, followed by another send on the same channel. Add a wait. |
+| `goal_shorter_than_waits` | `goalDays` is below the waits added up. Use the waits plus 2 days. |
+| `send_in_person_stage` | A send step in the goal stage or an `Assignee` stage writes to someone who already answered. Remove it. |
+| `steps_after_break_up` | A step after the break-up email. Put it before the break-up step. |
+| `message_without_connection` | A LinkedIn message with condition `Always` and no connection request before it. Use `Only if connected`. |
+| `stages_loop` | Routes or rules send people between stages in a circle. |
+
+## Stage
+
+| Field | Rule |
+| --- | --- |
+| `key` | A UUID, unique in the playbook. Keep it across revisions. |
+| `name` | Unique in the playbook. |
+| `on` | The events that jump a prospect forward to this stage: `accept` (they accept your LinkedIn connection request, not a meeting invite), `reply` or `meeting` (a booked meeting). Do not list `accept` or `reply` on the goal stage unless a reply or an accept should count as a win. An event moves the prospect to the furthest later stage that lists it; the stages passed over are recorded as skipped, never as done. Leave it out for a stage people reach when the stage before it finishes, or when a person moves them. Do not set it on the first stage. People and the pipeline read "Starts when they reply" from it. The older `movesInWhen` text and the value `manual` are accepted and ignored. |
+| `owner` | `Agent` or `Assignee` (the person assigned to the prospect). |
+| `goalDays` | 0 to 365. The days after which a prospect in this stage is overdue (the pipeline card turns orange). 0 means never overdue. |
+| `enabled` | Defaults to true. `false` skips the stage: no one is moved into it. The first stage and the goal stage cannot be skipped. |
+| `steps` | Up to 20 steps. |
+| `completion` | `{ "kind": "next" }`, `{ "kind": "stay" }` or `{ "kind": "off_ramp", "offRampKey": KEY }`. The last enabled stage cannot use `next`. |
+
+## Step
+
+| Field | Rule |
+| --- | --- |
+| `key` | A UUID, unique in the playbook. A plan action that runs this step carries it as `playbookStepKey`; actions without it change no playbook progress. |
+| `channel` | `LinkedIn`, `Email` or `Custom`. A `Custom` step is something you cannot do, for example a phone call, a voicemail, a handwritten note, a video or a gift. You prepare the script, note or choice, and a person does it by hand and records what happened on the Hand tasks page. A Custom step is never a side step and sends nothing. |
+| `action` | A short label, for example "Send connection request". |
+| `condition` | `Always`, `Only if viable` or `Only if connected`. `Only if connected` is checked: a person who was sent a connection request and has not accepted is skipped for the step; a person with no request on record is not blocked, because they may already be connected. A stage that opens on `accept` gates the same way. Left out, a LinkedIn message gets `Only if connected` and everything else `Always`. |
+| `viability` | Required with `Only if viable`: when the step makes sense. An Email step is skipped, without a card, for a person with no email on record, whatever its condition. |
+| `instructions` | Coaching for whoever does the step. |
+| `wait` | Optional: `{ "until": U, "days": N }`. `until` is `accept` (LinkedIn steps only), `reply`, `meeting`, `timeout` or `event` (Custom steps only); `days` is 1 to 60. An `event` wait also needs `"event": "Gift delivered"` (the name of what the person records); the person records it on the Hand tasks page and that ends the wait, and so does a reply, a booked meeting or the days running out. The wait starts when the agent reports the step's result with its step key: a plan action carries the step's `key` as `playbookStepKey`, and a succeeded result for that action starts the wait. A reply or a booked meeting ends every wait early; an accept ends only a wait until `accept`. Older playbooks used `waitDays: N`, which still reads as `{ "until": "timeout", "days": N }`. |
+| `side` | Defaults to false. A side step runs while the main step before it waits, for example a profile view or a like. A stage with side steps needs a main step. |
+| `onTimeout` | `next` (default) or `off_ramp`. With `off_ramp`, a main step whose wait runs out leaves the prospect through the `unresponsive` off-ramp. When nothing is left in the stage, its completion decides. |
+| `routes` | Optional: `{ "accept"?: T, "reply"?: T, "meeting"?: T }`, where `T` is `{ "kind": "stage", "stageKey": "<uuid>" }` or `{ "kind": "off_ramp", "offRampKey": "<uuid>" }`. Where an event that reaches the person after this step ran sends them. The step's route wins over the stage's `on` list; an event with no route follows the stage. A main step only; `accept` only on a LinkedIn step. A route to an earlier stage needs `rules.allowBackward`. |
+| `actionId` | Optional: an action id from the outreach rulebook, for example `linkedin.message.send`. It must match the step's `channel`. List the valid ids with their channel and label: `audienti playbook actions` (MCP `playbook_actions_list`). The `action` text stays the label the person reads. |
+| `eventRules` | Optional, up to 10: event rules for this step only. See Event rules. |
+
+## Event rules
+
+An event rule says what happens when an event reaches a person: do these things, then go here. It lives on the playbook (`fields.eventRules`, up to 30), on a stage (`eventRules`, up to 10) or on a step (up to 10). The nearest place wins, then the most specific event: a reply kind beats any reply. A step `routes` entry is the older form of the same thing.
+
+| Field | Rule |
+| --- | --- |
+| `key` | A UUID, unique in the playbook. |
+| `when` | The event: `accepted`, `replied`, `meeting_booked`, `wait_timeout`, `inbound_connection_request`, or a reply kind `reply.interested`, `reply.question`, `reply.later`, `reply.out_of_office`, `reply.wrong_person`, `reply.referral`. An unknown name is refused with the allowed names; `audienti playbook actions` lists them under `eventRules.when`. |
+| `do` | Optional list of `stop_wait`, `snooze`, `redirect_to_named_person`, `ask_who_is_right`, `tell_me`, `hand_to_user`, `withdraw_pending_request`. Also under `eventRules.do`. |
+| `snoozeDays` | 1 to 90. For `snooze`. |
+| `goto` | Where the person goes after: `{ "kind": "stay" }`, `{ "kind": "gate" }` (the stage's own next step; the default), or `{ "kind": "stage", "stageKey": KEY }`, `{ "kind": "off_ramp", "offRampKey": KEY }` or `{ "kind": "step", "stepKey": KEY }`. |
+
+Every new playbook starts with these three on the playbook, when you send no `eventRules`:
+
+- `reply.interested`: `stop_wait`, then `gate`.
+- `reply.out_of_office`: `snooze` for 7 days, then `stay`.
+- `reply.wrong_person`: `stop_wait`, `redirect_to_named_person`, `ask_who_is_right`, then `stay`.
+
+Taking someone off the list and a bounce always run first; no rule changes them.
+
+A LinkedIn step whose `actionId` is `linkedin.inmail.send` runs only when the LinkedIn account reports InMail available. Otherwise it is skipped without a card.
+
+## Example request
+
+Replace every `<uuid>` with a fresh UUID (`uuidgen` or `node -e "console.log(crypto.randomUUID())"`).
+Use the same UUID wherever the same placeholder letter appears.
+
+```json
+{
+  "expectedRevision": 0,
+  "requestId": "<uuid>",
+  "fields": {
+    "name": "Founder-led outbound",
+    "stages": [
+      { "key": "<A>", "name": "Ready", "owner": "Agent", "goalDays": 3, "steps": [], "completion": { "kind": "next" } },
+      { "key": "<B>", "name": "Warming", "owner": "Agent", "goalDays": 7, "steps": [
+        { "key": "<uuid>", "channel": "LinkedIn", "action": "View profile", "condition": "Always", "instructions": "Read their recent activity for a signal to mention." },
+        { "key": "<uuid>", "channel": "LinkedIn", "action": "Like a recent post", "condition": "Always", "instructions": "Only a post about their work.", "wait": { "until": "timeout", "days": 3 } }
+      ], "completion": { "kind": "next" } },
+      { "key": "<C>", "name": "Outreach underway", "owner": "Agent", "goalDays": 35, "steps": [
+        { "key": "<uuid>", "channel": "LinkedIn", "action": "Send connection request", "condition": "Always", "instructions": "No note, or one line on their signal.", "wait": { "until": "accept", "days": 21 } },
+        { "key": "<uuid>", "channel": "LinkedIn", "action": "View profile", "condition": "Always", "instructions": "A light touch while the request waits.", "side": true },
+        { "key": "<uuid>", "channel": "LinkedIn", "action": "Send message", "condition": "Only if connected", "instructions": "Lead with their signal and offer something useful.", "wait": { "until": "reply", "days": 5 } },
+        { "key": "<uuid>", "channel": "Email", "action": "Email 1", "condition": "Always", "instructions": "Three sentences: signal, offer, one short question.", "wait": { "until": "reply", "days": 4 }, "onTimeout": "off_ramp" }
+      ], "completion": { "kind": "off_ramp", "offRampKey": "<R>" } },
+      { "key": "<D>", "name": "In conversation", "on": ["reply"], "owner": "Assignee", "goalDays": 3, "steps": [
+        { "key": "<uuid>", "channel": "Email", "action": "Draft a reply", "condition": "Always", "instructions": "Answer their question first. Propose a time only if they asked.", "wait": { "until": "reply", "days": 2 } }
+      ], "completion": { "kind": "stay" } },
+      { "key": "<E>", "name": "Meeting requested", "owner": "Assignee", "goalDays": 3, "steps": [], "completion": { "kind": "next" } },
+      { "key": "<F>", "name": "Meeting booked", "on": ["meeting"], "owner": "Assignee", "goalDays": 0, "steps": [], "completion": { "kind": "stay" } }
+    ],
+    "goalKey": "<F>",
+    "offRamps": [{ "key": "<R>", "name": "Unresponsive", "reason": "unresponsive" }],
+    "voice": "Write like a founder. Lead with their signal, offer something useful, and ask one short question.",
+    "rules": { "allowBackward": false }
+  }
+}
+```