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

package/cli/audienti.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { isAssignmentCommand, assignmentCli } from './assignment.mjs';
+import { playbookHelp } from './playbook-help.mjs';
 // The CLI is an HTTP client. It has no database access or separate business rules.
 const args = process.argv.slice(2);
 const usage = `Profiles: audienti profiles list|search|get ID | match evaluate|apply SOURCE CANDIDATE | history RESOLUTION (saved workspace records)
-Skills: audienti skills list|show audienti|helper NAME --file INPUT.json|- [--json]
-Tools: audienti tools list|describe|decide|runs|balance [--help]
-Sender: audienti sender accounts list|get|alias|register|bind|unbind|state|automation|activity report [--profile PATH]
+Skills: audienti skills list [--compact]|show SKILL|read SKILL RESOURCE|helper NAME --file INPUT.json|- [--json]
+Tools: audienti call TOOL ['JSON'] | tools search "WORDS"|get TOOL|list|runs|balance [--help]
+Sender: audienti sender accounts list|get|alias|register|bind|unbind|state|workspaces|automation|activity report [--profile PATH]
+Managed LinkedIn: audienti sender managed list|connect [--workspace ID] [--profile PATH] (connect: the user only; returns a sign-in link)
+                  audienti sender managed plan MANAGED_ACCOUNT_ID --plan free|premium_career|premium_business|premium_all_in_one|sales_navigator_core|sales_navigator_advanced|recruiter_lite|none [--workspace ID]  (the user only; sets the connection note length; none clears it)
 Prospecting: audienti prospecting settings show|save|accounts|account-show|account-save|history [--profile PATH]
 Usage: audienti whoami [--json]
        audienti workspace assignments list [--workspace ID]
@@ -23,61 +26,87 @@ Required environment:
   AUDIENTI_API_TOKEN  Account API token (create it from your Account page)
 
 Use HTTPS for remote hosts. Local HTTP is supported on loopback only.
-Agent commands: agent connect --name NAME [--capabilities find,enrich,listen,approve]|poll|cancel|list|revoke ID --profile PATH
+Agent commands: agent connect --name NAME [--write (ask for Allow workspace changes up front)] [--capabilities find,enrich,expand,research,engage,sync,notify,approve]|poll|cancel|list|revoke ID --profile PATH
 Owner permission change: agent permission ID --scope workspace:read|workspace:access --profile USER_PROFILE
-Owner capability change: agent capabilities ID --set find,enrich,listen,approve --profile USER_PROFILE (agents are refused outside this set)
-Agent capabilities: agent capabilities report --file REPORT.json --profile AGENT_PROFILE
+Owner capability change: agent capabilities ID --set find,enrich,expand,research,engage,sync,notify,approve --profile USER_PROFILE (agents are refused outside this set)
+Agent capabilities: agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE (capability rows; the old per-account shape still works)
+What the agent can do: agent capabilities [--workspace ID] [--json] --profile AGENT_PROFILE (works now, and works with Audienti tools)
 Read capabilities: agent capabilities show [--id AGENT_ID] --profile PROFILE
-Getting started: skills show getting-started, then agent inventory report --file INVENTORY.json --profile AGENT_PROFILE
-Read tool inventory: agent inventory show [--id AGENT_ID] --profile PROFILE
+Getting started: skills show getting-started, then agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE
+Read tool inventory: agent inventory show [--id AGENT_ID] --profile PROFILE (agent inventory report still works; capabilities report is current)
 Account authorization: agent accounts show [--id AGENT_ID] --profile PROFILE
 Authorize/revoke: agent accounts authorize --id AGENT_ID --provider email|linkedin --account REF --authorized true|false --profile OWNER_PROFILE
 Sharing: agent capabilities sharing --id AGENT_ID --profile OWNER_PROFILE
 Share/unshare: agent capabilities share --id AGENT_ID --provider email|linkedin --account REF --workspace ID --shared true|false --profile OWNER_PROFILE
 Team member: workspace member USER_ID [--workspace ID] --profile PROFILE
-Work execution: work execution claim|start|get PLAN --action ID; release|lookup --claim ID; report --attempt ID
+Work execution: work execution claim|start|send|get PLAN --action ID (send: managed LinkedIn accounts, --file with claimId and requestId); release|lookup --claim ID; report --attempt ID
 Work feedback: work changes request|list|get|respond|withdraw PLAN --workspace ID
-Work: work plan save|list|show|approve|withdraw-approval|cancel|eligibility
+Work: work plan save|list|show|approve|withdraw-approval|cancel|skip|eligibility
 Activity: work activity --workspace ID [--search TEXT] [--cursor-at ISO --cursor-id ID]
 Work list: work list --workspace ID [--order oldest|priority] [--queue review|blocked|activity]
+           a plan that only waits for its cadence is in neither review nor blocked; it returns to review when the wait ends
 Work writes: --file INPUT.json; human review needs a human workspace:access token
-Audiences: audience options --kind industries|locations|sizes|types|seniorities|titles|functions|industry_groups [--q TEXT]
+Audiences: audience options --kind industries|locations|sizes|types|seniorities|titles|functions [--q TEXT]
            audience list|show ID|create|update ID|archive ID|restore ID
            audience summary [--audience ID]|people ID|companies ID
            audience test ID --url LINKEDIN_URL --request-id UUID  (spends hosted credits unless the profile is saved)
 Files: file upload PATH --type MIME|list|prepare|register|download|delete ID (personal files, human token only)
-Queue: audienti queue [list]|next|claim ID|done ID [--note TEXT]|skip ID --note TEXT|release ID  (start here after you connect)
-Questions: audienti ask "QUESTION" [--context TEXT] [--option TEXT]... [--campaign ID] [--task ID]  (questions for your owner go to Operator, not chat)
+Hand tasks: hand-tasks [list [--state open|ready|done|skipped]]|show ID|done ID --outcome TEXT [--notes TEXT] [--result replied|meeting_booked]|skip ID --reason TEXT|event ID [--name TEXT]  (a person does a Custom step by hand and records what happened)
+Queue: audienti queue [list]|next|claim ID [--note TEXT]|done ID [--note TEXT]|skip ID --note TEXT|release ID [--workspace ID]  (start here after you connect; without --workspace an agent reads every workspace its user approved it in; done or skip again with a new --note corrects the note of a finished task)
+Attachments: audienti attachments upload FILE [--duration SECONDS]  (store an image or voice note, get its id for content.attachments)
+Outcome checks: audienti outcomes report TASK_ID --file RESULTS.json  (results for the people an outcomes.check task lists)
+Saved posts: audienti posts list [--topic-id ID]|get ID  (savedByOperationId names the tool run that saved a post; read it with audienti tools runs get ID)
+Saved topics: audienti topics list|get ID|create --input FILE --request-id UUID
+Questions: audienti ask "QUESTION" [--context TEXT] [--option TEXT]... [--campaign ID] [--task ID]  (questions for your user go to Operator, not chat)
            audienti questions [list] [--state open|answered|withdrawn|all] | show ID | withdraw ID | answer ID --answer TEXT
-Rooms: audienti rooms directory|inbox|ack|send|thread|threads|create|list|retire|restore|redact|resume|pause|profile|hook|watch|wait (audienti rooms help)
+Rooms: audienti rooms directory|inbox|ack|send|thread|threads|create|list|read|retire|restore|redact|resume|pause|profile|hook|watch|wait (audienti rooms help)
+KV: audienti kv get KEY|set KEY VALUE [--json] [--nx] [--if-version N] [--ttl 7d|--expires-at TIME]|list [--prefix P]|search [--key TEXT] [--value TEXT]|delete KEY  (small state between runs; never credentials)
 Offers: offer list|show ID|create|update ID|archive ID|restore ID
 Offer options: --file FIELDS.json --request-id UUID --expected-revision N --revision N --archived true|false
   audienti prospects replies set|get|list PERSON --workspace ID [--evidence EVIDENCE] [--file INPUT.json]
 Account intake: prospects intake --workspace ID --file INPUT.json
                 prospects conversation append|list PERSON --workspace ID
-Discovery: prospects list|get ID|observation create|citation create|evidence create
-           prospects contacts list|record PERSON --workspace ID
+Discovery: prospects list|get ID|timeline ID [--limit N]|observation create|citation create|evidence create
+           prospects contacts list|record PERSON [--file INPUT.json] [--request-id UUID] --workspace ID
            prospects contacts get|retire PERSON CONTACT --workspace ID
            prospects suppression get|set ID --workspace ID
+           prospects duplicates list --workspace ID | get|merge|dismiss PERSON --workspace ID [--primary PROFILE_ID]  (same name and photo: the newer record is held until you decide)
            guardrails show|pause|resume --workspace ID
            dnc list|add VALUE|remove VALUE --workspace ID
            dnc import --file LIST.csv --workspace ID  (at most 5,000 rows; reports added, skipped and invalid rows)
            dnc export [--output FILE.csv] --workspace ID
+           secret list [--workspace ID]  (names only)
+           secret get NAME [--workspace ID] [--json]  (prints the value; the secret records who read it last and when)
            budgets show --workspace ID
            budgets alerts --workspace ID [--limit N]
            usage breakdown [--workspace ID] [--since month|7d|30d|90d] [--by tool|provider|model|caller|day] [--format json|csv]
+           workspace usage summary|callers|calls [--after ID] [--caller user:ID|agent:ID|key:ID] [--status all|succeeded|failed|pending]|call ID [--workspace ID]  (paid tool use, last 30 days, and single calls)
+           intent list [--playbook ID] [--workspace ID]  (the closed set of message labels: name, direction, event, channels, typed detail; --playbook adds that playbook's own labels as customLabels; output is JSON)
+           intent suggest (--text TEXT | --text-file PATH) --channel email|linkedin [--direction inbound|outbound] [--context TEXT] [--request-id UUID] [--workspace ID]  (paid: what a message may mean, read by a model; prints the price per 1M input tokens first; suggests labels with a quote and reason, records nothing; keep one with intent record)
+           intent record --person ID --evidence ID --label NAME --quote TEXT --reason TEXT [--confidence high|medium|low] [--request-id UUID] [--participation ID] [--workspace ID]  (what a stored message means; get EVIDENCE from prospects conversation append|list; --file LABELS.json for several labels or a typed detail such as a stop result or a meeting time; every label is checked and a refusal says what to fix; a message you sent that asks for a meeting takes --label meeting_requested on its outbound evidence)
+           intent correct --person ID --event ID (--label NAME --quote TEXT --reason TEXT [--confidence high|medium|low] | --file LABEL.json | --retract) [--request-id UUID] [--workspace ID]  (a person changes or withdraws one label; the old one stays in the history; a change that routes the person elsewhere opens a decision and a change away from a stop never lifts it until a person confirms; an agent token is refused)
+           decision list [--state open|decided|all] [--person ID] [--participation ID] [--limit N] [--workspace ID]  (what Operator asks the person when the rules do not decide; an open decision holds its person)
+           decision options ID [--workspace ID]  (one decision with the options the playbook allows)
+           decision ask --participation ID [--reason TEXT] [--request-id UUID] [--workspace ID]  (ask the person to decide about one running person)
+           decision prepare ID --recommended OPTION_ID --option OPTION_ID=ANALYSIS ... [--file PREPARE.json] [--request-id UUID] [--workspace ID]  (an agent adds its view: two to five options, one line each)
+           decision answer ID --option OPTION_ID [--workspace ID]  (a person picks; the move runs once)
            audit list [--workspace ID] [--since 7d] [--actor agent|person] [--category NAME] [--format json|csv]
            budgets set --workspace ID [--agent ID --cap N|none] [--new-agent-cap N|none] [--at-limit pause|ask] [--alert80 on|off]  (alert80 covers Operator and email at 80%)
 Qualification: campaigns qualification submit --file INPUT.json
-Approaches: approach list|show ID|save --file REQUEST.json|progress ID|record --file REQUEST.json
-Analytics: analytics show --from ISO --to ISO [--campaign ID] [--approach-version ID] [--format json|csv]
+Campaign summary: campaign summary [--workspace ID]  (campaign counts per state, and per campaign its audience, offer, playbook, goal stage, people, engaged and at-goal counts)
+Find prospects: campaign find CAMPAIGN_ID --count N --max-credits C  (searches with the audience filters, checks each person, admits only fits; stops at N fits or the credit cap and reports the spend)
+                campaign check CAMPAIGN_ID --url LINKEDIN_URL [--request-id UUID]  (checks one person the same way; reuse the request ID after an interruption)
+Target companies: campaign targets CAMPAIGN_ID [--limit N --after CURSOR]  (reads the companies people must work at to join)
+                  campaign targets CAMPAIGN_ID --add acme.com,linkedin.com/company/globex [--remove old.com] | --set FILE|-  (one company per line; saves a new revision)
+Playbooks: playbook list [--archived] [--limit N --cursor ID]|actions|show ID [--revision N]|save --file REQUEST.json|archive ID|restore ID|draft show ID|save ID --file REQUEST.json|discard ID [--expected-updated-at T]|publish ID [--request-id UUID]|delete ID|progress PARTICIPATION_ID|record --file REQUEST.json|event PARTICIPATION_ID --kind KIND --reason TEXT  (audienti playbook SUBCOMMAND --help for the request shape)
+Analytics: analytics show --from ISO --to ISO [--campaign ID] [--playbook-version ID] [--format json|csv]
            analytics outbound [--workspace ID] [--days N | --from ISO --to ISO] [--by sender|action|day] [--format json|csv]
            analytics activity [--workspace ID] [--days N | --from ISO --to ISO] [--format json|csv]
            analytics cohorts [--workspace ID] [--stage goal|KEY] [--cohorts N] [--horizon N] [filters] [--format json|csv]
            analytics aging [--workspace ID] [--threshold-days N] [filters] [--format json|csv]
            analytics filters [--workspace ID]  (lists campaign, owner, offer, audience and tag values)
            (filters: --campaign ID --owner ID --offer ID --audience ID --tag TAG; also accepted by analytics show)
-Pipeline: pipeline show [--campaign ID] [--approach-version ID]
+Pipeline: pipeline show [--campaign ID] [--playbook-version ID]
 Connections: connections list|register --file REQUEST.json|report --file REQUEST.json
 Discovery writes use --file INPUT.json, --workspace ID and stable --request-id UUID
 Workspace commands: workspace init|list|create|show|search|invite|invitations|use
@@ -86,23 +115,74 @@ Read state: workspace notification-read --workspace ID --key KEY --read true|fal
 Search: workspace search --workspace ID --query TEXT [--people-only true] [--recent FILE.json]
 Invitation commands: workspace invitation show|accept|decline|retry|cancel ID
 Options: --workspace ID --name NAME --request-id UUID --email EMAIL --generation N
-Optional private profile: --profile PATH (outside this repository)
-Save an environment token: profile save --scope account:read|workspace:access|agents:manage --profile PATH
-Start local MCP stdio server: mcp
+Optional private profile: --profile PATH (outside this repository), or the AUDIENTI_PROFILE variable. --profile wins.
+Save an environment token: profile save --scope account:read|workspace:read|workspace:access|agents:manage --profile PATH
+Tokens: token show [--profile PATH]  (what the token can do; workspace:read can look but is refused on every change)
+Start local MCP stdio server: mcp  (audienti mcp --help for the settings)
 --json writes the API response envelope.
 `;
 
+const MCP_HELP = `audienti mcp starts the MCP server on stdio. An agent app runs it as a command; do not type it in a shell.
+Settings come from the environment of that command:
+  AUDIENTI_PROFILE   the profile file made by agent connect or profile save (the usual way)
+  AUDIENTI_API_URL and AUDIENTI_API_TOKEN   instead of a profile: the API URL ending in /api/v1 and a token
+The workspace: a tool that works in a workspace takes workspaceId in its input. Call workspace_select once with a workspaceId to set a default for the session.
+Tool names follow the commands: playbook_get for playbook show, playbook_draft_get for playbook draft show.
+Errors name the MCP tool to call next, not the command.`;
+// Example inputs for the commands that save prospects, so `--help` shows a working shape.
+const examples = {
+  'decision prepare': { recommended: 'snooze_30', options: [{ id: 'snooze_30', analysis: 'They said ask again in March, so wait a month.' }, { id: 'continue', analysis: 'Keep the plan; a follow-up may go this week.' }] },
+  'prospects conversation append': { requestId: 'UUID', item: { source: { provider: 'email', accountRef: 'you@yourcompany.com', itemId: 'PROVIDER_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 } } },
+  'intent correct': { label: 'not_interested', quote: 'not a fit for us right now', reason: 'They decline, so this is not interest.' },
+  'intent record': [{ label: 'stop', quote: 'please stop writing to me', reason: 'They ask us to stop.', result: { type: 'reply.stop', scope: 'person' } }],
+  'prospects observation create': { requestId: 'UUID', kind: 'person', source: { provider: 'linkedin', url: 'https://www.linkedin.com/in/jane-doe' }, fields: { name: 'Jane Doe', title: 'VP Sales', imageUrl: 'https://media.licdn.com/dms/image/PHOTO_ID' }, provenance: { url: 'https://example.com/team/jane' }, observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects citation create': { requestId: 'UUID', source: { kind: 'prospect', id: 'PERSON_PROSPECT_ID' }, target: { kind: 'prospect', id: 'COMPANY_PROSPECT_ID' }, edgeType: 'works_at', roles: [{ roleId: 'role-1', title: 'VP Sales', current: true, observedAt: '2026-01-01T00:00:00Z' }] },
+  'prospects evidence create': { requestId: 'UUID', subject: { kind: 'person', prospectId: 'PROSPECT_ID' }, campaignId: 'CAMPAIGN_ID', campaignRevision: 1, kind: 'interpretation', data: { conclusion: 'Leads a 40-person sales team', reason: 'Team page lists her as VP Sales' }, sourceUrl: 'https://example.com/team', observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects contacts record': { kind: 'email|linkedin|mobile|phone', value: 'jane@example.com, or +15551234567 for a mobile or a direct office phone', reason: 'Published on https://example.com/contact', requestId: 'UUID', provenance: { observationId: 'OBSERVATION_ID' } },
+  'campaigns qualification submit': { requestId: 'UUID', campaignId: 'CAMPAIGN_ID', campaignRevision: 1, prospectId: 'PERSON_PROSPECT_ID', companyProspectId: 'COMPANY_PROSPECT_ID', companyIcp: { status: 'pass|fail|unverified', evidenceIds: ['COMPANY_EVIDENCE_ID'] }, personIcp: { status: 'pass|fail|unverified', evidenceIds: ['PERSON_EVIDENCE_ID'] }, signal: { status: 'match|no_match|unverified|not_required', evidenceIds: [] }, fit: { status: 'high|moderate|low|no_fit|unscored', evidenceIds: ['PERSON_EVIDENCE_ID'], reason: 'why' }, skill: { id: 'signal-prospect-research', version: '1' } },
+};
+
+function commandHelp() {
+  const words = args.slice(0, args.findIndex(value => value.startsWith('-'))).filter(Boolean);
+  const lines = usage.split('\n');
+  let shown = [];
+  for (let n = Math.min(words.length, 2); n > 0 && shown.length === 0; n--) {
+    const prefix = words.slice(0, n).join(' ');
+    shown = lines.filter(line => line.includes(prefix));
+  }
+  console.log(shown.length ? shown.map(line => line.trim()).join('\n') : usage);
+  const example = Object.entries(examples).find(([command]) => words.join(' ').startsWith(command) || (words.length > 0 && command.startsWith(words.join(' '))));
+  if (example) console.log(`\nExample --file INPUT.json for ${example[0]}:\n${JSON.stringify(example[1], null, 1)}\n${example[0].startsWith('decision') ? 'Choose option ids from `audienti decision options ID`. One plain line each, at most 140 characters, no IDs or error codes.' : example[0].startsWith('intent') ? `\nA message you sent that asks for a meeting (store it first with prospects conversation append, direction outbound):\naudienti intent record --person PERSON --evidence EVIDENCE --label meeting_requested --quote "find 20 minutes next week" --reason "We ask for a call next week."\nRules: the "Label a message with its words" and "Label a message you sent" sections of the getting-started replies reference.` : 'Steps and rules: the "Save prospects and contacts" section of llms.txt.'}`);
+}
+
+/** Says what is wrong with a command no handler took, instead of one message for every case. */
+function unknownCommandMessage(words) {
+  const first = words[0];
+  if (first === undefined) return 'Give a command. Use audienti --help.';
+  if (first.startsWith('-')) return `Put the command first, then its options: audienti COMMAND [--workspace ID] [--profile PATH]. "${first}" is an option, not a command. Use audienti --help.`;
+  if (first === 'mcp') return 'mcp starts the local MCP server and takes no options. Run: audienti mcp';
+  return `"${first}" is not an audienti command. Use audienti --help for the commands. Most commands also take --workspace ID, and --profile PATH when the profile is not set in AUDIENTI_PROFILE.`;
+}
+
 async function main() {
+  if (args[0] === 'playbook' && args.slice(1).some(value => value === '--help' || value === '-h')) { console.log(playbookHelp(args[1]?.startsWith('-') ? undefined : args[1] === 'draft' && args[2] && !args[2].startsWith('-') ? `draft_${args[2]}` : args[1])); return; }
+  if (args[0] === 'mcp' && args.length === 2 && (args[1] === '--help' || args[1] === '-h')) { console.log(MCP_HELP); return; }
+  if (args.length > 1 && args.slice(1).some(value => value === '--help' || value === '-h') && !['tools', 'call', 'skills'].includes(args[0])) { commandHelp(); return; }
   if(args[0]==='prospects'&&['intake','conversation'].includes(args[1])){const {accountIntakeCli}=await import('./account-intake.mjs');await accountIntakeCli(args);return;}
   if(args[0]==='sender'){const {senderAccountsCli}=await import('./sender-accounts.mjs');await senderAccountsCli(args);return;}
   if(args[0]==='prospecting'){const {prospectingSettingsCli}=await import('./prospecting-settings.mjs');await prospectingSettingsCli(args);return;}
   if(args[0]==='prospects'&&args[1]==='replies'){const {accountRepliesCli}=await import('./account-replies.mjs');await accountRepliesCli(args);return;}
   if(args[0]==='prospects'&&args[1]==='contacts'){const {recipientsCli}=await import('./recipients.mjs');await recipientsCli(args);return;}
   if(args[0]==='usage'){const {usageCli}=await import('./usage.mjs');await usageCli(args);return;}
+  if(args[0]==='decision'){const {decisionCli}=await import('./decision.mjs');await decisionCli(args);return;}
+  if(args[0]==='intent'){const {intentCli}=await import('./intent.mjs');await intentCli(args);return;}
   if(args[0]==='audit'){const {auditCli}=await import('./audit.mjs');await auditCli(args);return;}
+  if(args[0]==='secret'||args[0]==='secrets'){const {secretsCli}=await import('./secrets.mjs');await secretsCli(args);return;}
   if(args[0]==='budgets'){const {budgetsCli}=await import('./budgets.mjs');await budgetsCli(args);return;}
   if(args[0]==='guardrails'||args[0]==='dnc'){const {guardrailsCli}=await import('./guardrails.mjs');await guardrailsCli(args);return;}
   if(args[0]==='prospects'&&args[1]==='suppression'){const {suppressionCli}=await import('./suppression.mjs');await suppressionCli(args);return;}
+  if(args[0]==='prospects'&&args[1]==='duplicates'){const {duplicatesCli}=await import('./duplicates.mjs');await duplicatesCli(args);return;}
+  if(args[0]==='call'){const {callCli}=await import('./tools.mjs');await callCli(args);return;}
   if(args[0]==='tools'){const {toolsCli}=await import('./tools.mjs');await toolsCli(args);return;}
   if(['topics','posts'].includes(args[0])){const {contentCli}=await import('./content.mjs');await contentCli(args);return;}
   if(args[0]==='work'&&args[1]==='execution'){const {workExecutionCli}=await import('./work-execution.mjs');await workExecutionCli(args);return;}
@@ -111,18 +191,22 @@ async function main() {
   if(['prospects','campaigns'].includes(args[0])){const {discoveryCli}=await import('./discovery.mjs');await discoveryCli(args);return;}
   if(args[0]==='analytics'&&['cohorts','aging','filters'].includes(args[1])){const {cohortCli}=await import('./cohorts.mjs');await cohortCli(args);return;}
   if(args[0]==='analytics'&&['outbound','activity'].includes(args[1])){const {outboundCli}=await import('./outbound.mjs');await outboundCli(args);return;}
-  if(['approach','analytics','pipeline','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
+  if(['playbook','analytics','pipeline','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
   if(args[0]==='campaign'){const {campaignCli}=await import('./campaigns.mjs');await campaignCli(args);return;}
   if(args[0]==='audience'){const {audienceCli}=await import('./audiences.mjs');await audienceCli(args);return;}
   if(args[0]==='file'){const {fileCli}=await import('./files.mjs');await fileCli(args);return;}
   if(args[0]==='ask'){const {askCli}=await import('./questions.mjs');await askCli(args);return;}
   if(args[0]==='questions'){const {questionsCli}=await import('./questions.mjs');await questionsCli(args);return;}
+  if(args[0]==='hand-tasks'){const {handTasksCli}=await import('./hand-tasks.mjs');await handTasksCli(args);return;}
   if(args[0]==='queue'){const {queueCli}=await import('./queue.mjs');await queueCli(args);return;}
+  if(args[0]==='attachments'){const {attachmentsCli}=await import('./attachments.mjs');await attachmentsCli(args);return;}
+  if(args[0]==='outcomes'){const {outcomesCli}=await import('./outcomes.mjs');await outcomesCli(args);return;}
   if(args[0]==='rooms'){const {roomsCli}=await import('./rooms.mjs');await roomsCli(args);return;}
+  if(args[0]==='kv'){const {kvCli}=await import('./kv.mjs');await kvCli(args);return;}
   if(args[0]==='offer'){const {offerCli}=await import('./offers.mjs');await offerCli(args);return;}
   if (args[0] === 'agent') { const { agentCli } = await import('./agents.mjs'); await agentCli(args); return; }
   if (isAssignmentCommand(args)) { await assignmentCli(args); return; }
-  if (['workspace', 'profile'].includes(args[0])) { const { workspaceCli } = await import('./workspaces.mjs'); await workspaceCli(args); return; }
+  if (['workspace', 'profile', 'token'].includes(args[0])) { const { workspaceCli } = await import('./workspaces.mjs'); await workspaceCli(args); return; }
   if (args[0] === 'profiles') { const { profilesCli } = await import('./profiles.mjs'); await profilesCli(args); return; }
   if (args[0] === 'skills') { const { skillsCli } = await import('./skills.mjs'); await skillsCli(args); return; }
   if (args[0] === 'mcp' && args.length === 1) { await import('./mcp.mjs'); return; }
@@ -132,12 +216,19 @@ async function main() {
   if (args[0] === 'whoami' && profileIndex > 0 && args[profileIndex + 1]) {
     const { configuration } = await import('./workspaces.mjs');
     profileConfig = configuration(args[profileIndex + 1], 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token. Agents confirm their connection with: audienti workspace list --profile PATH');
     args.splice(profileIndex, 2);
+  } else if (args[0] === 'whoami' && profileIndex < 0 && process.env.AUDIENTI_PROFILE && !(process.env.AUDIENTI_API_URL && process.env.AUDIENTI_API_TOKEN)) {
+    // The profile named by AUDIENTI_PROFILE (#448), unless the URL and token are in the environment.
+    const { configuration } = await import('./workspaces.mjs');
+    profileConfig = configuration(undefined, 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token, and AUDIENTI_PROFILE holds none. Agents confirm their connection with: audienti workspace list');
   }
-  if (args[0] !== 'whoami' || args.length > 2 || (args[1] && args[1] !== '--json')) throw new Error('Unknown command or option. Use audienti --help.');
+  if (args[0] !== 'whoami') throw new Error(unknownCommandMessage(args));
+  if (args.length > 2 || (args[1] && args[1] !== '--json')) throw new Error('whoami takes only --json and --profile PATH. Use audienti --help.');
   const rawUrl = profileConfig ? profileConfig.url : process.env.AUDIENTI_API_URL;
   const token = profileConfig ? profileConfig.token : process.env.AUDIENTI_API_TOKEN;
-  if (!rawUrl || !token) throw new Error('Set AUDIENTI_API_URL and AUDIENTI_API_TOKEN. Create a token from your Account page.');
+  if (!rawUrl || !token) throw new Error('Set AUDIENTI_API_URL and AUDIENTI_API_TOKEN, or pass --profile PATH (or set AUDIENTI_PROFILE) to a profile with an account:read token. Create a token from your Account page.');
   let base;
   try { base = new URL(rawUrl); } catch { throw new Error('AUDIENTI_API_URL must be a valid API base URL.'); }
   if (base.username || base.password || base.search || base.hash) throw new Error('The API URL must not contain credentials, query parameters, or a fragment.');
@@ -163,4 +254,4 @@ async function main() {
   console.log(args[1] === '--json' ? JSON.stringify({ data: profile }) : `${profile.email ?? profile.username ?? profile.id}\nAccount ID: ${profile.id}`);
 }
 
-main().catch(error => { console.error(error.toJSON ? JSON.stringify({ error: error.toJSON() }) : `Audienti: ${error.message}`); process.exitCode = 1; });
+main().catch(error => { console.error(JSON.stringify({ error: error.toJSON ? error.toJSON() : { code: 'client_error', message: error.message } })); process.exitCode = 1; });

package/cli/audit-operations.mjs

@@ -5,13 +5,13 @@ export const auditOperations = {
   schema: z.object({
    workspaceId: z.string().uuid().optional(),
    actor: z.enum(['person', 'agent']).optional(),
-   category: z.enum(['guardrails', 'budgets', 'approvals', 'suppression', 'members', 'agents']).optional(),
+   category: z.enum(['guardrails', 'budgets', 'approvals', 'suppression', 'members', 'agents', 'replies', 'billing', 'playbooks']).optional(),
    since: z.string().datetime().optional(),
    until: z.string().datetime().optional(),
    cursor: z.string().max(500).optional(),
    limit: z.number().int().min(1).max(200).optional(),
   }).strict(),
   method: 'GET', path: a => `/workspaces/${a.workspaceId}/audit-events?${query(a)}`, scoped: true,
-  description: 'List the read-only workspace audit log: who changed guardrails, budgets, approvals, suppression, members and agent access, newest first. Admin only. Page with cursor.',
+  description: 'List the read-only workspace audit log: who changed guardrails, budgets, approvals, suppression, members, agent access and playbooks (who saved which version), newest first. Admin only. Page with cursor.',
  },
 };

package/cli/campaign-find.mjs

@@ -0,0 +1,155 @@
+import {randomUUID} from 'node:crypto';
+import {HostedResponseUnknown} from './workspaces.mjs';
+// #257: find N prospects for a Campaign. Searches LinkedIn with the Audience filters, then asks the server
+// to check each new person. The server fetches, runs the rules and records the result; this file only
+// drives the loop and adds up the spend. Amounts are pico USD (1 credit = 10,000,000,000).
+export const PICO_PER_CREDIT=10_000_000_000n;
+// Waits before each retry of a check whose outcome is unknown, in milliseconds.
+const RECOVERY_WAITS=[2000,5000,15000];
+const OUTCOMES=['fit','held','not_fit','already_found'];
+// Only a definite answer lets the run go on. A check that is still open, a lost response or a server
+// error may still be paying, so the same request ID is retried; anything else unexpected stops the run.
+const pending=error=>error instanceof HostedResponseUnknown||error?.code==='check_running'||error?.status>=500&&!['tool_unavailable','history_policy_unavailable'].includes(error?.code);
+// A refusal about this one person (a bad URL, no LinkedIn profile) is final, and the run moves on.
+const skippable=error=>[400,404,422].includes(error?.status);
+const MAX_SEARCHES=12,MAX_PAGES=10;
+const positive=list=>(list??[]).filter(item=>!item.negative);
+const numeric=value=>typeof value==='string'&&/^\d{1,20}$/.test(value);
+// A charge the server reported for one request. Charges are cumulative per request ID, so the largest one
+// seen across attempts is the request's charge so far.
+const reportedCharge=value=>numeric(value)?BigInt(value):0n;
+
+/** One profiles.search input per title, location and keyword combination the Audience and Campaign name. */
+export function planSearches(audience,signals=[]){
+ const titles=positive(audience.person?.currentTitles).map(item=>item.name).filter(Boolean).slice(0,5);
+ // #281: the people search has no company region filter, so with no person location the company's region is
+ // searched as where the person is. Without it the search pays to check people anywhere in the world.
+ const places=positive(audience.person?.locations).length?positive(audience.person?.locations):positive(audience.company?.locations);
+ const locations=places.slice(0,3).map(item=>numeric(item.providerId)?{geoId:item.providerId}:{location:item.name});
+ // #322: the search takes 20 industry ids at a time, so a longer list is split across searches, never cut.
+ const industryIds=[...new Set(positive(audience.company?.industries).map(item=>item.providerId).filter(numeric))];
+ const industryChunks=[];for(let i=0;i<industryIds.length;i+=20)industryChunks.push(industryIds.slice(i,i+20));
+ // A topic signal is a keyword people use; research and profile signals are judged after the fetch, not searched.
+ const queries=[...new Set([audience.discoveryKeyword,...signals.filter(signal=>signal.kind==='topic').map(signal=>signal.topic)].map(value=>value?.trim()).filter(Boolean))].slice(0,3);
+ // At most MAX_SEARCHES title, place and keyword combinations. Each one is searched across every industry chunk, so
+ // a long industry list never pushes a title out of the plan. The credit cap still bounds what the searches cost.
+ const combos=[];
+ for(const title of titles.length?titles:[undefined])for(const place of locations.length?locations:[{}])for(const query of queries.length?queries:[undefined])combos.push({kind:'person',...(title?{title}:{}),...place,...(query?{query}:{})});
+ const searches=[];
+ for(const combo of combos.slice(0,MAX_SEARCHES))for(const ids of industryChunks.length?industryChunks:[undefined]){
+  const input={...combo,...(ids?{industryIds:ids}:{})};
+  if(input.title||input.query||input.geoId||input.location||input.industryIds)searches.push(input);
+ }
+ return searches;
+}
+
+export function parseCredits(value){
+ if(typeof value!=='string'||!/^\d{1,7}(\.\d{1,4})?$/.test(value))throw new Error('Set --max-credits to a number of credits, like 50 or 12.5.');
+ const [whole,fraction='']=value.split('.');
+ return BigInt(whole)*PICO_PER_CREDIT+BigInt(fraction.padEnd(4,'0'))*(PICO_PER_CREDIT/10_000n);
+}
+export const credits=pico=>{const whole=pico/PICO_PER_CREDIT,rest=(pico%PICO_PER_CREDIT)*10_000n/PICO_PER_CREDIT;return rest?`${whole}.${rest.toString().padStart(4,'0').replace(/0+$/,'')}`:`${whole}`;};
+const charged=data=>data?.billing?.status==='charged'&&/^\d+$/.test(data.billing.amount??'')?BigInt(data.billing.amount):0n;
+// A search is final once its outcome is known and its charge has settled.
+const searchSettled=data=>['succeeded','failed','rejected'].includes(data?.status)&&(data.billing?.status==='not_charged'||charged(data)>0n||data.billing?.status==='charged'&&data.billing.amount==='0');
+const personUrl=url=>typeof url==='string'&&/^https:\/\/([a-z]{2,3}\.)?(www\.)?linkedin\.com\/in\//i.test(url);
+
+async function settled(call,workspaceId,data,wait){
+ for(let tries=0;data?.operationId&&!searchSettled(data)&&data.status!=='uncertain'&&tries<30;tries++){await wait(2000);data=(await call('tools_runs_get',{workspaceId,operationId:data.operationId})).data;}
+ return data;
+}
+
+/**
+ * Searches and checks until `count` new fits are found, the searches run out, or the next paid call could pass
+ * `maxCredits`. A search runs only when its published price fits what is left. Each check sends what is left as
+ * `maxCharge`, and the server refuses a check whose worst case (both profile fetches paid) could pass it.
+ */
+export async function findCampaignProspects(call,{workspaceId,campaignId,count,maxCredits},{wait=ms=>new Promise(resolve=>setTimeout(resolve,ms)),progress=()=>{}}={}){
+ const {data:campaign}=await call('campaign_get',{workspaceId,campaignId});
+ const fields=campaign.revision.fields;
+ if(!['Draft','Preparing','Active'].includes(campaign.campaign.state))throw new Error('This campaign is not finding prospects. Pick a Draft, Preparing or Active campaign.');
+ const {data:audience}=await call('audience_get',{workspaceId,audienceId:fields.audienceId,revision:fields.audienceRevision});
+ // #322: the search cannot apply an older audience's industry group, so it would pay to check people in any
+ // industry. Refuse before any paid call; named industries are searched.
+ const company=audience.revision.fields.company;
+ if(company?.industryGroups?.length&&!positive(company.industries).length)throw new Error("This campaign's audience uses an older industry group, which the LinkedIn search cannot apply. Name the industries in the audience instead (audienti audience options --kind industries --q TEXT), then try again.");
+ const searches=planSearches(audience.revision.fields,fields.signals);
+ // #323: rules that will reject people (a named title below the seniority floor) are shown before the first paid call.
+ const warnings=audience.revision.warnings??[];
+ for(const warning of warnings)progress({warning});
+ if(!searches.length)throw new Error("This campaign's audience has no title, location, industry or keyword to search by. Add one, then try again.");
+ const {data:tool}=await call('tools_get',{workspaceId,tool:'profiles.search'});
+ if(!/^\d{1,20}$/.test(tool?.price?.picoUsd??''))throw new Error('The LinkedIn search has no fixed price right now, so the credit cap cannot be kept. Try again later.');
+ const searchPrice=BigInt(tool.price.picoUsd);
+ const report={campaignId,state:campaign.campaign.state,target:count,maxCredits:credits(maxCredits),spentCredits:'0',spent:'0',searches:0,checked:0,fit:0,held:0,notFit:0,alreadyFound:0,failed:0,stoppedBecause:'searches_exhausted',fits:[],heldPeople:[],...(warnings.length?{audienceWarnings:warnings}:{})};
+ let spent=0n;const seen=new Set();
+ const finish=reason=>{report.stoppedBecause=reason;report.spent=spent.toString();report.spentCredits=credits(spent);return report;};
+ // The check may have paid more than it reported; the rest is recovered with the same request ID.
+ const unknown=(url,requestId,error)=>{report.unknownCheck={url,requestId,code:error?.code??'response_unknown'};return finish('outcome_unknown');};
+ for(const input of searches){
+  for(let page=1;page&&page<=MAX_PAGES;){
+   if(report.fit>=count)return finish('count_reached');
+   if(spent+searchPrice>maxCredits)return finish('credit_cap');
+   // Search results are not saved as People; only a person the check fetches joins People.
+   // Nothing else pays until this search has settled: a search still running, uncertain or with a charge not
+   // yet final is retried with the same request ID, and if it never settles the run stops and names it.
+   const search={workspaceId,requestId:randomUUID(),input:{...input,...(page>1?{page}:{}),saveProfiles:false}};
+   let data=null,failure=null,paid=0n;
+   for(let attempt=0;;attempt++){
+    try{data=await settled(call,workspaceId,(await call('tools_profiles_search',search)).data,wait);failure=null;}
+    catch(error){if(!pending(error))throw error;failure=error;}
+    if(!failure&&charged(data)>paid)paid=charged(data);
+    if(!failure&&searchSettled(data))break;
+    if(attempt>=RECOVERY_WAITS.length){
+     spent+=paid;report.searches++;
+     report.unknownSearch={requestId:search.requestId,operationId:data?.operationId??null,code:failure?.code??data?.error?.code??data?.status??'response_unknown'};
+     return finish('outcome_unknown');
+    }
+    await wait(RECOVERY_WAITS[attempt]);
+   }
+   spent+=paid;report.searches++;
+   if(data?.status!=='succeeded'){if(data?.error?.code==='insufficient_credits')return finish('no_credits');break;}
+   const items=(data.result?.items??[]).filter(item=>personUrl(item.url)&&!seen.has(item.url));
+   for(const item of items){
+    seen.add(item.url);
+    if(report.fit>=count)return finish('count_reached');
+    if(spent>=maxCredits)return finish('credit_cap');
+    // Nothing else pays until this check has a definite answer. The same request ID replays the stored
+    // outcome and charge; if no definite answer comes, the run stops and names the check to recover.
+    const args={workspaceId,campaignId,url:item.url,requestId:randomUUID(),maxCharge:(maxCredits-spent).toString()};
+    // Every attempt's reported charge is kept, and the largest is counted once on every way out.
+    let result,failure,paid=0n;
+    for(let attempt=0;;attempt++){
+     try{result=(await call('campaign_prospect_check',args)).data;failure=null;}
+     catch(error){result=null;failure=error;}
+     const reported=reportedCharge(failure?failure.charged:result?.charged);
+     if(reported>paid)paid=reported;
+     if(!failure&&!OUTCOMES.includes(result?.outcome)){failure={code:'invalid_response'};break;}
+     if(!failure||!pending(failure)||attempt>=RECOVERY_WAITS.length)break;
+     await wait(RECOVERY_WAITS[attempt]);
+    }
+    spent+=paid;
+    if(failure){
+     const error=failure;
+     if(pending(error)||error.code==='invalid_response')return unknown(item.url,args.requestId,error);
+     if(error.code==='check_over_budget')return finish('credit_cap');
+     if(error.status===402)return finish('no_credits');
+     if(error.code==='campaign_not_active')return finish('campaign_not_active');
+     if(['tool_unavailable','history_policy_unavailable'].includes(error.code))return finish('tool_unavailable');
+     if(!skippable(error))return unknown(item.url,args.requestId,error);
+     report.failed++;progress({url:item.url,outcome:'failed',code:error.code,spent:credits(spent)});continue;
+    }
+    report.checked++;
+    const who={prospectId:result.prospectId,url:item.url,name:item.name??null,reason:result.assessment?.fit?.reason??null};
+    if(result.outcome==='fit'){report.fit++;report.fits.push({...who,admission:result.assessment?.admission});}
+    else if(result.outcome==='held'){report.held++;report.heldPeople.push({...who,reason:result.assessment?.reason??null});}
+    else if(result.outcome==='not_fit')report.notFit++;
+    else report.alreadyFound++;
+    progress({url:item.url,outcome:result.outcome,spent:credits(spent)});
+   }
+   // Follow the next page even when this one had only people already seen; MAX_PAGES still bounds it.
+   page=data.result?.nextPage>page?data.result.nextPage:0;
+  }
+ }
+ return finish(report.fit>=count?'count_reached':'searches_exhausted');
+}

package/cli/campaign-operations.mjs

@@ -7,20 +7,24 @@ const signal=z.discriminatedUnion('kind',[
  z.object({...signalBase,kind:z.literal('topic'),topic:z.string()}).strict(),
  z.object({...signalBase,kind:z.literal('profile'),url:z.string(),track:z.enum(['audience','activity']).optional(),interactions:z.array(z.enum(['comments','reactions'])).optional()}).strict(),
 ]);
-const fields=z.object({name:z.string(),audienceId:uuid,audienceRevision:z.number().int(),offerId:uuid,offerRevision:z.number().int(),premise:z.string().optional(),approach:z.string().optional(),approachPin:z.object({id:uuid,revision:z.number().int().positive()}).strict().optional(),notes:z.string().optional(),ownerUserId:uuid.nullable().optional(),tags:z.array(z.string()).optional(),signalMatch:z.enum(['any','all']).optional(),signals:z.array(signal).optional(),targets:z.discriminatedUnion('kind',[
+const fields=z.object({name:z.string(),audienceId:uuid,audienceRevision:z.number().int(),offerId:uuid,offerRevision:z.number().int(),premise:z.string().optional(),playbookPin:z.object({id:uuid,revision:z.number().int().positive()}).strict().optional(),notes:z.string().optional(),ownerUserId:uuid.nullable().optional(),tags:z.array(z.string()).optional(),signalMatch:z.enum(['any','all']).optional(),signals:z.array(signal).optional(),method:z.enum(['signals','listen','track-audience','track-engagement','custom']).optional(),findingInstructions:z.string().optional(),targets:z.discriminatedUnion('kind',[
  z.object({kind:z.literal('none'),values:z.array(z.never())}).strict(),
  z.object({kind:z.literal('companies'),values:z.array(z.object({type:z.enum(['domain','linkedin-company']),value:z.string()}).strict())}).strict(),
- z.object({kind:z.literal('people'),values:z.array(z.object({type:z.literal('linkedin-person'),value:z.string()}).strict())}).strict(),
 ]).optional(),channels:z.array(z.enum(['email','linkedin'])).optional(),approvalMode:z.literal('manual').optional(),contentOpsEnabled:z.boolean().optional(),schedule:z.object({startAt:z.string().nullable().optional(),endAt:z.string().nullable().optional(),maxCompanies:z.number().int().nullable().optional()}).strict().optional()}).strict();
 const path=a=>`/workspaces/${a.workspaceId}/campaigns`,detail=a=>path(a)+`/${a.campaignId}`;
 const qs=a=>new URLSearchParams(Object.fromEntries(Object.entries(a).filter(([k,v])=>!['workspaceId','campaignId'].includes(k)&&v!==undefined).map(([k,v])=>[k,String(v)])));
 export const campaignOperations={
- campaign_summary:{schema:z.object({...workspace}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/campaign-summary`,scoped:true,description:'Counts of Campaigns per state, and per Campaign its Audience, offer, approach, goal stage, methods, people, engaged and at-goal counts since start.'},
+ campaign_summary:{schema:z.object({...workspace}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/campaign-summary`,scoped:true,description:'Counts of Campaigns per state, and per Campaign its Audience, offer, playbook, goal stage, methods, people, engaged and at-goal counts since start.'},
  campaign_list:{schema:z.object({...workspace,state:state.optional(),archived:z.boolean().optional(),q:z.string().optional(),limit:z.number().int().optional(),after:uuid.optional()}).strict(),method:'GET',path:a=>path(a)+'?'+qs(a),scoped:true},
  campaign_get:{schema:z.object({...locator,revision:z.number().int().optional()}).strict(),method:'GET',path:a=>detail(a)+'?'+qs(a),scoped:true},
  campaign_events:{schema:z.object({...locator,limit:z.number().int().optional(),after:uuid.optional()}).strict(),method:'GET',path:a=>detail(a)+'/events?'+qs(a),scoped:true},
  campaign_create:{schema:z.object({...workspace,requestId:uuid,fields}).strict(),method:'POST',path,body:a=>({requestId:a.requestId,fields:a.fields}),scoped:true},
  campaign_update:{schema:z.object({...locator,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>detail(a)+'/revisions',body:a=>({expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
- campaign_transition:{schema:z.object({...locator,expectedState:state,operation:z.enum(['prepare','activate','pause','resume','close','archive','restore']),reason:z.string().optional()}).strict(),method:'POST',path:a=>detail(a)+'/transitions',body:a=>({expectedState:a.expectedState,operation:a.operation,...(a.reason===undefined?{}:{reason:a.reason})}),scoped:true,description:'Move a Campaign through its lifecycle. prepare: Draft to Preparing (signal tracking and prospect finding run, no engagement). activate: Draft or Preparing to Active (finding and engagement run). pause: stop automation. resume: back to the paused state. close: Active to Closing (finding stops, engagement continues). archive: stop everything and hide it. restore: Archived to Paused, or Draft for a draft. Agents do not start or activate campaigns; the owner does.'},
+ campaign_transition:{schema:z.object({...locator,expectedState:state,operation:z.enum(['prepare','activate','pause','resume','close','archive','restore']),reason:z.string().optional()}).strict(),method:'POST',path:a=>detail(a)+'/transitions',body:a=>({expectedState:a.expectedState,operation:a.operation,...(a.reason===undefined?{}:{reason:a.reason})}),scoped:true,description:'Move a Campaign through its lifecycle. prepare: Draft to Preparing (signal tracking and prospect finding run, no engagement). activate: Draft or Preparing to Active (finding and engagement run). pause: stop automation. resume: back to the paused state. close: Active to Closing (finding stops, engagement continues). archive: stop everything and hide it. restore: Archived to Paused, or Draft for a draft. Agents do not start or activate campaigns; the user does. A campaign that cannot run is refused with campaign_not_ready and its missing items in blockers.'},
+ campaign_pace_get:{schema:z.object({...locator}).strict(),method:'GET',path:a=>detail(a)+'/pace',scoped:true,description:'Read a Campaign pace: new people a day. Derived is 25 a day per confirmed LinkedIn account, each capped by its reported connection-request limit; an email-only Campaign uses its own number, 50 by default, within mailbox limits. The reply names the LinkedIn accounts, the weekly figure and the expected daily credits for hosted lookups.'},
+ campaign_pace_set:{schema:z.object({...locator,perDay:z.union([z.number().int().min(1).max(1000),z.literal('derived')]).optional(),maxCredits:z.number().int().min(1).max(100000).nullable().optional()}).strict().refine(a=>a.perDay!==undefined||a.maxCredits!==undefined,{message:'Send perDay, maxCredits or both.'}),method:'POST',path:a=>detail(a)+'/pace',body:a=>({...(a.perDay===undefined?{}:{perDay:a.perDay}),...(a.maxCredits===undefined?{}:{maxCredits:a.maxCredits})}),scoped:true,description:'Save a Campaign pace. Pass the number the user gave, or "derived" to follow the confirmed sending accounts. An owner number stays until changed and is still capped by LinkedIn account and mailbox limits. maxCredits saves the credits a day the user approved for finding (null removes it); each day\'s find task carries it.'},
+ campaign_targets_get:{schema:z.object({...locator,limit:z.number().int().min(1).max(500).optional(),after:z.string().regex(/^\d{1,7}$/).optional()}).strict(),method:'GET',path:a=>detail(a)+'/targets?'+qs(a),scoped:true,description:'Read a Campaign\'s target companies in pages of up to 500: domains and LinkedIn company URLs. Only people whose current company is one of them can join.'},
+ campaign_targets_change:{schema:z.object({...locator,expectedRevision:z.number().int().positive(),add:z.array(z.string()).optional(),remove:z.array(z.string()).optional(),set:z.array(z.string()).optional()}).strict().refine(a=>(a.set===undefined)!==(a.add===undefined&&a.remove===undefined),{message:'Send set, or add and or remove.'}),method:'POST',path:a=>detail(a)+'/targets',body:a=>({expectedRevision:a.expectedRevision,...Object.fromEntries(['add','remove','set'].filter(k=>a[k]!==undefined).map(k=>[k,a[k]]))}),scoped:true,description:'Change a Campaign\'s target companies: add or remove domains (acme.com) and LinkedIn company URLs, or replace them all with set. Saves a new Campaign revision; an empty set removes the targets.'},
+ campaign_prospect_check:{schema:z.object({...locator,url:z.string().max(1024),requestId:uuid,maxCharge:z.string().regex(/^\d{1,20}$/).optional()}).strict(),method:'POST',path:a=>detail(a)+'/prospect-checks',body:a=>({url:a.url,requestId:a.requestId,...(a.maxCharge!==undefined?{maxCharge:a.maxCharge}:{})}),scoped:true,recoverable:true,timeoutMs:90000,description:'Check one LinkedIn person URL for a Campaign and record the result. Fetches the person and current company (saved profiles are reused free; otherwise each fetch spends hosted credits), runs the pinned Audience rules and records a qualification with the profiles as evidence. outcome fit: admitted, or shortlisted while the Campaign is a Draft. held: an agent must judge a smart rule, a signal or an undecided rule. not_fit: a rule failed. already_found: already in or shortlisted for this Campaign; nothing written. charged and balance are pico USD (1 credit = 10,000,000,000). Generate requestId once and reuse it after an interruption so a retry never pays twice.'},
  campaign_successor:{schema:z.object({...locator,requestId:uuid,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>detail(a)+'/successors',body:a=>({requestId:a.requestId,expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
 };

package/cli/campaigns.mjs

@@ -3,11 +3,44 @@ import {readJsonFile} from './json-file.mjs';
 export async function campaignCli(args){
  const position=[],flags={};for(let i=0;i<args.length;i++){
   if(!args[i].startsWith('--')){position.push(args[i]);continue}
-  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','state','operation','expected-state','reason'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete campaign option.');
+  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','state','operation','expected-state','reason','per-day','count','max-credits','url','add','remove','set'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete campaign option.');
   flags[key]=args[++i];
  }
- const command=position[1],name={list:'campaign_list',show:'campaign_get',create:'campaign_create',update:'campaign_update',transition:'campaign_transition',successor:'campaign_successor',events:'campaign_events'}[command];
- if(!name||position.length!==(['list','create'].includes(command)?2:3))throw new Error('Use campaign list|show ID|create|update ID|transition ID|successor ID|events ID.');
+ const command=position[1];
+ if(command==='find'){
+  if(position.length!==3)throw new Error('Use campaign find ID --count N --max-credits C.');
+  if(!/^\d{1,3}$/.test(flags.count??'')||Number(flags.count)<1||Number(flags.count)>500)throw new Error('Set --count to how many fits to find, from 1 to 500.');
+  if(flags['max-credits']===undefined)throw new Error('Set --max-credits to the most credits this run may spend.');
+  const {findCampaignProspects,parseCredits}=await import('./campaign-find.mjs');
+  const config=configuration(flags.profile);
+  const report=await findCampaignProspects((operation,input)=>callWorkspace(operation,input,config),{workspaceId:flags.workspace,campaignId:position[2],count:Number(flags.count),maxCredits:parseCredits(flags['max-credits'])},{progress:step=>console.error(JSON.stringify(step))});
+  console.log(JSON.stringify({data:report}));return;
+ }
+ if(command==='check'){
+  if(position.length!==3||!flags.url)throw new Error('Use campaign check ID --url LINKEDIN_URL [--request-id UUID].');
+  const {randomUUID}=await import('node:crypto');
+  console.log(JSON.stringify(await callWorkspace('campaign_prospect_check',{workspaceId:flags.workspace,campaignId:position[2],url:flags.url,requestId:flags['request-id']??randomUUID()},configuration(flags.profile))));return;
+ }
+ if(command==='targets'){
+  if(position.length!==3)throw new Error('Use campaign targets ID [--add a.com,b.com] [--remove a.com] [--set FILE|-] [--expected-revision N].');
+  const config=configuration(flags.profile),input={workspaceId:flags.workspace,campaignId:position[2]};
+  const change=['add','remove','set'].some(k=>flags[k]!==undefined);
+  if(!change){if(flags.limit!==undefined)input.limit=Number(flags.limit);if(flags.after)input.after=flags.after;console.log(JSON.stringify(await callWorkspace('campaign_targets_get',input,config)));return;}
+  if(flags.set!==undefined&&(flags.add!==undefined||flags.remove!==undefined))throw new Error('Use --set on its own, or --add and --remove.');
+  const split=v=>v.split(',').map(x=>x.trim()).filter(Boolean);
+  if(flags.add!==undefined)input.add=split(flags.add);
+  if(flags.remove!==undefined)input.remove=split(flags.remove);
+  if(flags.set!==undefined){const {readFileSync}=await import('node:fs');input.set=readFileSync(flags.set==='-'?0:flags.set,'utf8').split(/\r?\n/).map(x=>x.trim()).filter(x=>x&&!x.startsWith('#'));}
+  input.expectedRevision=flags['expected-revision']!==undefined?Number(flags['expected-revision']):(await callWorkspace('campaign_targets_get',{workspaceId:flags.workspace,campaignId:position[2],limit:1},config)).data.revision;
+  console.log(JSON.stringify(await callWorkspace('campaign_targets_change',input,config)));return;
+ }
+ if(command==='summary'){
+  if(position.length!==2)throw new Error('Use campaign summary [--workspace ID].');
+  console.log(JSON.stringify(await callWorkspace('campaign_summary',{workspaceId:flags.workspace},configuration(flags.profile))));return;
+ }
+ const name={list:'campaign_list',show:'campaign_get',create:'campaign_create',update:'campaign_update',transition:'campaign_transition',successor:'campaign_successor',events:'campaign_events',pace:flags['per-day']===undefined&&flags['max-credits']===undefined?'campaign_pace_get':'campaign_pace_set'}[command];
+ if(!name||position.length!==(['list','create'].includes(command)?2:3))throw new Error('Use campaign list|summary|show ID|create|update ID|transition ID|successor ID|events ID|pace ID [--per-day N|derived] [--max-credits C|none]|find ID --count N --max-credits C|check ID --url URL|targets ID [--add|--remove|--set].');
+ if(flags['per-day']!==undefined&&command!=='pace')throw new Error('Set the pace with campaign pace ID --per-day N|derived, after the campaign is saved.');
  const input={workspaceId:flags.workspace};
  if(position[2])input.campaignId=position[2];
  if(['list','events'].includes(command)){
@@ -22,5 +55,7 @@ export async function campaignCli(args){
  if(['create','successor'].includes(command))input.requestId=flags['request-id'];
  if(['update','successor'].includes(command))input.expectedRevision=Number(flags['expected-revision']);
  if(command==='transition'){input.operation=flags.operation;input.expectedState=flags['expected-state'];if(flags.reason!==undefined)input.reason=flags.reason;}
+ if(command==='pace'&&flags['per-day']!==undefined){const v=flags['per-day'];if(v!=='derived'&&!/^\d+$/.test(v))throw new Error('Pace must be a whole number of people a day, or derived.');input.perDay=v==='derived'?v:Number(v);}
+ if(command==='pace'&&flags['max-credits']!==undefined){const v=flags['max-credits'];if(v!=='none'&&!/^\d+$/.test(v))throw new Error('The credit cap must be a whole number of credits a day, or none.');input.maxCredits=v==='none'?null:Number(v);}
  console.log(JSON.stringify(await callWorkspace(name,input,configuration(flags.profile))));
 }

package/cli/cohort-operations.mjs

@@ -9,7 +9,7 @@ const path = name => a => {
 export const cohortOperations = {
  workspace_analytics_cohorts: {
   schema: z.object({ ...filters, stage: z.string().min(1).max(100).optional(), cohorts: z.number().int().min(1).max(52).optional(), horizon: z.number().int().min(1).max(26).optional() }).strict(), method: 'GET', path: path('cohorts'), scoped: true,
-  description: `Weekly entry cohorts: people grouped by the UTC week (Monday start) they were admitted to a campaign, and for each week since admission the share that reached a stage. stage is "goal" (default, each approach's goal) or a stage key from the stages list in the response. cohorts is the number of weeks (default 12, at most 52); horizon is the number of weeks since entry shown after week 0 (default 8, at most 26). A cell is empty (null) until every member of the cohort has had that long. ${FILTER_TEXT} Same figures as Analytics > Cohorts.`,
+  description: `Weekly entry cohorts: people grouped by the UTC week (Monday start) they were admitted to a campaign, and for each week since admission the share that reached a stage. stage is "goal" (default, each playbook's goal) or a stage key from the stages list in the response. cohorts is the number of weeks (default 12, at most 52); horizon is the number of weeks since entry shown after week 0 (default 8, at most 26). A cell is empty (null) until every member of the cohort has had that long. ${FILTER_TEXT} Same figures as Analytics > Cohorts.`,
  },
  workspace_stage_aging: {
   schema: z.object({ ...filters, thresholdDays: z.number().int().min(1).max(365).optional() }).strict(), method: 'GET', path: path('stage-aging'), scoped: true,

package/cli/content.mjs

@@ -10,6 +10,7 @@ const help = `Usage:
 
 Topic input: {"name":"Topic name","slug":"optional-slug","description":"optional"}.
 These commands read saved records or create a topic; they do not call a paid provider.
+Each post names the tool run that last saved it in savedByOperationId; read the run with audienti tools runs get OPERATION_ID.
 Retrieve fresh data with audienti tools posts.fetch|posts.search|posts.comments|posts.reactions|profiles.posts.
 Use audienti tools describe NAME --json for the exact contract.
 All commands accept --profile PATH, --workspace UUID and --json.`;
@@ -21,6 +22,7 @@ export async function contentCli(argv) {
   let args = values.workspace ? { workspaceId: values.workspace } : {};
   if (verb === 'list' && positionals.length === 1) args = { ...args, cursor: values.cursor, ...(kind === 'posts' ? { topicId: values['topic-id'] } : {}) };
   else if (verb === 'get' && positionals.length === 2) args.id = id;
+  else if (verb === 'get') throw new Error(`Name the ${kind === 'posts' ? 'post' : 'topic'} to read: audienti ${kind} get ID.`);
   else if (kind === 'topics' && verb === 'create' && positionals.length === 1) {
     if (!values.input || !values['request-id']) throw new Error('Topic create requires --input FILE and --request-id UUID.');
     args = { ...readJsonFile(values.input, 32768, 'Topic input'), ...args, requestId: values['request-id'] };