@audienti/cli 0.1.145 → 0.2.0-exora.2

package/cli/workspaces.mjs

@@ -0,0 +1,158 @@
+import {approachOperations} from './approach-operations.mjs';
+import {connectionRegistryOperations} from './connection-registry-operations.mjs';
+import { hostedToolOperations, paidToolByName, isPaidToolOperation, paidToolResult } from './tools-operations.mjs';
+import { workspaceExecutionOperations } from './work-execution-operations.mjs';
+import { workFeedbackOperations } from './work-feedback-operations.mjs';
+import { accountReplyOperations } from './account-reply-operations.mjs';
+import { accountIntakeOperations } from './account-intake-operations.mjs';
+import { recipientOperations } from './recipient-operations.mjs';
+import { suppressionOperations } from './suppression-operations.mjs';
+import { workOperations } from './work-operations.mjs';
+import { assignmentOperations } from './assignment-operations.mjs';
+import {discoveryOperations} from './discovery-operations.mjs';
+import {experimentOperations} from './experiment-operations.mjs';
+import {audienceOperations} from './audience-operations.mjs';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, statSync, lstatSync, realpathSync } from 'node:fs';
+import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import {offerOperations} from './offer-operations.mjs';
+const uuid = z.string().uuid();
+const workspace = { workspaceId: uuid.optional() };
+export const operations = {
+ ...approachOperations,
+ ...connectionRegistryOperations,
+ ...hostedToolOperations,
+ ...workOperations,
+ ...workspaceExecutionOperations,
+ ...workFeedbackOperations,
+ ...suppressionOperations,
+ ...recipientOperations,
+ ...accountIntakeOperations,
+ ...accountReplyOperations,
+ ...assignmentOperations,
+ ...discoveryOperations,
+ ...offerOperations,
+ ...audienceOperations,
+ ...experimentOperations,
+ workspace_sending_settings_get: {schema:z.object({...workspace,userId:uuid.optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/sending-settings${a.userId?'?userId='+encodeURIComponent(a.userId):''}`,scoped:true,description:'Read workspace sending defaults, or own member effective hours, ramp and activity limits with userId. A workspace Admin may read another member. External activities remain agent-managed; these values do not authorize sending.'},
+ workspace_member: {schema:z.object({...workspace,userId:uuid}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/members/${a.userId}`,scoped:true},
+ workspace_agent_access: { schema:z.object(workspace).strict(), method:'GET', path:a=>`/workspaces/${a.workspaceId}/agent-access`, scoped:true },
+ workspace_agent_access_set: { schema:z.object({...workspace,userId:uuid,blocked:z.boolean()}).strict(), method:'POST', path:a=>`/workspaces/${a.workspaceId}/members/${a.userId}/agent-access`, body:a=>({blocked:a.blocked}), scoped:true },
+ workspace_initialize: { schema: z.object({}).strict(), method: 'POST', path: () => '/workspaces/bootstrap' },
+ workspace_list: { schema: z.object({}).strict(), method: 'GET', path: () => '/workspaces' },
+ workspace_create: { schema: z.object({ name: z.string().trim().min(1).max(80), requestId: uuid }).strict(), method: 'POST', path: () => '/workspaces', body: a => a },
+ workspace_get: { schema: z.object(workspace).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}`, scoped: true },
+ workspace_invite: { schema: z.object({ ...workspace, email: z.string().trim().email() }).strict(), method: 'POST', path: a => `/workspaces/${a.workspaceId}/invitations`, body: a => ({ email: a.email }), scoped: true },
+ workspace_invitation_retry: { schema: z.object({ ...workspace, id: uuid }).strict(), method: 'POST', path: a => `/workspaces/${a.workspaceId}/invitations/${a.id}/retry`, scoped: true },
+ workspace_invitation_cancel: { schema: z.object({ ...workspace, id: uuid }).strict(), method: 'POST', path: a => `/workspaces/${a.workspaceId}/invitations/${a.id}/cancel`, scoped: true },
+ workspace_invitations: { schema: z.object({}).strict(), method: 'GET', path: () => '/me/invitations' },
+ workspace_invitation_get: { schema: z.object({ id: uuid, generation: z.number().int().positive() }).strict(), method: 'GET', path: a => `/invitations/${a.id}?generation=${a.generation}` },
+ workspace_invitation_accept: { schema: z.object({ id: uuid, generation: z.number().int().positive() }).strict(), method: 'POST', path: a => `/invitations/${a.id}/accept`, body: a => ({ generation: a.generation }) },
+ workspace_select: { schema: z.object({ workspaceId: uuid }).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}` },
+};
+function profilePath(path) {
+ const target=resolve(path); const parent=dirname(target);
+ const repo=realpathSync(fileURLToPath(new URL('..',import.meta.url)));
+ const lexical=relative(repo,parent);
+ if(!lexical || (!lexical.startsWith('..') && !isAbsolute(lexical))) throw new Error('Store CLI profiles outside the repository.');
+ mkdirSync(parent,{recursive:true,mode:0o700});
+ const realParent=realpathSync(parent);
+ const rel=relative(repo,realParent);
+ if (!rel || (!rel.startsWith('..') && !isAbsolute(rel))) throw new Error('Store CLI profiles outside the repository.');
+ return resolve(realParent,target.slice(parent.length+1));
+}
+export function readProfile(path) {
+ if (!path) return {};
+ const target=profilePath(path);
+ try {
+  if(lstatSync(target).isSymbolicLink()) throw new Error("CLI profiles must not be symbolic links.");
+  const stat=statSync(target);
+  if ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()) throw new Error('CLI profile must be owned by you and readable only by you (chmod 600).');
+  return JSON.parse(readFileSync(target,'utf8'));
+ } catch(error) {if(error.code==='ENOENT') return {};throw new Error('Could not read a private CLI profile. Check ownership, permissions and JSON format.');}
+}
+export function writeProfile(path, profile) {
+ if (!path) throw new Error('Supply --profile PATH outside the repository.');
+ const target=profilePath(path); const temporary=`${target}.${process.pid}.tmp`;
+ writeFileSync(temporary,JSON.stringify(profile)+'\n',{mode:0o600,flag:'wx'}); renameSync(temporary,target);
+}
+export function configuration(path, scope='workspace:access') {
+ 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 };
+}
+export function validateUrl(value) {
+ let url;try {url=new URL(value);}catch{throw new Error('Set AUDIENTI_API_URL to an API URL ending with /api/v1.');}
+ if(url.username || url.password || url.search || url.hash || url.pathname.replace(/\/$/,'')!=='/api/v1') throw new Error('The API URL must end with /api/v1 and contain no credentials, query or fragment.');
+ 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;
+}
+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} : {}) }; }
+}
+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; }
+ toJSON() { return {...(this.requestTraceId?{requestTraceId:this.requestTraceId}:{}),code:'response_unknown',requestId:this.requestId,reason:this.reason,message:this.message,recovery:'retry_same_request_id'}; }
+}
+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.');
+ const input={...parsed.data};
+ if(operation.scoped) { 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.');
+ 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))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;
+ let result;try{result=await response.json();}catch{if(isPaidToolOperation(name))throw new HostedResponseUnknown(input.requestId,'invalid_response',headerTrace);throw new Error('The API returned an invalid response.');}
+ const requestTraceId=uuid.safeParse(result?.requestTraceId).success?result.requestTraceId:headerTrace;
+ 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 blockers = code==='execution_blocked' && 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}).${retryAt ? ` Retry after ${retryAt}.` : ''}`, retryAt, blockers, requestTraceId);
+  if(isPaidToolOperation(name)){error.requestId=input.requestId;error.recovery=response.status>=500?'retry_same_request_id':'inspect_rejection';}
+  throw error;
+ }
+ if(!result || !Object.hasOwn(result,'data')) {if(isPaidToolOperation(name))throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);throw new Error('The API returned an invalid response.');}
+ const paidResult = paidToolResult(name, result?.data);
+ if(isPaidToolOperation(name)&&(!uuid.safeParse(paidResult?.operationId).success||paidResult.requestId!==input.requestId||!['running','succeeded','failed','uncertain','rejected'].includes(paidResult.status)))throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);
+ if(name==='workspace_select') config.workspaceId=input.workspaceId;
+ return {data:result.data,...(requestTraceId?{requestTraceId}:{})};
+}
+export async function workspaceCli(args) {
+ const flags={}; const position=[];
+ for(let i=0;i<args.length;i++) {
+  if(args[i]==='--json') continue;
+  if(args[i].startsWith('--')) {const key=args[i].slice(2);if(!['profile','workspace','name','request-id','email','generation','scope','user'].includes(key)||!args[i+1]||args[i+1].startsWith('--')) throw new Error('Unknown or incomplete option.');flags[key]=args[++i];}
+  else position.push(args[i]);
+ }
+ 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 config=configuration(flags.profile);const command=position.slice(1).join(' ');
+ let name, input={};
+ if(command==='sending-settings') {name='workspace_sending_settings_get';input={workspaceId:flags.workspace,...(flags.user?{userId:flags.user}:{})};}
+ else if(command==='agent-access') {name='workspace_agent_access';input={workspaceId:flags.workspace};}
+ else if(['agent-access block','agent-access restore'].includes(command)) {name='workspace_agent_access_set';input={workspaceId:flags.workspace,userId:flags.user,blocked:command.endsWith('block')};}
+ else if(command==='init') name='workspace_initialize';
+ else if(command==='list') name='workspace_list';
+ else if(command==='create') {name='workspace_create';input={name:flags.name,requestId:flags['request-id']};}
+ else if(command==='show') {name='workspace_get';input={workspaceId:flags.workspace};}
+ else if(command==='invite') {name='workspace_invite';input={workspaceId:flags.workspace,email:flags.email};}
+ else if(command==='invitations') name='workspace_invitations';
+ else if(position[1]==='member' && position.length===3) {name='workspace_member';input={workspaceId:flags.workspace,userId:position[2]};}
+ else if(position[1]==='use' && position.length===3) {name='workspace_select';input={workspaceId:position[2]};}
+ else if(position[1]==='invitation' && position.length===4) {
+  const action=position[2];name={show:'workspace_invitation_get',accept:'workspace_invitation_accept',retry:'workspace_invitation_retry',cancel:'workspace_invitation_cancel'}[action];
+  input={id:position[3],...(['retry','cancel'].includes(action)?{workspaceId:flags.workspace}:{generation:Number(flags.generation)})};
+ }
+ 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});
+ console.log(JSON.stringify(result));
+}

package/package.json

@@ -1,46 +1,35 @@
 {
   "name": "@audienti/cli",
-  "version": "0.1.145",
-  "description": "Agent-first command-line client for Audienti.",
+  "version": "0.2.0-exora.2",
+  "description": "Audienti CLI and MCP client for exo.audienti.com",
   "type": "module",
   "bin": {
-    "audienti": "./bin/audienti.js",
-    "audienti-mcp": "./bin/audienti-mcp.js"
+    "audienti": "cli/audienti.mjs",
+    "audienti-mcp": "bin/audienti-mcp.mjs"
   },
   "files": [
+    "cli/",
     "bin/",
-    "src/",
     "skills/",
-    ".mcp.json",
-    "install",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "source-manifest.json"
   ],
-  "scripts": {
-    "test": "node --test test/*.test.js",
-    "verify": "node scripts/verify-package.mjs",
-    "check": "npm run verify && npm test"
-  },
   "engines": {
-    "node": ">=20"
+    "node": ">=24 <25"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/audienti/cli.git"
-  },
-  "homepage": "https://github.com/audienti/cli#readme",
-  "bugs": {
-    "url": "https://github.com/audienti/cli/issues"
+    "url": "git+https://github.com/audienti/cli.git",
+    "directory": "exora"
   },
   "license": "SEE LICENSE IN LICENSE",
-  "keywords": [
-    "audienti",
-    "cli",
-    "agents",
-    "go-to-market"
-  ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "exora"
   }
 }

package/skills/audienti/SKILL.md

@@ -1,337 +1,75 @@
 ---
 name: audienti
-description: Use when the user wants to operate Audienti through the production CLI or app-hosted MCP endpoint, including account selection, plays, prospect imports, lists and routing rules, message previews, analytics, Inbox Ops, Network Ops, or supported operator outcomes.
+description: Find, enrich, and expand CRM profile research using Audienti's account-scoped records, explicit paid tools, and executable deterministic helpers. Use for saved Prospect/Profile lookup, known profile URLs, relevant posts and their participants, or discovering additional profiles for the same identity.
 ---
 
-# Audienti CLI and MCP
+# Audienti profile research
 
-Use the installed `audienti` command or Audienti's app-hosted MCP endpoint as
-the production contract. The packaged `audienti-mcp` command is only a local
-stdio bridge for MCP hosts. Do not build a parallel wrapper or call
-undocumented API endpoints.
+You own the research workflow. Audienti keeps canonical Prospect/Profile records,
+citations, authorization and paid-tool accounting. A Prospect is a person or company;
+it can have many source Profiles. Employment links a person and company through
+citations; it does not make them one identity.
 
-Before creating, changing, or judging any experiment, read the complete
-[outbound methodology](references/methodology.md), also available through
-`audienti help methodology`. The customer owns the strategy. Record a written
-baseline, target and scheduled review date before starting; judge only matured
-cohorts. `experiments`, `experiment`, and `plays` are aliases for `motions`,
-including command help. CLI reminders are guidance; existing authorization and
-sending controls still apply.
+First inspect the selected workspace, current permissions and available tools. Use
+the account the user selected; never search another workspace or global cache as a
+substitute. Discover current contracts with `audienti tools list`, `tools describe`
+and resource help. Read [the workflow recipes](references/profile-workflows.md)
+and [helper contracts and installation](references/helpers.md). Keep an
+[agent research receipt](references/workflow-receipt.md) as you work.
 
-For website-only gift research, run `audienti tools gift-research --url <website>`
-and follow the returned skill using your own browsing tools. The command supplies
-instructions; it does not perform research or call the app. The bundled
-`audienti-gift-research` skill also works independently of this production
-workflow. Do not use offer scans or create gifts for this research exercise.
+## Executable helpers
 
-Use `audienti skills list` and `audienti skills show <name>` to discover bundled
-skills or the Audienti marketplace snapshot. Marketplace entries provide source
-links and install commands, not bundled upstream implementations. Read the
-upstream README and applicable skill before use; its dependencies and permissions
-still apply. Installation requires a separate instruction from the user.
+The skill includes four deterministic helpers. They consume supplied JSON; none
+performs research, calls a model, reads the CRM, writes records or charges credits.
 
-Before using a social-network finder, inspect the local environment for available
-browser/search tools, connected MCP tools or apps, installed skills and CLIs,
-and existing secure credential configuration without printing secrets. Read their
-documentation and permissions to choose supported read-only access to that network.
-Do not assume Apify, a browser session or credentials are available. If suitable
-access is missing, report the missing capability and ask the owner; do not invent
-findings, install tools or silently switch networks. Read the environment check
-returned by `audienti skills show <finder>` before following its upstream skill.
-The full returned check applies. It does not authorize granting access, sending
-messages or posting comments to test access.
-
-Set `approach` in a Motion create/update payload, or use `motions update <id> --approach "..."`. A nonblank Approach automatically guides adaptive planning and writing; blank, nil, or whitespace keeps the existing sequence. The simple `--approach ""` flag explicitly clears the guidance and restores that sequence. There is no separate planning-mode selector, and existing sending controls still apply.
-
-To clear an Inbox Ops backlog, run `inbox-ops queue` first: it follows every page, numbers each row, and saves the numbered list locally for the selected account. Then use `inbox-ops ignore`, `filter-domain`, `filter-sender`, `allow-domain`, or `allow-sender` with numbers, ranges (`1-25,30`), row ids, `--domain`, or `--sender`. Always run `--dry-run` first when acting for a person, read the per-row planned/skipped/rejected results back, and only then re-run with `--yes`. Numbers stay valid until `inbox-ops queue` runs again; ignore hides one thread until a new reply, while filter and allow rules are durable across all of the owner's accounts. Rule verbs given only `--domain` or `--sender` write the keyed rule directly. Through MCP use `inbox_ops.queue`, then `inbox_ops.actions` with `{operation, row_ids, dry_run}`.
-
-When Operator exposes `answer_planner_question`, read its prompt and candidate options with `operator queue` or `operator next`. Use `operator answer <row_id> --choice <id>` or `--answer "..."`, exactly one input. This command refetches the exact row and submits the current row and decision fingerprints. Do not substitute a generic outcome, a reusable steer note, or a guessed send. A 409 means refresh the question; 202 means the answer was recorded and planning continues. Answers apply only to that decision.
-
-## Setup
-
-1. Verify the command is installed:
-
-```bash
-audienti --help
-```
-
-2. If it is unavailable, install the public package:
-
-```bash
-curl -fsSL https://cli.audienti.com/install | bash
+```sh
+audienti skills helper profile-queries --file context.json --json
+audienti skills helper profile-candidates --file results.json --json
+audienti skills helper profile-completeness --file field-states.json --json
+audienti skills helper profile-evidence --file supplied-text.json --json
 ```
 
-3. Authentication is explicit and per machine. Do not ask a user to paste a
-production token into chat, a repository file, an issue, or a CI secret. For a
-person at a terminal, the friendly first run is:
+Without the CLI, run the same bundled code with Node:
 
-```bash
-audienti start
-audienti setup
+```sh
+node scripts/run.mjs profile-queries --file context.json
 ```
 
-`audienti start` signs in through the browser (or creates an account), picks
-the account, hands an unpaid account to the web pay page (or takes a signup
-code), and runs setup in the terminal. `audienti start --json` never prompts; it
-reports `sign_in_required`, `payment_required` (with `payment_url`) or `ready`.
-Never pay or enter a signup code for the user. LinkedIn connect is finished on
-the web setup page (`/quick_start/go_live`); that page acts on the browser's current
-account, so tell the user to switch the browser to the CLI account first. Browser login alone is:
-
-```bash
-audienti auth login
-```
-
-`audienti setup --url <company_url> --sell-to "<who they sell to>" --ask "<what
-prospects say yes to>" --json` drafts a first experiment without creating it.
-Add `--city`, `--state` and `--country` when setup says it needs the place. Show
-the draft to the user and add `--yes` only after they approve creating it.
-
-Use `audienti auth token` only after the user supplies a token through an
-approved secure channel.
-
-4. Start with discovery, not mutation:
-
-```bash
-audienti auth status
-audienti accounts list --json
-audienti help agent-workflows
-```
-
-For MCP hosts, configure the packaged `.mcp.json` or run:
-
-```bash
-audienti-mcp
-```
-
-The bridge reads the same local config as the CLI and forwards MCP JSON-RPC to
-the app-hosted `/mcp` endpoint. Before starting the bridge, select account
-context:
-
-```bash
-audienti auth login
-audienti accounts list --json
-audienti accounts create --name Doppel --parent OMALab --json
-audienti accounts select <acct_id>
-audienti users select me
-```
-
-If the MCP host can call HTTP directly, use `POST /mcp` with the same bearer
-token as the API. Call `tools/list` first, then call named tools with
-`tools/call`. Account-scoped tools accept `account_id`; the local bridge injects
-the selected CLI account when it is omitted.
-
-Useful MCP tools:
-
-- `auth.me` confirms the token identity.
-- `accounts.list` shows accessible accounts.
-- `setup.play_preflight` returns connected-account readiness and setup or
-  mapping URLs, including the selected sender's active days, working hours,
-  effective timezone, current in-window status, configured user fallback
-  location, effective proxy geography and source, and server-calculated
-  LinkedIn pacing and outstanding-invitation inventory authority under
-  `social_cookie.automation`. Treat `ready: true` as connection readiness, not
-  approval to start automation.
-- `offers.create`, `icps.create`, and `motions.create` set up the offer, ICP,
-  and play.
-- Use `audienti icps list --status all` to audit active and archived ICPs. Use
-  `audienti icps archive <icp_id>` for reversible cleanup and `restore` to make
-  the ICP selectable again; restore never reactivates motions.
-- Use `audienti motions abm-companies <motn_id> add --file <txt|json>` to attach
-  a positive company filter list for isolated ABM discovery runs.
-- `analytics.stages` returns stage conversion cohorts and stage aging.
-- `analytics.cohort_lists.create` materializes event cohorts as reusable lists.
-
-## Operating Rules
-
-- Use `--json` whenever another agent or tool will consume the response.
-- Use `audienti <resource> <action> help` before a mutation when the accepted
-  payload or behavior is unclear.
-- Inspect the current resource before a create, update, attach, delete, or
-  operator outcome writeback.
-- For account-user automation, run `users automation show`, then preview the
-  exact payload without `--apply`. Apply only after explicit authorization and
-  verify the applied response/readback.
-- Treat the production API as the source of truth. Persist durable work in
-  Audienti rather than leaving it only in agent prose.
-- Keep current gaps explicit. Do not imply that unsupported actions execute.
-
-## Common Entry Points
-
-```bash
-audienti help agent-workflows
-audienti prospects list --query "name or company" --wide --json
-audienti prospects list --assigned-user unassigned --json
-audienti prospects assign <prsp_id> --assigned-user me --json
-audienti prospects move-account <prsp_id> --account <source_acct_id> --target-account <target_acct_id> --json
-audienti prospects move-account <prsp_id> --account <source_acct_id> --target-account <target_acct_id> --assigned-user me --apply --json
-audienti prospects set-status <prsp_id> --status not_fit --json
-audienti prospects lock <prsp_id> --note "Emergency hold" --json
-audienti prospects unlock <prsp_id> --json
-audienti users activity me --window 7d --json
-audienti users automation show <account_user_id|me> --platform linkedin --json --account <acct_id>
-audienti users automation update <account_user_id|me> --payload automation-controls.json --json --account <acct_id>
-audienti users automation update <account_user_id|me> --payload automation-controls.json --apply --json --account <acct_id>
-audienti social-cookies sync-messages <scok_id> [--folder <folder>] [--retry] --json
-audienti prospects import-batch --file prospects.csv --motion <motn_id> --assigned-user me --json
-audienti lists create --name "Target list" --json
-audienti lists routing-rules <list_id> list --json
-audienti lists routing-rules <list_id> create --payload routing-rule.json --json
-audienti lists routing-rules <list_id> move <rule_id> up --json
-audienti lists routing-rules <list_id> apply --json
-audienti motions quick-start --url https://example.com --wait --confirm --json
-audienti motions abm-companies <motn_id> add --file abm-domains.txt --json
-audienti motions abm-companies <motn_id> list --json
-audienti motions update <motn_id> --status paused --json
-audienti motions update <motn_id> --start-date 2026-09-01 --end-date 2026-09-30 --maximum-company-count 25 --json
-audienti motions update <motn_id> --payload motion-principal-list.json --json
-audienti motions activate <motn_id> --json
-audienti motions delete <motn_id> --confirm yes --json
-audienti operator next --json
-audienti operator next --plan
-audienti network-ops queue --json
-audienti network-ops accept <row_id> --account <acct_id> --json
-audienti network-ops decline <row_id> --account <acct_id> --json
-audienti inbox-ops queue --json
-audienti inbox-ops queue --group-by domain
-audienti inbox-ops ignore 1-25 --dry-run --json
-audienti inbox-ops ignore 1-25 --yes --json
-audienti inbox-ops filter-domain --domain alerts.example.com --yes --json
-audienti inbox-ops filter-sender 3,7 --yes --json
-audienti inbox-ops filters --json
-audienti inbox-ops rule <row_id> --scope <sender|domain> --disposition <allow|filter> --json
-audienti analytics motions --json
-audienti analytics icps --json
-audienti analytics prospects --window 24h --json
-audienti analytics stages --window 30d
-audienti analytics visibility --window 24h --user me --json
-audienti analytics content --window week --json
-audienti tools list --json
-audienti tools humanize --file draft.txt --tone professional --json
-audienti tools email-find --first-name Ada --last-name Lovelace --company-domain example.com --wait --json
-audienti tools email-find --linkedin-url https://www.linkedin.com/in/example --wait --json
-audienti tools linkedin-enrich --url https://www.linkedin.com/in/example --wait --json
-audienti tools signals-find --icp "<ICP description>" --question "<signal question>" --wait --json
-audienti tools write --purpose "<goal>" --audience "<who>" --fact "<fact>" --channel email --wait --json
-audienti tools runs show <trun_id> --json
-audienti tools runs results <trun_id> --json
-audienti network list --cookie <scok_id> --kind connection --json
-audienti tools linkedin-review --url https://www.linkedin.com/in/example --icp <icp_id> --json
-audienti tools linkedin-review reports --json
-audienti tools linkedin-review show <rprt_id> --json
-audienti tools linkedin-review status <rprt_id> --json
-audienti writer test-run <prsp_id>
-audienti writer test-run <prsp_id> --mode report --report <rprt_id>
-audienti writer test-run <prsp_id> --mode step --branch no-accept --step 3 --report <rprt_id>
-audienti writer test-run <prsp_id> --mode step --branch no-accept --step 3 --report <rprt_id> --no-wait
-audienti writer test-run show <prsp_id> <rprt_id>
-```
-
-## Prospect Account Moves
-
-Use `audienti prospects move-account` only to transfer one prospect and its
-account-scoped history, not to copy it. `--account` is the source account and
-`--target-account` is the destination. The authenticated user must administer
-both accounts.
-
-Start with a preview and inspect `eligible`, `blockers`, `mappings`,
-`dispositions`, and `expected_state`:
-
-```bash
-audienti prospects move-account <prsp_id> \
-  --account <source_acct_id> \
-  --target-account <target_acct_id> \
-  --assigned-user <target_account_user_id|me> \
-  --target-motion <target_motn_id> \
-  --target-list <target_list_id> \
-  --json
-```
-
-Omit mappings that were not explicitly chosen; never infer a target motion,
-list, agent, or research mapping by name. Apply only after the preview is
-eligible and the user authorizes the move:
-
-```bash
-audienti prospects move-account <prsp_id> \
-  --account <source_acct_id> \
-  --target-account <target_acct_id> \
-  --assigned-user <target_account_user_id|me> \
-  --target-motion <target_motn_id> \
-  --target-list <target_list_id> \
-  --apply \
-  --json
-```
-
-With `--apply`, the CLI performs a fresh preview and submits that response's
-`manifest_digest`; it does not reuse an older preview. Treat a stale manifest,
-any blocker, or any failed response as not applied, then inspect current source
-and target state before retrying.
-
-## Account-User Automation Safety
-
-`audienti users automation show <account_user_id|me>` resolves one connected
-account through the selected account, account user, and LinkedIn platform. Use
-per-command `--account` for administrative inspection without changing the
-saved default. Fail closed on API ambiguity or missing access; do not substitute
-another connected account.
-
-Automation updates are preview-first:
-
-```bash
-audienti users automation show 136 --platform linkedin --json --account acct_example
-audienti users automation update 136 --payload automation-controls.json --json --account acct_example
-audienti users automation update 136 --payload automation-controls.json --apply --json --account acct_example
-audienti users automation show 136 --platform linkedin --json --account acct_example
-```
-
-The payload object accepts `automation_controls`, `action_limits`, and
-`visibility_ramp`. Action-limit keys are `profile_view`, `follow`, `like`,
-`invite`, `message`, `comment`, and aggregate `visibility`; each action limit
-may provide `hourly`, `daily`, and `weekly`. `follow` covers follow/unfollow,
-`like` covers like/unlike, and `message` covers messages/InMail. A ramp accepts
-`enabled`, `starting_daily_limit`, `weekly_increment`, and optional
-`started_at`.
-
-The CLI wraps the file as `{ automation: { ...payload, platform: "linkedin",
-apply: false|true } }`; file values cannot override the command's platform or
-apply decision. Omitted settings are preserved by the server. Use unchanged
-JSON output to compare current, before, and after snapshots, including policy
-source, schedule/timezone, configured/default/effective limits, used and
-remaining capacity, binding limits, preview/applied state, and applied audit id.
-
-For a new account, keep contact and writing controls disabled, enable risk
-cooldown, and bound `visibility` to the authorized active-day warm-up level.
-Never infer that `ready: true`, paused motions, or prepared queue work authorizes
-provider execution.
-
-List routing-rule create and update commands accept the same normalized
-condition and action data as the list UI. Location and company_location labels
-must resolve to a known geography or the request returns 422. Inspect the
-ordered rules first, use `audienti lists routing-rules help` for the payload
-contract, and treat `apply` as an asynchronous relaunch: it queues the existing
-routing job and does not mean every list member has finished routing.
-
-Motion start and end dates are optional lifecycle controls. A due start can
-activate a configured preparing or paused motion; an end date is the final
-active day and pauses the motion afterward. `--maximum-company-count` caps
-durable company admissions only: research and people discovery for admitted
-companies, prospect intake, and automation continue. Use `none` to clear any
-of these settings.
-
-`audienti writer test-run <prsp_id>` starts a report-backed writing session and
-builds the campaign timeline without drafting every message. The printed
-`Report: rprt_...` id is the session handle. Pass `--report <rprt_id>` when
-drafting every message with `--mode report` or one selected row with
-`--mode step`; the server report supplies prior drafted rows as context. Use
-`--timeout-seconds <n>` for longer waits, or `--no-wait` to launch and return
-immediately. Use `writer test-run show` with the report id to fetch the
-completed report later.
-
-## Standalone Tools Versus Prospect Tools
-
-- For an email lookup with no prospect, use `audienti tools email-find`. `audienti tools get email` imports a prospect into the account; use it only when that is wanted.
-- `tools email-find`, `linkedin-enrich`, `signals-find` and `write` return a run id immediately. Pass `--wait --json` to get results in one call, or poll `tools runs show <trun_id>` and read `tools runs results <trun_id>`. Nothing is sent and no prospects or experiments are created.
-- Pass `--request-key <key>` when retrying a submission; the same key and input return the same run.
-- `audienti network list|export` reads only the requester's own connected account's saved network. A 404 means the requester is not that account's owner. Coverage `unsupported_capture` or `not_yet_observed` is not zero.
-
-Create a child workspace with `audienti accounts create --name <name> --parent <name-or-id> [--json]`. The parent can be a visible name, unique name fragment, numeric ID, or prefixed ID. You must administer a root team account. All parent admins receive access to the child; ordinary members do not. Ambiguous names show matching IDs and stop. A duplicate child name under the same parent fails clearly. The response includes the new account ID. Creation keeps your selected account unchanged: use `audienti accounts select <new_acct_id>` or `--account <new_acct_id>` before creating a motion there.
+Use `audienti skills show audienti --json` for the exact version, digest and JSON
+schemas. The local MCP tools expose the same helpers. An HTTP-only agent without
+local execution cannot run these helpers: report that capability gap rather than
+claiming to have executed them. Compatible research tools already available to you
+can supply inputs; using Audienti's paid tools is optional.
+
+## Preserve the boundary
+
+- Search saved Prospects and Profiles before purchasing fresh data.
+  `profiles.enrich` accepts a known LinkedIn URL or authorized saved Profile ID,
+  saves the result and returns its current canonical Prospect and profile page.
+  Complete eligible cached data is reused; request `refresh` only deliberately.
+- Execute each search, retrieval, contact lookup or optional AI decision explicitly.
+  Helpers return inputs for you to use; they never continue a research chain.
+- A candidate rank is not an identity match, qualification, contact permission or
+  assurance that a source is trustworthy. `trusted_source` is a legacy V10 ranking
+  feature only. Submit attributed facts and citations to the CRM's shared owners.
+- Reuse the returned Prospect/Profile IDs. Do not manufacture merge authority,
+  provider verification, or image-match evidence. The CRM owns final identity
+  reconciliation. If the installed API lacks the required guarded operation, keep
+  the evidence and report the missing capability; do not set foreign keys yourself.
+- Recover an unknown paid outcome using the existing request/operation ID and run
+  history before retrying. A new request ID is new work, not a recovery mechanism.
+  Do not bypass a zero-credit refusal with another alias or credential.
+- Persist requested relevant evidence even when a candidate fails an experiment's
+  fit criteria. Separate source facts from your interpretation and cite both.
+  Include this skill's identity/version on supported evidence and assessment writes.
+- Profile research does not authorize a message, follow, contact purchase or change
+  to an approval. Use the customer's instructions and current server permissions.
+
+Return canonical records read back from the selected workspace, evidence collected,
+profiles matched or still unresolved, operation IDs for interrupted work, and the
+specific remaining evidence/capability gap. Do not claim a complete enrichment or
+expansion when only search results or advisory rankings are available.
+
+For field coverage use `profile-completeness` with supplied field states. For observed
+bio/website links and mentions use `profile-evidence`. Both run locally; neither
+chooses a paid call or asserts an identity. See [helper contracts](references/helpers.md).