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

package/skills/getting-started/SKILL.md

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

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

@@ -4,12 +4,24 @@ An audience is a set of structured filters plus one smart rule. Discovery and fi
 read the structured filters first, so put everything you can into them. Free text is
 only for the one test the filters cannot express.
 
+An audience says **who** the buyer is: facts about the company and the person that stay
+true for months. It never says **why now**. Hiring, funding, a new leader, a tool
+change, a post or an intent to buy are events, and events are campaign signals (see
+section 5). An audience with an event in it matches almost no one.
+
 ## 1. Pick one buyer lane
 
 One audience describes one kind of buyer: one function at one seniority band, in one
 kind of company. If the offer sells to two different buyers (for example finance and
 operations), draft two audiences and two campaigns. Do not mix lanes in one audience.
 
+Every audience sets `person.functions`. Seniority alone is not a lane: "all VPs" reaches
+the VP of Finance and the VP of Engineering as well as the buyer. Pick the function that
+owns the problem the offer solves and signs for it. For example, an outbound or SDR
+agency sells to whoever owns pipeline: Sales, and Marketing when marketing owns
+pipeline. Add `currentTitles` such as "VP of Sales" or "Chief Revenue Officer" when the
+function is still too wide.
+
 ## 2. Resolve every value with `audience options`
 
 Never type a value from memory. Look each one up and copy the `providerId` and `name`
@@ -24,8 +36,19 @@ audienti audience options --kind functions --q finance
 audienti audience options --kind titles --q "head of finance"
 ```
 
-Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorities`,
-`functions`, `titles`. Over MCP, use `audience_options` with the same `kind`.
+Kinds: `industries`, `sizes`, `types`, `locations`, `seniorities`, `functions`, `titles`.
+Over MCP, use `audience_options` with the same `kind`. Name industries one by one: new
+audiences cannot add industry groups, because a group's industries do not match its name.
+
+- Search ignores case. Several terms in one query ("freight and logistics", or a
+  comma-separated list) return the matches for each term.
+- An industry search matches the industry's own name, not the group it sits in:
+  "logistics" returns the logistics industries, not airlines or rail.
+- Company size comes in LinkedIn's bands. A range in `--q` ("100 to 1000", "500+",
+  "under 50") returns every band it overlaps. Add all of them to `company.sizes`.
+- `functions` is LinkedIn's fixed list of 26 job functions. It needs no Sales Navigator
+  account.
+- A title that is not in the list can be saved as typed, without a `providerId`.
 
 ## 3. Fill the template
 
@@ -33,7 +56,7 @@ Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorit
 {
   "name": "Heads of finance, UK logistics, 51-500 staff",
   "company": {
-    "industries": [{ "providerId": "ID", "name": "Transportation, Logistics, Supply Chain and Storage" }],
+    "industries": [{ "providerId": "ID", "name": "Logistics and Supply Chain" }, { "providerId": "ID", "name": "Package/Freight Delivery" }],
     "sizes": [{ "providerId": "ID", "name": "51-200" }, { "providerId": "ID", "name": "201-500" }],
     "locations": [{ "providerId": "ID", "name": "United Kingdom" }]
   },
@@ -45,11 +68,14 @@ Kinds: `industries`, `industry_groups`, `sizes`, `types`, `locations`, `seniorit
   },
   "seniorityMatchMode": "at_least",
   "textCriteria": "The company runs its own truck or freight fleet.",
-  "notes": "Region and size inferred from the owner's last 20 sent emails; owner confirmed in Operator."
+  "notes": "Region and size inferred from the user's last 20 sent emails; user confirmed in Operator."
 }
 ```
 
 - `seniorityMatchMode: "at_least"` matches the chosen seniority and higher.
+- After saving, `audienti audience summary --audience ID` returns `sizes`: about how many
+  people the included industries, functions and regions reach, against the 1,000-person
+  minimum. Under 1,000, widen the industries, functions or regions.
 - Use `negative: true` on a value to exclude it (for example a competitor's industry).
 - `currentTitles` narrows the lane; keep it to the titles that buy, at most a few.
 
@@ -67,12 +93,51 @@ Good:
 Not allowed in the smart rule:
 
 - Provenance: "inferred from…", "based on the website", "found in sent email".
-- Hedges or open questions: "owner to confirm", "probably", "maybe", "TBD".
-- Values the filters already hold (industry, size, region, seniority, title).
+- Hedges or open questions: "user to confirm", "probably", "maybe", "TBD".
+- Values the filters already hold (industry, size, region, seniority, function, title).
 - More than one test joined with "and" or "or". Pick the one that matters most.
+- Events, timing or intent: "is hiring…", "recently raised…", "is considering…",
+  "is looking for…", "just changed…". These are campaign signals (section 5).
 
-Put provenance in `notes`. Put open questions to the owner in Operator with
+Put provenance in `notes`. Put open questions to the user in Operator with
 `audienti ask`, not in the audience.
 
+Saving refuses a smart rule that states the company's size or an event, and says where
+it belongs: size in `company.sizes`, events in a campaign signal.
+
 Check the rule before you save: `audienti audience improve --text "RULE"` returns a
 suggested rewrite when the rule is vague.
+
+## 5. Audience or signal?
+
+Ask of each condition: would it still be true of this company in six months?
+
+| Condition | Where it goes |
+| --- | --- |
+| Sells B2B software; 51 to 500 staff; based in the US | Audience filters |
+| Sells to hospitals; runs its own freight fleet | Audience smart rule |
+| Owns pipeline or revenue (VP of Sales, CRO) | Audience `person.functions`, `seniorities`, `currentTitles` |
+| Is hiring SDRs; is considering an outbound agency | Campaign signal |
+| Raised a round this quarter; new VP of Sales in the last 90 days | Campaign signal |
+
+A signal lives in the campaign's `signals` array. A `research` signal is a yes/no
+question a researcher answers from public evidence such as job posts, news or the
+company's site:
+
+```json
+{
+  "signalMatch": "any",
+  "signals": [{
+    "id": "UUID",
+    "kind": "research",
+    "scope": "company",
+    "question": "Is the company hiring SDRs or BDRs, or looking for an outbound agency?",
+    "expected": true,
+    "details": "Open SDR or BDR job posts, or a post asking for agency recommendations, in the last 90 days."
+  }]
+}
+```
+
+`signalMatch: "any"` lets a company qualify on any one signal; `"all"` needs every one.
+A signal narrows who is worth contacting now; it never replaces the audience, so the
+company and person still have to fit the audience.