@audienti/cli 0.1.145 → 0.2.0-exora.10

package/skills/audienti/scripts/run.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { openSync, closeSync, readSync, realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { MAX_INPUT_BYTES } from './contracts.mjs';
+import { runHelper } from './profile-helpers.mjs';
+
+export function readHelperInput(path) {
+  const fd = path === '-' ? 0 : openSync(path, 'r');
+  try {
+    const chunks = []; let size = 0;
+    while (size <= MAX_INPUT_BYTES) {
+      const chunk = Buffer.alloc(Math.min(65536, MAX_INPUT_BYTES + 1 - size));
+      const count = readSync(fd, chunk, 0, chunk.length, null);
+      if (!count) break;
+      size += count; chunks.push(chunk.subarray(0, count));
+    }
+    if (size > MAX_INPUT_BYTES) throw new Error('Helper input exceeds 1 MiB.');
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+    catch { throw new Error('Helper input must be valid JSON.'); }
+  } finally { if (fd !== 0) closeSync(fd); }
+}
+
+export function executeHelperFile(name, path) {
+  // Neither a filename nor a helper name is ever imported or executed.
+  return runHelper(name, readHelperInput(path));
+}
+
+let isEntry = false;
+try { isEntry = Boolean(process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href); }
+catch { /* Imported from a synthetic runner without a file entry point. */ }
+if (isEntry) {
+  try {
+    const [name, flag, path, ...rest] = process.argv.slice(2);
+    if (!name || flag !== '--file' || !path || rest.length) throw new Error('Usage: node scripts/run.mjs HELPER --file INPUT.json|-');
+    process.stdout.write(`${JSON.stringify(executeHelperFile(name, path))}\n`);
+  } catch {
+    process.stderr.write('Skill helper failed. Use a bundled helper name and valid JSON input of at most 1 MiB.\n');
+    process.exitCode = 1;
+  }
+}

package/skills/getting-started/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: getting-started
+description: Run once, right after your Audienti connection is approved. Report the tools and connectors you already have, introduce yourself to the user, and propose a first campaign test (offer, audience, playbook, length) drafted from what you can already read, so the user only corrects it. Use again when your tools change or the user asks for a new test.
+---
+
+# Getting started with Audienti
+
+You have just been connected to a person's Audienti account. Audienti is an agentic CRM
+and the system of record for this work: audiences, offers, campaigns, people, companies
+and the work you do for them. The person who approved you is the user. The user wants
+to learn which playbook books meetings: turn their ideas into campaign tests quickly, do
+as much of the work as you can, and ask only for what you cannot find yourself. Write
+plainly and briefly, address the user as "you", no emoji, no marketing tone.
+
+Start every run with the work queue: `audienti queue next --json`. The reply opens with
+`orientation`: what Audienti is, who you are and how to work. Follow it. One read
+covers every workspace your user approved you in (`workspaces` lists them), so one
+schedule and one call are enough; `--workspace ID` narrows it to one. `next` is the task
+to take now; tasks you already hold are in `holding`, finish those first. Each task names
+its `workspace`: run every `audienti` command for it with `--workspace` and that ID, as
+`workspaceStep` says. Claim a task before you start it (`audienti queue claim TASK`), report it
+when you finish (`audienti queue done TASK --note "what you did"`) or release it
+(`audienti queue release TASK --note "why"`). Over MCP, use `agent_queue_list`,
+`agent_queue_claim`, `agent_queue_complete` and `agent_queue_release`. On a long task,
+claim it again every 20 to 30 minutes with a note that says where you are: that extends
+your lease and shows the user your progress; if your lease lapses, another agent may
+take the task and continue from your last note. A refused claim says why: `task_taken`
+(another agent holds it; pick another task), `task_closed` (done, skipped or no longer
+due; read the queue again) or `task_not_for_you` (the message says which: assigned to
+another agent; or it needs a capability you have not reported as connected, so report
+your tools again if you have one; or its requirements are being refreshed, so read the
+queue again and claim it from there). Your first task is usually
+**Report your tools and connectors**, part 1 of three: triage your tools and report
+them, asking nothing; introduce yourself and propose a first campaign as one question in
+Operator (`audienti ask`), not in chat; save the campaign as a draft once the user
+answers, and show five fits.
+
+## Rules that always apply
+
+- **Report, never connect.** List only the tools and connectors your runtime already
+  has. Do not install connectors, start OAuth or ask the user to sign in to anything
+  during this skill. If something is missing, say it is missing.
+- **Never invent.** Draft only from what you read. Do not make up customers, results,
+  numbers or claims. Mark anything you inferred as inferred.
+- **Draft, never send.** Everything you create is a draft. Nothing goes to a prospect.
+  The user activates a campaign in Audienti.
+- **Never include secrets.** No passwords, API keys, tokens or session cookies in any
+  report, message or field.
+- **Read-only does not stop you.** Run this skill right after connecting, without
+  waiting to be told. If the user left **Allow workspace changes** unticked, you can
+  still read, work the queue, report your tools and ask in Operator (`audienti ask`).
+  When a step has to save a record, ask the user there to turn it on in **Settings →
+  Agents**, and carry on with the rest.
+- **Audienti is the record.** Save what you and the user decide in Audienti records
+  (offer text, audience filters, campaign premise and notes), not only in chat or memory.
+
+## 1. Triage your tools
+
+First, keep yourself awake. Audienti never calls you, so set a durable schedule in your
+own host now that starts you and runs `audienti queue next` (no `--workspace`, so it
+covers all your user's workspaces), then does the work it returns: every 5 minutes during your user's working hours, every 15 minutes outside them
+(`queue next` names the hours in `orientation`; `pollAfterSeconds` gives the next gap). A
+timer inside your current session, such as a Claude Code `/loop` or a session cron, stops
+when the session ends and does not count. Use a schedule your host keeps: a Paseo schedule
+(`paseo schedule create`, then check it with `paseo schedule ls`), a Claude Code routine or
+cloud schedule, a Codex automation, or cron. Tell your user the schedule is set, and name
+it, when you introduce yourself. If your host cannot wake you, say plainly that it cannot
+wake you, so you only check when they message you.
+
+1. Confirm your connection: `audienti workspace list --profile AGENT_PROFILE`, then select
+   the workspace the user approved (`audienti workspace use ID --profile AGENT_PROFILE`;
+   over MCP, `workspace_select`).
+2. List every tool, connector, plugin and integration you can call now: your runtime's
+   own listing (tool list, connector settings, MCP servers, installed plugins) and every
+   integration hub you use. Check aggregators first: if you reach tools through Composio,
+   Treg or another hub, list each app connected there. Then list your native connectors.
+   Leave out Audienti's own hosted tools unless you reach them through another connector.
+3. Turn that list into capability rows (capability id, provider, `via`, the user's
+   `account` for anything you send as the user, access, status) as
+   [the capability report format](references/capabilities.md) describes; it has the
+   full catalog. Never write `via: audienti`.
+4. Report it: `audienti agent capabilities report --file CAPABILITIES.json --profile
+   AGENT_PROFILE` (over MCP, `agent_capabilities_report` with the same JSON; over HTTP,
+   `PUT /api/v1/agent-capabilities`). The report replaces the previous one, and the
+   user sees it in **Settings → Agents**. It counts as stale after seven days: report
+   again whenever your tools change, and at least weekly.
+5. Check what Audienti counts for you: `audienti agent capabilities --profile
+   AGENT_PROFILE` (over MCP, `agent_capabilities_list`): the rows that work now and the
+   ones that work with Audienti's hosted tools in this workspace.
+6. Install the skills you will use: `audienti skills list --compact`, then `audienti
+   skills read ID SKILL.md` and only the references the task needs (over MCP,
+   `skills_list` with `compact: true` and `skills_read`). The `audienti` skill covers
+   prospect finding and profile research; planning, writing and cadence skills are in
+   the `audienti/plugins` marketplace, installed with your runtime's plugin installer.
+
+Email goes out from your user's own mailbox through your own email connector (Gmail or
+Outlook, through Composio, a Claude connector or similar). If you have none, tell your user
+exactly: “I need a Gmail or Outlook connector to send from your mailbox.” Never send your
+user to Settings to connect a mailbox. If you have one, report the mailbox in your
+capability report and ask your user to approve it in **Settings → Sending**; then
+Audienti gives you a queue task to send one test email from the mailbox to itself, read it
+back and report its code; the mailbox counts once you do
+([the mailbox test email](references/mailbox-check.md)). Never ask your user for the code.
+A campaign can run without a mailbox: its people with an email step wait at that step, and their
+LinkedIn steps go on. Nothing is skipped. They go on once a mailbox is confirmed, so the fix is the
+email connector.
+
+## 2. Introduce yourself and propose a first campaign
+
+First check what already exists: `audienti campaign list`, `audienti offer list`,
+`audienti audience list`. If the workspace already has an active campaign, introduce
+yourself, list your tools and ask what the user wants to test next; skip the rest of
+this section.
+
+Otherwise draft a complete first campaign before you ask anything. Start from the
+user's own answers: `audienti workspace show` returns `startingAudience` (their website or
+`noWebsite`, what they sell, `about` the business, the first `offer`, and their target buyer:
+industries, company `sizes`, job functions, job `titles` and regions, with `providerId`s you
+can reuse; ask only for what they left out) and
+`approximateSize`, how many people Audienti can reach for that buyer (10000 means more
+than 10,000); both are `null` if they did not answer on the setup page. Treat them as the
+user's first audience, not a finished one. Under 1,000 people is too few to target: one
+sending account reaches about 500 a month, so the campaign runs dry within a month. If
+`approximateSize` is below 1,000, propose a wider buyer (more industries, job functions or
+regions) in your draft. Then read what your tools reach: the user's
+website, documents, recent sent email, CRM records and LinkedIn profile. Fill every
+field of [the campaign draft](references/campaign-draft.md) in the user's own words,
+offer first; if you cannot find an offer, your one question is what they sell and to
+whom. Build one buyer lane as structured filters, every value resolved with `audienti
+audience options --kind KIND --q TEXT`, always with the person function that owns the
+problem, plus at most one smart rule (`textCriteria`) a reviewer can answer true or
+false ([audience definition](references/audience.md)). The audience says who they are;
+anything about why now (hiring, funding, a new leader, an intent to buy) is a campaign
+signal, not a smart rule. Give the campaign at least one signal: prospect finding starts
+from signals, which find the companies that need the offer today ([the through line](references/campaign-draft.md#signals-the-through-line)).
+
+Ask the user in Audienti, not in chat: `audienti ask "QUESTION" --context "PROPOSAL"
+--option "Go" --option "Change it" --topic first_campaign`. It shows as a card in
+Operator, and the answer comes back to you as a task. The topic keeps one open card per
+subject (`first_campaign`, `campaign:ID` or `tools`): a new question with the same topic
+replaces the old one. Keep the question itself to one short sentence: the decision you
+need. Put the rest in the context, one short line per fact, in this order: who you are
+and what you will do; your tools in one line and what is missing, as a fact; the
+proposed campaign as a short card, marking what you inferred; the first message as you
+would send it, so the user can check the voice; every rule that cannot say exactly what
+the user asked for, with what you used instead (company size bands cannot express 200 to
+2,000 employees); a missing sending account for the playbook's first channel; at most two
+questions the user can answer on the same card; and that nothing is sent without their
+approval. Finding the five fits in section 3 costs credits, so ask for that OK on the
+same card: `--option "Approve, find 5 people for up to 20 credits" --option "Change it"`.
+A note the user types on the card comes with the option they pick. Give every cost in
+credits, never dollars. Name
+things the way the user sees them; never put IDs (campaign, signal, revision) in the
+question or the context.
+Whenever you propose something or ask the user to check your work, give the yes/no choice
+as options (`--option "Approve" --option "Change it"`): each option is a button that sends
+at once. Leave out error codes, status numbers and tool or provider names; say in plain
+words what happened and what you need. Link people and records with their URLs.
+[The campaign draft](references/campaign-draft.md) ends with an example of the shape.
+
+## 3. Save the drafts and show five fits
+
+When the user answers (a **Read your user's answer** task in your queue):
+
+1. Apply their changes. Save their words as they wrote them.
+2. Create the records with fresh request IDs, reusing each ID if you retry:
+   `audienti offer create`, `audienti audience create`, then `audienti campaign create`
+   with the premise, playbook, channels and `schedule.endAt` (over MCP, `offer_create`,
+   `audience_create`, `campaign_create`). The campaign starts in `Draft`; nothing runs
+   until the user starts it. Then save the pace: `audienti campaign pace ID --per-day N`
+   with the user's number, or `--per-day derived` when they kept it (over MCP,
+   `campaign_pace_set`). Only `campaign pace` takes `--per-day`; `campaign create` and
+   `update` refuse it. When the user approved a spend for finding, such as "find 5 people
+   for up to 20 credits", save the cap too: `audienti campaign pace ID --max-credits 20`.
+   Each day's find task carries it; pass it to `audienti campaign find` and never raise it.
+3. Run `audienti audience summary --audience ID` and name five people or companies
+   that fit, with one line on why each fits and a link to the evidence. If you have no
+   people-data tool, say so and show the audience filters instead.
+4. Ask the user with `audienti ask --campaign ID` to review it on the campaign page
+   and start it. Quote the campaign's own Pace line from `audienti campaign pace ID`.
+   Name the controls the page has: the status menu next to the campaign name offers
+   **Find prospects only**, which moves it to `Preparing`, where signal tracking and
+   prospect finding run, and **Activate campaign**, which moves it to `Active`, where
+   engagement runs too. There is no Start button.
+5. Then offer to draft first messages for the five fits once the campaign is active.
+
+If a create call fails, say what happened in one sentence and what you will do next; do
+not retry with a new request ID. For a later idea, draft a new campaign or a successor
+(`audienti campaign successor ID`) that changes one thing (playbook, offer or audience)
+and name what changed, so the two tests compare; save a new playbook as a template with
+the playbook-design skill, then pin it to the successor.
+
+## After getting started: work the queue
+
+After that, Audienti puts the daily work in your queue: get a draft campaign ready to
+start, find prospects at the campaign's pace, plan each prospect's next step, handle
+replies and send what the user approved. Every task carries its steps and names its
+skill; outcome checks follow [the check procedure](references/outcome-checks.md),
+replies [the reply procedure](references/replies.md), a mailbox's test email [the mailbox test email](references/mailbox-check.md), and the
+reply check before each email follow-up [the mailbox checks](references/reply-checks.md). When the user skips a touch, do
+not propose it again unless they ask for a rewrite; when they take a person over, leave
+them alone. A **Rewrite** (`work.revise`) comes to the agent that wrote the draft; its
+steps carry the commands. Answer the request with `audienti work changes respond`:
+saving the revision alone does not answer it, and the answer finishes the task. A new
+note from the user replaces the task, and the task closes when the user approves,
+skips or withdraws the touch, even while you hold it: then stop and read the queue
+again. Every first email ends with one plain sentence that lets the prospect opt out.
+Do not do work another agent holds (`fleet`); hand off or ask for help in a room
+(`audienti rooms send`). `needsOtherTools` lists tasks no agent can take: tell the
+user which connector would unlock them. A task there with `waitingOn: credits` needs an
+Audienti hosted tool and the workspace has no credits left: tell the user once that it
+waits on credits and runs when they add credits in Billing, and do not ask again. When
+credits are added or run out, or the user adds or removes one of their own provider keys
+in the Vault, every agent gets a notice task: run `audienti agent capabilities` again,
+then do what its steps say. If you reported an `owner.notify` capability, Audienti puts one
+**Tell your user about an alert** task in your queue for each alert it records. Its steps
+give the message and a link: tell your user that message on whatever channel you use with
+them (chat, push, Slack, SMS or email), include the link, and mark the task done once it
+is delivered. Done means delivered: a done task is not created again for the same alert.
+An agent that did not report `owner.notify` gets no such task. When the queue is empty, your timer runs it
+again after `pollAfterSeconds`; when `ask` or `queue next` returns an `announce` line,
+say it in your chat and point to Operator. Keep machine state in Audienti, not in your
+own memory: `audienti kv set KEY VALUE` stores cursors, change tokens, hashes, ids and
+timestamps for every agent of your user in this workspace, `audienti kv get KEY` reads
+them back on the next run, and `--if-version N` protects a key two agents may touch;
+credentials never go there: the Vault holds them and you store the Vault key name. Never
+send anything to a prospect that the user has not approved.

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

@@ -0,0 +1,143 @@
+# Audience definition
+
+An audience is a set of structured filters plus one smart rule. Discovery and fit checks
+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`
+the command returns:
+
+```
+audienti audience options --kind industries --q logistics
+audienti audience options --kind sizes
+audienti audience options --kind locations --q "United Kingdom"
+audienti audience options --kind seniorities
+audienti audience options --kind functions --q finance
+audienti audience options --kind titles --q "head of finance"
+```
+
+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
+
+```json
+{
+  "name": "Heads of finance, UK logistics, 51-500 staff",
+  "company": {
+    "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" }]
+  },
+  "person": {
+    "functions": [{ "providerId": "ID", "name": "Finance" }],
+    "seniorities": [{ "providerId": "ID", "name": "Director" }],
+    "currentTitles": [{ "providerId": "ID", "name": "Head of Finance" }],
+    "locations": [{ "providerId": "ID", "name": "United Kingdom" }]
+  },
+  "seniorityMatchMode": "at_least",
+  "textCriteria": "The company runs its own truck or freight fleet.",
+  "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.
+
+## 4. Write the smart rule (`textCriteria`)
+
+The smart rule is one criterion that a reviewer can answer true or false from a
+person's profile or company page. It covers only what the filters cannot express.
+
+Good:
+
+- "The company runs its own truck or freight fleet."
+- "The person manages accounts receivable or credit control."
+- "The company sells to hospitals."
+
+Not allowed in the smart rule:
+
+- Provenance: "inferred from…", "based on the website", "found in sent email".
+- 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 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

@@ -0,0 +1,80 @@
+# Campaign draft
+
+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. 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 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`). |
+| 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. |
+| 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`). |
+
+## Signals: the through line
+
+Prospect finding starts from signals: they find the companies that need the offer
+today. A campaign with no signal, no target companies and no finding instructions cannot
+start, so every signal campaign you draft has at least one signal. When the user already
+has the people, or a source Audienti does not have, draft a custom campaign instead:
+`method: "custom"`, finding instructions in the user's words and no signals. 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,
+logistics UK, problem-led email". When a later test changes one thing, say which in the
+name or notes.
+
+## Mapping to records
+
+| Draft part | Command | MCP tool |
+| --- | --- | --- |
+| 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.