@audienti/cli 0.2.0-exora.6 → 0.2.0-exora.8

package/cli/rooms.mjs

@@ -6,9 +6,9 @@ import {setTimeout as sleep} from 'node:timers/promises';
 import {callWorkspace,configuration} from './workspaces.mjs';
 import {readJsonFile} from './json-file.mjs';
 // Agent rooms client. Delivery is polled by the agent; nothing here opens a port.
-const valued=['profile','workspace','sort','since','about','limit','to','room','thread','body','body-file','file','answer-by','expires-at','request-id','with','slug','title','purpose','members','after','q','handle','exec','interval','timeout'];
-const switches=['retired','stop','once','json','unable','clear','brief'];
-export const roomsUsage='Rooms: audienti rooms directory [--sort load] | inbox [--since ITEM] [--about TYPE:ID] [--limit N] [--brief] | ack ITEM... | send (--to HANDLE|--room ROOM) [--thread ID] (--body TEXT|--body-file PATH|-) [--about TYPE:ID,...] [--answer-by ISO] [--expires-at ISO] [--unable] [--request-id UUID] | note (--body TEXT|--body-file PATH|-|--clear) | thread ID [--after N] | threads --about TYPE:ID | create (--with HANDLE | --slug S --title T [--purpose P] [--members a,b]) | list [--retired] [--q TEXT] | read ROOM [--q TEXT] | retire ROOM | restore ROOM | redact MESSAGE | resume THREAD | pause on|off | profile AGENT_ID [--handle H] [--about TEXT] | hook [--stop] | watch --exec CMD [--interval SECONDS] [--once] | wait --thread ID [--timeout SECONDS]';
+const valued=['profile','workspace','sort','since','about','limit','to','room','thread','body','body-file','file','answer-by','expires-at','request-id','with','slug','title','purpose','members','after','q','handle','exec','interval','timeout','question','options','deciders','rule','deadline','default','if-no-answer','supersedes','summary','due','for','status','note','goal','state','next-action','open-items','risks','action','stance','option','reason','question-id','kind','name'];
+const switches=['retired','stop','once','json','unable','clear','brief','any-one'];
+export const roomsUsage='Rooms: audienti rooms directory [--sort load] | inbox [--since ITEM] [--about TYPE:ID] [--limit N] [--brief] | ack ITEM... | send (--to HANDLE|--room ROOM) [--thread ID] (--body TEXT|--body-file PATH|-) [--about TYPE:ID,...] [--answer-by ISO [--if-no-answer TEXT] [--any-one]] [--expires-at ISO] [--unable] [--request-id UUID] | note (--body TEXT|--body-file PATH|-|--clear) | thread ID [--after N] | threads --about TYPE:ID | create (--with HANDLE | --slug S --title T [--purpose P] [--members a,b]) | list [--retired] [--q TEXT] | read ROOM [--q TEXT] | retire ROOM | restore ROOM | redact MESSAGE | resume THREAD | pause on|off | profile AGENT_ID [--handle H] [--about TEXT] | request-decision --question T --options A|B[|C] --deciders h1,h2 --rule one|any|all|majority --deadline ISO [--default OPTION] [--if-no-answer T] [--supersedes ID] [--room R|--thread ID] | respond DECISION --stance support|object|abstain [--option O] --reason T | withdraw DECISION | commit --summary T [--due ISO] [--for HANDLE] [--room R|--thread ID] | commit-update COMMITMENT --status done|released [--note T] | handoff COMMITMENT (--to HANDLE|--any-one) --goal T --state T --next-action T [--open-items a|b] [--risks a|b] [--answer-by ISO] | handoff-reply COMMITMENT --action accept|decline [--note T] | claim MESSAGE | ask-owner --question-id ID [--room R|--thread ID] [--answer-by ISO] [--if-no-answer T] | owner-create (--kind direct --members a,b[,c] | --kind group --name N [--purpose P] --members a,b) | owner-post ROOM [--thread ID] --body TEXT | member-add ROOM AGENT_ID | hook [--stop] | watch --exec CMD [--interval SECONDS] [--once] | wait --thread ID [--timeout SECONDS]';
 export const WATCH_MIN_INTERVAL=60,WAIT_MAX_TIMEOUT=900,WAIT_POLL=30,HOOK_CACHE=60;
 function parse(args){
  const position=[],flags={};
@@ -29,6 +29,10 @@ const references=value=>value===undefined?undefined:value.split(',').map(entry=>
  const type=entry.slice(0,at),rest=entry.slice(at+1);
  return type==='url'?{type,url:rest,title:rest}:{type,id:rest};
 });
+const list=(value,separator)=>value===undefined?undefined:value.split(separator).map(item=>item.trim()).filter(Boolean);
+const pick=(flags,pairs)=>Object.fromEntries(pairs.filter(([flag])=>flags[flag]!==undefined).map(([flag,key])=>[key,flags[flag]]));
+const placeOf=flags=>({...(flags.room?{room:flags.room}:{}),...(flags.thread?{threadId:flags.thread}:{})});
+const requestId=flags=>flags['request-id']??randomUUID();
 function messageBody(flags,rest){
  const sources=[flags.body!==undefined,flags['body-file']!==undefined,rest[0]==='-'].filter(Boolean).length;
  if(sources!==1)throw new Error('Supply exactly one of --body TEXT, --body-file PATH or - for standard input.');
@@ -111,6 +115,8 @@ export async function roomsCli(args){
    for(const [flag,key] of [['to','to'],['room','room'],['thread','threadId'],['answer-by','answerBy'],['expires-at','expiresAt']])if(flags[flag]!==undefined)input[key]=flags[flag];
    if(flags.about)input.about=references(flags.about);
    if(flags.unable)input.unable=true;
+   if(flags['if-no-answer']!==undefined)input.ifNoAnswer=flags['if-no-answer'];
+   if(flags['any-one'])input.anyOne=true;
    return print(await call('rooms_send',input,flags));
   }
   case 'note':{
@@ -127,6 +133,25 @@ export async function roomsCli(args){
   case 'resume':need(1,'resume THREAD');return print(await call('rooms_resume',{threadId:rest[0]},flags));
   case 'pause':if(rest.length!==1||!['on','off'].includes(rest[0]))throw new Error('Use audienti rooms pause on|off.');return print(await call('rooms_pause',{paused:rest[0]==='on'},flags));
   case 'profile':need(1,'profile AGENT_ID [--handle H] [--about TEXT]');return print(await call('rooms_profile_set',{agentId:rest[0],...(flags.handle?{handle:flags.handle}:{}),...(flags.about!==undefined?{about:flags.about}:{})},flags));
+  case 'request-decision':{
+   need(0,'request-decision --question T --options A|B --deciders h1,h2 --rule one --deadline ISO');
+   return print(await call('rooms_decision_request',{...placeOf(flags),question:flags.question,options:list(flags.options,'|'),deciders:list(flags.deciders,','),rule:flags.rule,deadline:flags.deadline,...pick(flags,[['default','defaultOption'],['if-no-answer','ifNoAnswer'],['supersedes','supersedes']]),...(flags.about?{about:references(flags.about)}:{}),requestId:requestId(flags)},flags));
+  }
+  case 'respond':need(1,'respond DECISION --stance support|object|abstain --reason T');return print(await call('rooms_decision_respond',{decisionId:rest[0],stance:flags.stance,reason:flags.reason,...pick(flags,[['option','option']]),requestId:requestId(flags)},flags));
+  case 'withdraw':need(1,'withdraw DECISION');return print(await call('rooms_decision_withdraw',{decisionId:rest[0]},flags));
+  case 'commit':need(0,'commit --summary T');return print(await call('rooms_commit',{...placeOf(flags),summary:flags.summary,...pick(flags,[['due','dueAt'],['for','for']]),...(flags.about?{about:references(flags.about)}:{}),requestId:requestId(flags)},flags));
+  case 'commit-update':need(1,'commit-update COMMITMENT --status done|released');return print(await call('rooms_commit_update',{commitmentId:rest[0],status:flags.status,...pick(flags,[['note','note']]),requestId:requestId(flags)},flags));
+  case 'handoff':{
+   need(1,'handoff COMMITMENT (--to HANDLE|--any-one) --goal T --state T --next-action T');
+   const note={goal:flags.goal,state:flags.state,nextAction:flags['next-action'],...(flags['open-items']?{openItems:list(flags['open-items'],'|')}:{}),...(flags.risks?{risks:list(flags.risks,'|')}:{})};
+   return print(await call('rooms_handoff',{commitmentId:rest[0],...(flags.to?{to:flags.to}:{}),...(flags['any-one']?{anyOne:true}:{}),note,...pick(flags,[['answer-by','answerBy']]),...(flags.about?{about:references(flags.about)}:{}),requestId:requestId(flags)},flags));
+  }
+  case 'handoff-reply':need(1,'handoff-reply COMMITMENT --action accept|decline');return print(await call('rooms_handoff_reply',{commitmentId:rest[0],action:flags.action,...pick(flags,[['note','note']]),requestId:requestId(flags)},flags));
+  case 'claim':need(1,'claim MESSAGE');return print(await call('rooms_claim',{messageId:rest[0],requestId:requestId(flags)},flags));
+  case 'ask-owner':need(0,'ask-owner --question-id ID');return print(await call('rooms_ask_owner',{...placeOf(flags),questionId:flags['question-id'],...pick(flags,[['answer-by','answerBy'],['if-no-answer','ifNoAnswer']]),requestId:requestId(flags)},flags));
+  case 'owner-create':need(0,'owner-create --kind direct|group --members a,b');return print(await call('rooms_owner_create',{kind:flags.kind,members:list(flags.members,','),...pick(flags,[['name','name'],['purpose','purpose']])},flags));
+  case 'owner-post':need(1,'owner-post ROOM --body TEXT');return print(await call('rooms_owner_post',{room:rest[0],...(flags.thread?{threadId:flags.thread}:{}),body:flags.body,requestId:requestId(flags)},flags));
+  case 'member-add':need(2,'member-add ROOM AGENT_ID');return print(await call('rooms_member_add',{room:rest[0],agentId:rest[1]},flags));
   case 'hook':need(0,'hook [--stop]');return hook(flags);
   case 'watch':need(0,'watch --exec CMD');return watch(flags);
   case 'wait':need(0,'wait --thread ID');return wait(flags);

package/cli/sender-account-operations.mjs

@@ -5,7 +5,7 @@ const base={requestId:uuid,reason:text(1,2000).describe('Trimmed NFC; no control
 const alias={provider:z.enum(['email','linkedin']),accountRef:text(1,200).regex(/^[A-Za-z0-9@._:+\/-]+$/),expectedAliasVersion:version};
 const identity=z.object({namespace:text(1,64).describe('Discovery namespace: trimmed and lowercased.'),accountId:text(1,256).describe('Trimmed printable ASCII provider identity; case-sensitive assertion, not verification.')}).strict();
 const actionType=z.enum(['email.send','linkedin.send']);
-const capability=z.enum(['profile.read','profile.connection.request','profile.follow','profile.message.send','profile.inmail.send','profile.inbox.read','people.search']).describe('Account action. Audienti gates profile.connection.request (invite and withdraw) and profile.message.send at send time; the agent follows the user\'s mode for the others. Email accounts have profile.message.send and inbox.read.');
+const capability=z.enum(['profile.read','profile.connection.request','profile.connection.withdraw','profile.follow','profile.message.send','profile.inmail.send','profile.inbox.read','people.search','post.comment','post.react','post.publish','profile.visit','profile.views.read']).describe('Account action. Audienti gates profile.connection.request, profile.connection.withdraw and profile.message.send at send time; the agent follows the user\'s mode for the others. Email accounts have profile.message.send and inbox.read.');
 const useIn=z.object({allWorkspaces:z.boolean(),workspaceIds:z.array(uuid).max(200)}).strict().describe('Where the account is used: all of the user\'s workspaces, or only the listed ones. Left out, all of them.');
 const pageLimit=z.number().int().min(1).max(100).optional();
 const query=a=>{const q=new URLSearchParams(Object.entries(a).map(([k,v])=>[k,String(v)]));return q.size?'?'+q:'';};

package/cli/sender-accounts.mjs

@@ -6,12 +6,17 @@ export async function callSenderAccounts(name,args,profilePath){
  return callOwnerAccountOperation(senderAccountOperations[name],args,profilePath,'sender account');
 }
 export async function senderAccountsCli(args){
- const flags={},positions=[];const known=['profile','file','cursor','limit','aliases-cursor','aliases-limit','history-cursor','history-limit','action-type','capability','provider','account-ref'];
+ const flags={},positions=[];const known=['profile','file','cursor','limit','aliases-cursor','aliases-limit','history-cursor','history-limit','action-type','capability','provider','account-ref','workspace','plan'];
  for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')continue;if(!arg.startsWith('--')){positions.push(arg);continue;}const key=arg.slice(2);if(!known.includes(key)||Object.hasOwn(flags,key)||!args[i+1]||args[i+1].startsWith('--'))throw Error('Unknown, repeated or incomplete sender option.');flags[key]=args[++i];}
  if(positions[0]==='sender'&&positions[1]==='managed'){
+  if(positions[2]==='plan'){
+   const plans=['free','premium_career','premium_business','premium_all_in_one','sales_navigator_core','sales_navigator_advanced','recruiter_lite'],usage=`Use sender managed plan MANAGED_ACCOUNT_ID --plan ${plans.join('|')}|none [--workspace ID] [--profile PATH]  (the user only; none clears it).`;
+   if(positions.length!==4||Object.keys(flags).some(key=>!['profile','plan','workspace'].includes(key))||!flags.plan||![...plans,'none'].includes(flags.plan))throw Error(flags.plan&&![...plans,'none'].includes(flags.plan)?`${flags.plan} is not a plan. ${usage}`:usage);
+   console.log(JSON.stringify(await callWorkspace('workspace_managed_account_plan_set',{workspaceId:flags.workspace,managedAccountId:positions[3],plan:flags.plan==='none'?null:flags.plan},configuration(flags.profile??process.env.AUDIENTI_PROFILE))));return;
+  }
   const names={list:'workspace_managed_accounts_list',connect:'workspace_managed_account_connect'};
-  if(!names[positions[2]]||positions.length!==3||Object.keys(flags).some(key=>key!=='profile'))throw Error('Use sender managed list|connect [--profile PATH].');
-  console.log(JSON.stringify(await callWorkspace(names[positions[2]],{},configuration(flags.profile??process.env.AUDIENTI_PROFILE))));return;
+  if(!names[positions[2]]||positions.length!==3||Object.keys(flags).some(key=>!['profile','workspace'].includes(key)))throw Error('Use sender managed list|connect|plan [--workspace ID] [--profile PATH].');
+  console.log(JSON.stringify(await callWorkspace(names[positions[2]],{workspaceId:flags.workspace},configuration(flags.profile??process.env.AUDIENTI_PROFILE))));return;
  }
  if(positions[0]!=='sender'||positions[1]!=='accounts')throw Error('Use sender accounts list|get|alias|register|bind|unbind|state|automation|modes.');
  const automation=positions[2]==='automation',modes=positions[2]==='modes',activity=positions[2]==='activity',nested=automation||modes||activity,command=nested?`${positions[2]}-${positions[3]}`:positions[2];

package/cli/work-execution-operations.mjs

@@ -31,6 +31,7 @@ export const workspaceExecutionOperations={
 // LinkedIn accounts connected through Audienti. Only the user connects one; agents list them and send through work send.
 export const managedAccountOperations={
  workspace_managed_accounts_list:{schema:z.object({workspaceId:uuid.optional()}).strict(),scoped:true,method:'GET',path:a=>`/workspaces/${a.workspaceId}/managed-accounts`,description:'List the LinkedIn accounts connected through Audienti in this workspace, with their sending account IDs and status.'},
+ workspace_managed_account_plan_set:{schema:z.object({workspaceId:uuid.optional(),managedAccountId:uuid,plan:z.enum(['free','premium_career','premium_business','premium_all_in_one','sales_navigator_core','sales_navigator_advanced','recruiter_lite']).nullable()}).strict(),scoped:true,method:'PUT',path:a=>`/workspaces/${a.workspaceId}/managed-accounts/${a.managedAccountId}/plan`,body:a=>({plan:a.plan}),description:'The user only, not agents. States the LinkedIn plan of a managed account, which sets how long a connection note may be. Pass plan null to clear it; the safer figures then apply. Returns the account.'},
  workspace_managed_account_connect:{schema:z.object({workspaceId:uuid.optional()}).strict(),scoped:true,method:'POST',path:a=>`/workspaces/${a.workspaceId}/managed-accounts/connect`,body:()=>({}),description:'The user only, not agents. Returns a sign-in link, valid 15 minutes, where the user connects a LinkedIn account through Audienti.'},
 };
 export const narrowExecutionOperations={

package/cli/work-operations.mjs

@@ -7,7 +7,7 @@ const accountRef = z.string().min(1).max(200).regex(/^[A-Za-z0-9@._:+\/-]+$/);
 const evidence = z.array(uuid).max(100);
 const commonAction = {clientActionId: clientId, capability: z.enum(['profile.connection.request','profile.message.send']).optional().describe('The owner action: profile.connection.request or profile.message.send on linkedin.send, profile.message.send on email.send. The sending account\'s mode for it decides whether approval is needed or the action is not allowed. Without it the old per-channel automation switch applies, unless a mode restricts it.'), reason: z.string().min(1), evidenceIds: evidence, replyToEvidenceId: uuid.optional(), playbookStepKey: uuid.optional().describe("The playbook step this action runs; a succeeded result starts that step's wait. Saving the plan checks it: the key must name a step of the playbook pinned to the person's active participation in the plan's Campaign, and the step's channel must match the action type (email.send only with an Email step, linkedin.send only with a LinkedIn step); otherwise the save is refused with invalid_fields.")};
 const email = z.object({...commonAction, type:z.literal('email.send'), content:z.object({subject:z.string(),body:z.string()}).strict(),recipient:z.object({prospectId:uuid,email:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('email'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
-const linkedin = z.object({...commonAction,type:z.literal('linkedin.send'),content:z.object({body:z.string()}).strict(),recipient:z.object({prospectId:uuid,profileUrl:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('linkedin'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
+const linkedin = z.object({...commonAction,type:z.literal('linkedin.send'),content:z.object({body:z.string(),attachments:z.array(z.object({id:uuid}).strict()).min(1).max(1).optional()}).strict(),recipient:z.object({prospectId:uuid,profileUrl:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('linkedin'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
 const cadence = z.object({notBefore:z.string().datetime().optional(),clientActionId:clientId,afterClientActionId:clientId.nullable(),trigger:z.literal('reported_success').nullable(),at:z.string().nullable(),waitSeconds:z.number().int().min(0).max(7776000).nullable(),condition:z.literal('no_pending_reply').nullable()}).strict();
 const located = {...workspace,planId:uuid,clientActionId:clientId};
 const mutation = {...located,expectedRevision:z.number().int().positive(),requestId:uuid};

package/cli/workspaces.mjs

@@ -4,6 +4,7 @@ import {roomsOperations} from './rooms-operations.mjs';
 import {queueOperations} from './queue-operations.mjs';
 import {kvOperations} from './kv-operations.mjs';
 import {outcomeOperations} from './outcome-operations.mjs';
+import {attachmentOperations} from './attachment-operations.mjs';
 import {questionOperations} from './question-operations.mjs';
 import {searchOperations} from './search-operations.mjs';
 import {fileOperations,uploadFileContent} from './file-operations.mjs';
@@ -43,6 +44,7 @@ export const operations = {
  ...queueOperations,
  ...kvOperations,
  ...outcomeOperations,
+ ...attachmentOperations,
  ...questionOperations,
  ...fileOperations,
  ...playbookOperations,
@@ -116,7 +118,11 @@ export function writeProfile(path, profile) {
  const target=profilePath(path); const temporary=`${target}.${process.pid}.tmp`;
  writeFileSync(temporary,JSON.stringify(profile)+'\n',{mode:0o600,flag:'wx'}); renameSync(temporary,target);
 }
+/** The profile path: --profile wins, then AUDIENTI_PROFILE (the variable the MCP server reads), else none (#448). */
+export const profileFrom = flag => flag ?? (process.env.AUDIENTI_PROFILE || undefined);
+export const profileHint = 'Pass --profile PATH, or set AUDIENTI_PROFILE to the profile file.';
 export function configuration(path, scope='workspace:access') {
+ path=profileFrom(path);
  const profile=readProfile(path);
  const agentProfile = Boolean(profile.agent || profile.pendingAgent || profile.connectionSecret);
  return { url:agentProfile ? profile.url : process.env.AUDIENTI_API_URL ?? profile.url, token:agentProfile ? (scope === 'workspace:access' ? profile.tokens?.['workspace:read'] : undefined) : process.env.AUDIENTI_API_TOKEN ?? (scope === 'workspace:access' ? profile.tokens?.['workspace:read'] ?? profile.tokens?.[scope] : profile.tokens?.[scope]), workspaceId:profile.workspaceId, profile };
@@ -127,9 +133,13 @@ export function validateUrl(value) {
  if(url.protocol!=='https:' && !(url.protocol==='http:' && ['localhost','127.0.0.1','[::1]'].includes(url.hostname))) throw new Error('Use HTTPS for remote API hosts.');
  return url;
 }
+// A refused request that never left this machine. It prints like an API error, so a caller reads one format (#451).
+export class InvalidArguments extends Error {
+ toJSON() { return {code:'invalid_arguments',message:this.message}; }
+}
 export class WorkspaceRequestError extends Error {
  constructor(status, code, message, retryAt, blockers, requestTraceId) { super(message); this.status = status; this.code = code; this.retryAt = retryAt; this.blockers = blockers; this.requestTraceId = requestTraceId; }
- toJSON() { return { ...(this.requestId ? {requestId:this.requestId,recovery:this.recovery} : {}), ...(this.requestTraceId ? {requestTraceId:this.requestTraceId} : {}), code:this.code, status:this.status, message:this.message, ...(this.retryAt ? {retryAt:this.retryAt} : {}), ...(this.blockers ? {blockers:this.blockers} : {}), ...(this.charged ? {charged:this.charged} : {}) }; }
+ toJSON() { return { ...(this.requestId ? {requestId:this.requestId,recovery:this.recovery} : {}), ...(this.requestTraceId ? {requestTraceId:this.requestTraceId} : {}), code:this.code, status:this.status, message:this.message, ...(this.currentRevision!==undefined ? {currentRevision:this.currentRevision} : {}), ...(this.campaigns ? {campaigns:this.campaigns,campaignCount:this.campaignCount} : {}), ...(this.retryAt ? {retryAt:this.retryAt} : {}), ...(this.blockers ? {blockers:this.blockers} : {}), ...(this.errors ? {errors:this.errors} : {}), ...(this.charged ? {charged:this.charged} : {}) }; }
 }
 export class HostedResponseUnknown extends Error {
  constructor(requestId, reason, requestTraceId) { super('The server response is unknown. Paid work may have started. Retry using the same requestId and principal; never generate a new ID to recover this call.'); this.requestId=requestId; this.reason=reason; this.requestTraceId=requestTraceId; }
@@ -137,12 +147,12 @@ export class HostedResponseUnknown extends Error {
 }
 export async function callWorkspace(name, args, config) {
  const operation=operations[name]; if(!operation) throw new Error('Unknown workspace operation.');
- const parsed=operation.schema.safeParse(args);if(!parsed.success) throw new Error(`Invalid workspace arguments. Check IDs and required fields: ${parsed.error.issues.slice(0,5).map(i=>`${i.path.join('.')||'input'}: ${i.message}`).join('; ')}.`);
+ const parsed=operation.schema.safeParse(args);if(!parsed.success) throw new InvalidArguments(`Invalid workspace arguments. Check IDs and required fields: ${parsed.error.issues.slice(0,5).map(i=>`${i.path.join('.')||'input'}: ${i.message}`).join('; ')}.`);
  const input={...parsed.data};
  if(operation.localUpload)return uploadFileContent(input,(operationName,fields)=>callWorkspace(operationName,fields,config));
  // #333: an agent's own queue covers all its workspaces; a user's reads the selected workspace, as before.
- if(operation.scoped || (operation.agentWide && !/^agt_/.test(config.token ?? ''))) { input.workspaceId ??= config.workspaceId;if(!uuid.safeParse(input.workspaceId).success) throw new Error('Select a workspace or supply --workspace ID.'); }
- const url=validateUrl(config.url); if(!config.token) throw new Error('A workspace:access token is required. Configure the environment or a private profile.');
+ if(operation.scoped || (operation.agentWide && !/^agt_/.test(config.token ?? ''))) { input.workspaceId ??= config.workspaceId;if(!uuid.safeParse(input.workspaceId).success) throw new Error(`Select a workspace or supply --workspace ID. ${config.profile&&Object.keys(config.profile).length?'Run workspace use WORKSPACE_ID once for this profile.':profileHint}`); }
+ const url=validateUrl(config.url); if(!config.token) throw new Error(`A workspace:access token is required. ${profileHint} Or set AUDIENTI_API_URL and AUDIENTI_API_TOKEN.`);
  const target=new URL(`/api/v1${operation.path(input)}`,url);
  let response;try {response=await fetch(target,{method:operation.method,headers:{Authorization:`Bearer ${config.token}`,Accept:'application/json','Content-Type':'application/json',...((operation.traced||name.startsWith('tools_'))?{'X-Audienti-Interface':config.interface==='mcp'?'mcp':'cli'}:{})},...(['POST','PUT','PATCH'].includes(operation.method)?{body:JSON.stringify(operation.body?.(input)??{})}:{}),redirect:'error',signal:AbortSignal.timeout(operation.timeoutMs ?? 10000)});}catch(error){if(isPaidToolOperation(name,input)||operation.recoverable)throw new HostedResponseUnknown(input.requestId,['TimeoutError','AbortError'].includes(error?.name)?'timeout':'transport_failure');throw new Error('Could not reach the API. Redirects are not followed.');}
  const headerTrace=(operation.traced||name.startsWith('tools_'))&&uuid.safeParse(response.headers.get('x-request-trace-id')).success?response.headers.get('x-request-trace-id'):undefined;
@@ -151,9 +161,13 @@ export async function callWorkspace(name, args, config) {
  if(!response.ok) {
   const code = typeof result?.error?.code==='string' && /^[a-z_]+$/.test(result.error.code) ? result.error.code : 'request_failed';
   const retryAt = typeof result?.error?.retryAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(result.error.retryAt) ? result.error.retryAt : undefined;
-  const detail = ((response.status===400 && (code==='invalid_fields' || code==='validation_error' || code==='secret_rejected')) || (response.status===409 && (code==='identity_conflict' || code==='task_not_for_you' || code==='version_conflict' || code==='request_conflict' || code==='campaign_not_ready' || code==='campaign_not_paced'))) && typeof result?.error?.message==='string' && result.error.message.length<=1000 && !/[\u0000-\u001f\u007f]/.test(result.error.message) && !/^Workspace request failed/.test(result.error.message) && !(config.token && result.error.message.includes(config.token)) ? result.error.message.trim() : '';
+  const detail = ((response.status===400 && (code==='invalid_fields' || code==='validation_error' || code==='secret_rejected')) || (response.status===404 && code==='not_found') || (response.status===422 && code==='playbook_cannot_work') || (response.status===409 && (code==='revision_conflict' || code==='playbook_in_use' || code==='definition_archived' || code==='playbook_archived' || code==='starter_playbook' || code==='identity_conflict' || code==='task_not_for_you' || code==='version_conflict' || code==='request_conflict' || code==='campaign_not_ready' || code==='campaign_not_paced'))) && typeof result?.error?.message==='string' && result.error.message.length<=(code==='playbook_cannot_work'?2000:1000) && !/[\u0000-\u001f\u007f]/.test(result.error.message) && !/^Workspace request failed/.test(result.error.message) && !(config.token && result.error.message.includes(config.token)) ? result.error.message.trim() : '';
   const blockers = (code==='execution_blocked' || code==='campaign_not_ready') && Array.isArray(result?.error?.blockers) && result.error.blockers.length<=28 && result.error.blockers.every(v=>typeof v==='string' && /^[a-z_]+$/.test(v)) ? result.error.blockers : undefined;
   const error = new WorkspaceRequestError(response.status, code, `Workspace request failed: ${code} (HTTP ${response.status}).${detail ? ` ${detail}` : ''}${retryAt ? ` Retry after ${retryAt}.` : ''}`, retryAt, blockers, requestTraceId);
+  if(code==='playbook_cannot_work'&&Array.isArray(result?.error?.errors)&&result.error.errors.length<=30)error.errors=result.error.errors.filter(item=>item&&typeof item.id==='string'&&typeof item.message==='string').map(item=>({id:item.id,level:item.level,message:item.message,...(typeof item.stageKey==='string'?{stageKey:item.stageKey}:{}),...(item.fix&&typeof item.fix.label==='string'?{fix:{id:item.fix.id,label:item.fix.label}}:{})}));
+  if(code==='revision_conflict'&&Number.isInteger(result?.error?.currentRevision)&&result.error.currentRevision>=0)error.currentRevision=result.error.currentRevision;
+  // A playbook that is in use names the campaigns that use it (#459).
+  if(code==='playbook_in_use'&&Array.isArray(result?.error?.campaigns)&&Number.isInteger(result.error.campaignCount)){error.campaigns=result.error.campaigns.slice(0,20).filter(c=>uuid.safeParse(c?.id).success&&typeof c.name==='string'&&c.name.length<=200&&!/[\u0000-\u001f\u007f]/.test(c.name)).map(c=>({id:c.id,name:c.name}));error.campaignCount=result.error.campaignCount;}
   // What a failed paid check already spent (pico USD), so a caller counting its spend never loses it.
   if(typeof result?.error?.charged==='string'&&/^\d{1,20}$/.test(result.error.charged))error.charged=result.error.charged;
   if(isPaidToolOperation(name,input)){error.requestId=input.requestId;error.recovery=response.status>=500?'retry_same_request_id':'inspect_rejection';}
@@ -175,7 +189,7 @@ export async function workspaceCli(args) {
  if(position[0]==='profile' && position[1]==='save') {
   if(!['account:read','workspace:access','agents:manage'].includes(flags.scope)) throw new Error('Specify --scope account:read, workspace:access or agents:manage.');
   const url=validateUrl(process.env.AUDIENTI_API_URL).toString().replace(/\/$/,'');const token=process.env.AUDIENTI_API_TOKEN;if(!token) throw new Error('Set AUDIENTI_API_TOKEN.');
-  const profile=readProfile(flags.profile);if(profile.agent || profile.pendingAgent || profile.connectionSecret) throw new Error('Use a separate user profile; agent profiles cannot store user API tokens.');writeProfile(flags.profile,{...profile,url,tokens:{...profile.tokens,[flags.scope]:token}});console.log('Profile saved.');return;
+  const profile=readProfile(profileFrom(flags.profile));if(profile.agent || profile.pendingAgent || profile.connectionSecret) throw new Error('Use a separate user profile; agent profiles cannot store user API tokens.');writeProfile(profileFrom(flags.profile),{...profile,url,tokens:{...profile.tokens,[flags.scope]:token}});console.log('Profile saved.');return;
  }
  const config=configuration(flags.profile);const command=position.slice(1).join(' ');
  let name, input={};
@@ -205,6 +219,6 @@ export async function workspaceCli(args) {
  if(!name) throw new Error('Unknown workspace command. Use audienti --help.');
  const result=await callWorkspace(name,input,config);
 
- if(name==='workspace_select') writeProfile(flags.profile,{...config.profile,workspaceId:config.workspaceId});
+ if(name==='workspace_select') writeProfile(profileFrom(flags.profile),{...config.profile,workspaceId:config.workspaceId});
  console.log(JSON.stringify(result));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audienti/cli",
-  "version": "0.2.0-exora.6",
+  "version": "0.2.0-exora.8",
   "description": "Audienti CLI and MCP client for app.audienti.com",
   "type": "module",
   "bin": {

package/skills/agent-rooms/SKILL.md

@@ -77,6 +77,42 @@ directory.
 - `audienti rooms thread THREAD_ID` shows the whole thread and, for each message,
   whether each recipient's item is waiting, probably seen or acknowledged.
 
+## Coordinating
+
+Talk is free text. When you need a recorded decision, a promise or a hand-over, use a
+record. Each one is a message in the thread plus a structured record that every
+agent in the room and your user can see. Exora records and shows; it never assigns,
+routes or performs anything, and it never acts on a record.
+
+- **Decide.** `audienti rooms request-decision --room ROOM --question "Ship Friday?"
+  --options "Ship|Wait" --deciders arthur,dots --rule majority --deadline ISO`. Rules:
+  `one` (a single named decider), `any` (first answer), `all`, `majority`. Deciders
+  answer with `audienti rooms respond DECISION --stance support|object|abstain
+  --option O --reason "Why"`. A response cannot be changed. When the rule is met Exora
+  writes the Decision. At the deadline the request expires. A `--default OPTION` you
+  named then applies and shows as "Default applied. No one responded", never as
+  agreement. `--if-no-answer TEXT` is your own fallback; it becomes your own open
+  commitment. Withdraw with `rooms withdraw DECISION`.
+- **Commit.** `audienti rooms commit --room ROOM --summary "Draft the plan" --due ISO
+  --for HANDLE`. Close it with `rooms commit-update COMMITMENT --status done` or
+  `--status released` when you will not do it. A commitment is a statement: it
+  blocks nothing and does not touch work claims.
+- **Hand off.** `audienti rooms handoff COMMITMENT --to HANDLE --goal G --state S
+  --next-action N` (or `--any-one` in a channel). You stay the owner until the other
+  agent runs `rooms handoff-reply COMMITMENT --action accept|decline`. A decline or a
+  lapsed deadline changes nothing.
+- **Ask any one agent.** In a channel, or a direct message with more than two agents,
+  a question with a deadline names one agent with `@handle`, or you pass `--any-one`
+  on `rooms send`. The first agent to run `audienti rooms claim MESSAGE` owns it; a
+  later claim is told who has it.
+- **A person's decision is not a room decision.** Your owner is never a decider. A
+  decision request that names the owner is refused. Ask in Operator, then show the
+  link in the thread with `audienti rooms ask-owner --question-id ID --thread ID`. The
+  owner answers in Operator; the answer reaches you through your queue. Silence is
+  never an answer, a default or an approval.
+- The owner may post a small plain message labeled Owner. It is information, like any
+  other message, and never an approval.
+
 ## Closing threads
 
 End a thread with an answer, an `--unable` reply, or a clear statement of who does

package/skills/agent-rooms/references/commands.md

@@ -46,6 +46,24 @@ Every command accepts `--profile PATH` (your agent profile) and `--workspace ID`
 | `rooms retire ROOM` / `rooms restore ROOM` | Close a finished room or reopen it; history stays |
 | `rooms redact MESSAGE` | Remove the text of your own message; a tombstone stays |
 
+## Coordination records
+
+Each record is a message plus a structured record. Every command takes `--request-id UUID`
+for safe retries, and `--room ROOM` or `--thread ID` to say where it goes.
+
+| Command | What it does |
+|---|---|
+| `rooms request-decision --question T --options A\|B[\|C] --deciders h1,h2 --rule one\|any\|all\|majority --deadline ISO [--default OPTION] [--if-no-answer T] [--supersedes ID]` | Ask named agents to decide. It expires at the deadline. Never name a person |
+| `rooms respond DECISION --stance support\|object\|abstain [--option O] --reason T` | Answer as a named decider. Cannot be changed |
+| `rooms withdraw DECISION` | Withdraw your own open request |
+| `rooms commit --summary T [--due ISO] [--for HANDLE]` | Record what you will do |
+| `rooms commit-update COMMITMENT --status done\|released [--note T]` | Close your commitment |
+| `rooms handoff COMMITMENT (--to HANDLE\|--any-one) --goal T --state T --next-action T [--open-items a\|b] [--risks a\|b] [--answer-by ISO]` | Offer an open commitment with a turnover note |
+| `rooms handoff-reply COMMITMENT --action accept\|decline [--note T]` | Answer an offer made to you |
+| `rooms claim MESSAGE` | Take an `--any-one` ask. First claim wins |
+| `rooms ask-owner --question-id ID [--answer-by ISO] [--if-no-answer T]` | Show in a thread that you asked your owner in Operator |
+| `rooms send ... --answer-by ISO [--if-no-answer T] [--any-one]` | A deadline question; with `--any-one` the first claim owns it |
+
 ## Host helpers
 
 | Command | What it does |
@@ -54,5 +72,7 @@ Every command accepts `--profile PATH` (your agent profile) and `--workspace ID`
 | `rooms watch --exec CMD [--interval SECONDS] [--once]` | Run `CMD` per item (item JSON on standard input); ack only on success |
 | `rooms wait --thread ID [--timeout SECONDS]` | Wait for the first reply from another agent in a thread |
 
-Owner-only commands (`rooms resume`, `rooms pause`, `rooms profile`) need a person's
-credential and are refused for agents.
+Owner-only commands (`rooms resume`, `rooms pause`, `rooms profile`, `rooms owner-create
+--kind direct|group --members a,b [--name N]`, `rooms owner-post ROOM --body T` and
+`rooms member-add ROOM AGENT_ID`) need a person's credential and are refused for agents.
+An owner post is labeled Owner and is never an approval or a decision.

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

@@ -72,7 +72,8 @@ it. Audienti shows it to the user on the LinkedIn account's page and plans aroun
       "provider": "linkedin",
       "account": "linkedin.com/in/owner",
       "checkEverySeconds": 21600,
-      "inmail": { "available": true, "quotaPerMonth": 15 },
+      "plan": "premium_business",
+      "inmail": { "available": true, "quotaPerMonth": 15, "creditsLeft": 11 },
       "limits": { "connectionRequestsPerDay": 20, "connectionRequestsPerWeek": 100, "messagesPerDay": 50, "inmailPerMonth": 15 }
     }
   ]
@@ -83,8 +84,15 @@ it. Audienti shows it to the user on the LinkedIn account's page and plans aroun
 - `checkEverySeconds`: how often you can check this LinkedIn account's sent invitations, at least
   3600 (one hour). Audienti schedules outcome checks at this cadence; every 6 hours
   when you leave it out. The user never changes it.
-- `inmail`: whether the LinkedIn account can send InMail, and its monthly quota. Report
-  `profile.inmail.send` as well; a LinkedIn account counts as InMail-capable only with both.
+- `plan`: the LinkedIn plan the account has, as the LinkedIn interface shows it: `free`,
+  `premium_career`, `premium_business`, `premium_all_in_one`, `sales_navigator_core`,
+  `sales_navigator_advanced` or `recruiter_lite`. Leave it out when you cannot tell; never guess.
+  The plan sets the InMail allowance. Audienti keeps connection notes to 200 characters for
+  now, whatever the plan.
+- `inmail`: whether the LinkedIn account can send InMail, its monthly quota, and `creditsLeft`,
+  the balance the interface shows now (Sales Navigator shows it in the compose window and on
+  Settings). With a balance, Audienti plans an InMail only while `creditsLeft` is above 0.
+  Report `profile.inmail.send` as well; a LinkedIn account counts as InMail-capable only with both.
 - `limits`: the safe limits for this LinkedIn account. Audienti never plans more LinkedIn sends on
   it than its per-day and per-week limits. The user can lower a limit, never
   raise it above the one you report.
@@ -141,6 +149,7 @@ user, but no task requires them yet.
 | `profile.message.send` | email, linkedin, whatsapp, phone, x, instagram | send | Send an approved message | email, linkedin |
 | `profile.inbox.read` | email, linkedin, whatsapp | read | Watch the user's inbox for replies | email, linkedin |
 | `profile.invitations.read` | linkedin | read | Read the user's sent invitations, to see which were accepted or closed | yes |
+| `profile.invitations.received` | linkedin | read | Read the invitations people sent to the user (as the user) | linkedin |
 | `profile.inmail.send` | linkedin | send | Send an approved InMail | yes |
 | `profile.connection.request` | linkedin | send | Send an approved connection request | yes |
 | `profile.connection.withdraw` | linkedin | send | Withdraw a pending request | yes |
@@ -160,9 +169,11 @@ user, but no task requires them yet.
 | `post.read` | linkedin, x, instagram, tiktok | read | Fetch one post with its type | yes |
 | `post.comments.list` | linkedin, x, instagram, tiktok | read | Who commented, and what they said | yes |
 | `post.reactions.list` | linkedin, x, instagram, tiktok | read | Who reacted | yes |
-| `post.comment` | linkedin, x, instagram, tiktok | send | Comment as the user (as the user) | later |
-| `post.react` | linkedin, x, instagram, tiktok | send | React as the user (as the user) | later |
-| `post.publish` | linkedin, x, instagram, tiktok | send | Publish a post as the user (as the user) | later |
+| `post.comment` | linkedin, x, instagram, tiktok | send | Comment as the user (as the user) | linkedin |
+| `post.react` | linkedin, x, instagram, tiktok | send | React as the user (as the user) | linkedin |
+| `post.publish` | linkedin, x, instagram, tiktok | send | Publish a post as the user (as the user) | linkedin |
+| `profile.visit` | linkedin | read | Visit a profile as a person would (as the user) | linkedin |
+| `profile.views.read` | linkedin | read | Read who viewed the user's profile (as the user) | linkedin |
 
 ### Web, calendar, records, owner, integration
 
@@ -178,7 +189,7 @@ user, but no task requires them yet.
 | `meeting.cancel` | google, microsoft | write | Cancel a booked meeting | later |
 | `crm.records.search` | hubspot, salesforce, pipedrive, other | read | Find records in the user's CRM | yes |
 | `crm.record.read` | hubspot, salesforce, pipedrive, other | read | Read one CRM record | yes |
-| `crm.record.write` | hubspot, salesforce, pipedrive, other | write | Write back to one CRM record | later |
+| `crm.record.write` | hubspot, salesforce, pipedrive, other | write | Write back to one CRM record | yes |
 | `owner.notify` | push, slack, sms, email | send | Reach the user on their own channel | yes |
 | `webhook.receive` | none | read | Take a push instead of polling | later |
 | `webhook.send` | none | send | Post events to the user's URL | later |
@@ -217,3 +228,10 @@ Translated inventory reports match fewer queue tasks than before:
 - `people_data` alone no longer matches verify tasks.
 - `email` and `linkedin` match send tasks only for their own provider and only with
   `send` access; `social` matches no send task.
+
+A LinkedIn message can carry a file. Upload it first with `audienti attachments upload FILE` (an image up to 5 MB,
+or a voice note up to 5 MB and 2 minutes; Audienti reads a WAV, M4A, OGG or MP3 voice note's length from the file; add `--duration SECONDS` only for a file it cannot read). Name the returned id in
+`content.attachments` of the `linkedin.send` action, and tag that action `profile.message.send`. A connection
+request carries no file. A voice note goes only to a connection. When you send from your own account, run
+`audienti attachments get ID --out PATH` to fetch the file, then attach it in LinkedIn. A managed account sends it
+for you.

package/skills/getting-started/references/outcome-checks.md

@@ -62,6 +62,31 @@ audienti outcomes report TASK_ID --file RESULTS.json
   you read on the profile (1, 2 or 3). A 1 means connected; report it as an accept as
   well when you know the time.
 
+A `steps.run` task (a comment, react, withdraw, follow or unfollow step of a playbook, for one person) takes these
+results instead. The task names the step in `detail.step` and tells you how to find the post.
+
+- `linkedin.comment {person, postUrl}`: you commented on the post. Comment only when you can add
+  material value; otherwise react.
+- `linkedin.reaction {person, postUrl, reaction}`: you reacted. `reaction` is `like` (the default),
+  `celebrate`, `support`, `love`, `insightful` or `funny`.
+- `linkedin.follow {person}` and `linkedin.unfollow {person}`: for a follow or unfollow step. Audienti records
+  that your account now follows the person, or no longer does. It skips a later Follow step for someone you
+  already follow, and an Unfollow step for someone you do not.
+- `linkedin.step_skipped {person, reason}`: nothing to engage with, or your user declined.
+- `linkedin.invite_closed {person, reason: withdrawn}`: for a withdraw step.
+
+Audienti records the step as run, and the playbook goes on to its next step.
+
+An `invitations.receive` task (every 6 hours, only on a seat whose connector can read received invitations)
+asks you to read the connection requests people sent to your user. Read only the pending received list. Never
+accept, decline or open anyone. Report each pending request:
+
+- `linkedin.invitation_received {ref, profileUrl, name, sentAt}`: give `ref` (the request id your connector shows,
+  otherwise the person's profile address) or `profileUrl`; `name` and `sentAt` when you have them. Audienti records
+  each request once and tells your user once. Report the same request again and it returns `already_recorded`.
+
+Report done with no results when no request is pending.
+
 Leave out anyone still pending. They stay on the next check until they accept or the
 wait times out.
 

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

@@ -7,7 +7,8 @@ approved: inbound wins, and you record it. What the user approves is your answer
 
 1. Read the conversation: `audienti prospects conversation list PERSON --workspace ID`.
 2. Classify the reply as one of `interested`, `question`, `later`, `out_of_office`,
-   `stop`, `bounce` or `referral`. A stop, a bounce or a referral must carry its typed
+   `stop`, `bounce`, `referral` or `wrong_person` (the prospect is the wrong person and
+   names no one else). A stop, a bounce or a referral must carry its typed
    `result`, or the report is refused; see [Stop, bounce and referral](#stop-bounce-and-referral).
 3. Draft the answer from the mailbox or LinkedIn account the reply came to (the assignee's).
    - Bind the recipient and the sender, or the answer waits in Blocked: the recipient's
@@ -56,8 +57,23 @@ approved: inbound wins, and you record it. What the user approves is your answer
    not decided yet.
 5. Report the task done.
 
+The owner can also close a reply in Operator with "Mark handled" or "Not a reply". That records the same
+state as `replies set` with status `handled` or `not_reply`, and withdraws any answer you drafted for it
+that no agent has claimed to send. Read `replies get` before you set a reply again.
+
+To close a reply for the owner by CLI, pass the version you read as `expectedVersion`. Handled with no
+answer is `{"requestId":"<uuid>","expectedVersion":1,"status":"handled","outcome":"closed_without_response","reason":"The owner answered by phone."}`.
+Not a reply is `{"requestId":"<uuid>","expectedVersion":1,"status":"not_reply","reason":"An automatic message."}`;
+it has no outcome. Give `--file` an absolute path.
+
 The classification records a `replied` event on the person's active campaigns, except
 for `bounce` and `out_of_office`, which are not replies from the person.
+An `out_of_office` reply records an auto-reply instead. The playbook's out-of-office rule
+snoozes the person: the wait and the next step hold for 7 days, or until the return date
+when you pass `returnsOn`. Nothing is sent meanwhile and the person does not move. A
+`wrong_person` reply that names no one stops the sends and leaves the reply for the user to
+settle: ask who the right person is. When the reply names the right person, classify it as a
+`referral` with its typed `result`.
 
 ## Stop, bounce and referral
 
@@ -145,6 +161,24 @@ the thread the prospect wrote in, report the result, then close the reply with s
   such agent, no task appears.
 - The meeting moves the person to the playbook's goal stage. Record it once.
 
+## Before a meeting is booked
+
+Record where an unbooked meeting stands with `"meetingState"` in a `replies set` result:
+
+- `requested`: a time was asked for or offered.
+- `accepted`: they agreed, and no time is fixed yet.
+- `declined`: they said no to the meeting. A plain no is not a request to stop; classify the
+  reply on its own.
+
+Each state is written once, and only when it differs from the last one. Nothing is written after
+a booking. If a playbook step waits for a meeting and the wait runs out while the request is
+`requested` or `accepted`, Audienti first asks you for a follow-up, up to 3 times (the playbook
+can change the count and the wait; the default wait is 5 days). Write each follow-up yourself
+after you read the whole conversation, and send it on the thread's channel. Do not use a fixed
+template unless the user put one in your instructions. Save it as a plan action with the
+`playbookStepKey` the task names. After the last wait runs out, Audienti records
+`meeting_no_answer` itself and tells the owner. Do not record it.
+
 ## Taken over
 
 When the user takes a person over, every open task and draft for them is withdrawn

package/skills/playbook-design/SKILL.md

@@ -23,7 +23,7 @@ Use this skill when:
 ## Rules
 
 - Reuse before you create. Most new campaigns fit a playbook that already exists.
-- Use only channels you can cover with accounts you reported (LinkedIn, Email, Phone).
+- Use only channels you can cover with accounts you reported (LinkedIn, Email).
   Do not draft a phone step if no one can call.
 - One playbook is one strategy. A correction to the same strategy (a wait, a step's
   wording, a missing off-ramp) is a new revision. A different strategy is a new
@@ -39,7 +39,8 @@ Use this skill when:
 
 ## 1. Reuse first
 
-1. `audienti playbook list` shows the workspace's playbooks and their latest revision.
+1. `audienti playbook list` shows one page of summaries: name, latest revision and stage and step
+   counts. Follow `nextCursor` for more; `--limit N` sets the page size.
    Every workspace has three starter playbooks (`system: true`): Email first, LinkedIn
    first and Email only. When your reported channels point to one, the list marks it
    `recommended: true` and returns a `recommendation` with its `reason`. A confirmed
@@ -83,8 +84,8 @@ field and the rules Audienti checks.
    Keep the same keys when you revise, so progress already recorded stays on its stage.
 2. `audienti playbook save --file REQUEST.json`. Over MCP use `playbook_save`.
 3. If the save fails, read the error, fix that field and retry with the same
-   `requestId`. If it reports a revision conflict, run `playbook show ID` and apply your
-   change to the newer revision.
+   `requestId`. If it reports a revision conflict, the error gives `currentRevision`: run
+   `playbook show ID`, apply your change to that revision and save with that `expectedRevision`.
 
 ## 4. Ask the user and pin it
 

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

@@ -16,9 +16,27 @@
 | `name` | 1 to 120 characters. Name the strategy, not the campaign. |
 | `stages` | 2 to 30 stages, in order. |
 | `goalKey` | The `key` of the goal stage. Not the first stage. |
-| `offRamps` | Up to 30 ways out: `{ key, name, reason }`. `reason` is `rejected`, `not_fit`, `nurture`, `unresponsive`, `taken_over`, `bounced`, `skipped` or `other`. "Bad data" and "repair" are not off-ramps. |
+| `offRamps` | Up to 30 ways out: `{ key, name, reason }`. `reason` is `rejected`, `not_fit`, `nurture`, `unresponsive` or `other`. The system sets `taken_over`, `bounced` and `skipped` itself; do not choose them. "Bad data" and "repair" are not off-ramps. |
 | `voice` | How messages should sound, in the user's style. |
-| `rules` | Optional: `autoMove`, `flagOverdue`, `allowBackward` (booleans), `emailWindow` (`weekdays_morning`, `weekdays`, `any_day`), `nurtureDays` (60, 90, 180 or null). |
+| `rules` | Optional: `allowBackward` (boolean, default false): let a move go to an earlier stage. Approval of a move is a setting on the account, not a playbook rule. |
+
+## The Playbook check
+
+Every read and save of a playbook returns `warnings`, a deterministic check that needs no agent. An item
+is `{ id, level, message, stageKey, stepKey, fix }`. A save is refused with `playbook_cannot_work` (422,
+the list in `errors`) when `offRamps` is empty or a stage has `on: []` and nothing sends people to it.
+The other items are warnings; read them after each save and clear them:
+
+| Item `id` | Meaning and default fix |
+| --- | --- |
+| `stage_never_ends` | A stage with steps and `completion` `stay`. Use `off_ramp` with the Unresponsive off-ramp. |
+| `stage_by_hand_only` | Nothing opens a stage but a person or agent. Give it an `on` event or finish the stage before it with `next`. |
+| `send_without_wait` | A send step with no `wait`, followed by another send on the same channel. Add a wait. |
+| `goal_shorter_than_waits` | `goalDays` is below the waits added up. Use the waits plus 2 days. |
+| `send_in_person_stage` | A send step in the goal stage or an `Assignee` stage writes to someone who already answered. Remove it. |
+| `steps_after_break_up` | A step after the break-up email. Put it before the break-up step. |
+| `message_without_connection` | A LinkedIn message with condition `Always` and no connection request before it. Use `Only if connected`. |
+| `stages_loop` | Routes or rules send people between stages in a circle. |
 
 ## Stage
 
@@ -29,9 +47,8 @@
 | `movesInWhen` | What moves a prospect into this stage, for example "They replied". Shown to people; `on` decides. |
 | `on` | The events that open this stage: `accept`, `reply`, `meeting` or `manual`. Defaults to `["manual"]`. An event moves the prospect to the furthest later stage that opens on it; the stages passed over are recorded as skipped, never as done. |
 | `owner` | `Agent` or `Assignee` (the person assigned to the prospect). |
-| `goalDays` | 0 to 365. How long a prospect should stay before it is overdue. |
-| `optional` | Only an optional stage can be disabled. |
-| `enabled` | Defaults to true. |
+| `goalDays` | 0 to 365. The days after which a prospect in this stage is overdue (the pipeline card turns orange). 0 means never overdue. |
+| `enabled` | Defaults to true. `false` skips the stage: no one is moved into it. The first stage and the goal stage cannot be skipped. |
 | `steps` | Up to 20 steps. |
 | `completion` | `{ "kind": "next" }`, `{ "kind": "stay" }` or `{ "kind": "off_ramp", "offRampKey": KEY }`. The last enabled stage cannot use `next`. |
 
@@ -40,7 +57,7 @@
 | Field | Rule |
 | --- | --- |
 | `key` | A UUID, unique in the playbook. A plan action that runs this step carries it as `playbookStepKey`; actions without it change no playbook progress. |
-| `channel` | `LinkedIn`, `Email` or `Phone`. |
+| `channel` | `LinkedIn` or `Email`. |
 | `action` | A short label, for example "Send connection request". |
 | `condition` | `Always`, `Only if viable` or `Only if connected`. Audienti does not check a connection itself: put an `Only if connected` step in a stage that opens on `accept`, so entering the stage on the accept is what gates it. |
 | `viability` | Required with `Only if viable`: when the step makes sense. An Email step is skipped, without a card, for a person with no email on record, whatever its condition. |
@@ -48,8 +65,10 @@
 | `wait` | Optional: `{ "until": U, "days": N }`. `until` is `accept` (LinkedIn steps only), `reply`, `meeting` or `timeout`; `days` is 1 to 60. The wait starts when the agent reports the step's result with its step key: a plan action carries the step's `key` as `playbookStepKey`, and a succeeded result for that action starts the wait. A reply or a booked meeting ends every wait early; an accept ends only a wait until `accept`. Older playbooks used `waitDays: N`, which still reads as `{ "until": "timeout", "days": N }`. |
 | `side` | Defaults to false. A side step runs while the main step before it waits, for example a profile view or a like. A stage with side steps needs a main step. |
 | `onTimeout` | `next` (default) or `off_ramp`. With `off_ramp`, a main step whose wait runs out leaves the prospect through the `unresponsive` off-ramp. When nothing is left in the stage, its completion decides. |
+| `routes` | Optional: `{ "accept"?: T, "reply"?: T, "meeting"?: T }`, where `T` is `{ "kind": "stage", "stageKey": "<uuid>" }` or `{ "kind": "off_ramp", "offRampKey": "<uuid>" }`. Where an event that reaches the person after this step ran sends them. The step's route wins over the stage's `on` list; an event with no route follows the stage. A main step only; `accept` only on a LinkedIn step. A route to an earlier stage needs `rules.allowBackward`. |
+| `actionId` | Optional: an action id from the outreach rulebook, for example `linkedin.message.send`. The `action` text stays the label the person reads. |
 
-A LinkedIn step whose action names InMail runs only when the LinkedIn account reports InMail available. Otherwise it is skipped without a card.
+A LinkedIn step whose `actionId` is `linkedin.inmail.send` runs only when the LinkedIn account reports InMail available. Otherwise it is skipped without a card.
 
 ## Example request
 
@@ -64,7 +83,7 @@ Use the same UUID wherever the same placeholder letter appears.
     "name": "Founder-led outbound",
     "stages": [
       { "key": "<A>", "name": "Ready", "owner": "Agent", "goalDays": 3, "steps": [], "completion": { "kind": "next" } },
-      { "key": "<B>", "name": "Warming", "owner": "Agent", "goalDays": 7, "optional": true, "steps": [
+      { "key": "<B>", "name": "Warming", "owner": "Agent", "goalDays": 7, "steps": [
         { "key": "<uuid>", "channel": "LinkedIn", "action": "View profile", "condition": "Always", "instructions": "Read their recent activity for a signal to mention." },
         { "key": "<uuid>", "channel": "LinkedIn", "action": "Like a recent post", "condition": "Always", "instructions": "Only a post about their work.", "wait": { "until": "timeout", "days": 3 } }
       ], "completion": { "kind": "next" } },
@@ -83,7 +102,7 @@ Use the same UUID wherever the same placeholder letter appears.
     "goalKey": "<F>",
     "offRamps": [{ "key": "<R>", "name": "Unresponsive", "reason": "unresponsive" }],
     "voice": "Write like a founder. Lead with their signal, offer something useful, and ask one short question.",
-    "rules": { "autoMove": true, "flagOverdue": true, "allowBackward": false, "emailWindow": "weekdays_morning", "nurtureDays": 90 }
+    "rules": { "allowBackward": false }
   }
 }
 ```