@trydreamstate/cli 1.3.1 → 1.3.3

package/README.md

@@ -37,7 +37,7 @@ dreamstate workspaces use <id|slug>
 dreamstate packs list --workspace <id|slug>
 dreamstate packs list
 dreamstate packs get <pack_id>
-dreamstate commands search "create a workbook and add rows"
+dreamstate commands search "create a workbook and add rows"   # CLI commands first, then matching capabilities
 dreamstate tools get <capability_id>
 dreamstate tools search --goal "create a workbook" --limit 50 --toolset tables
 dreamstate tools run tables.workbooks.create --params '{"name":"Pipeline"}' --mode live --approved
@@ -49,24 +49,37 @@ Credentials are stored as JSON `{"token", "workspace"}` (mode `0600`); the singl
 
 `login` prints approval URL plus confirmation code. Approval page shows same code, then CLI stores granted credential with mode `0600` and prints `whoami`. Default API is `https://api.trydreamstate.com/api/v1`; `DREAMSTATE_API_URL` overrides it. `whoami` and `auth whoami` are aliases. `auth whoami` prints API `registry_hash` unchanged. `packs list`, `packs get`, and `commands search` read authenticated API catalog at request time.
 
-`--json` is output alias for `--json-output` when used without a value. `tools run --json <body>`, `runs list --json <query>`, and `runs cancel --json <body>` keep JSON input meaning. `tools run --mode smoke_test|dry_run|live` sends canonical execution mode; `--dry-run` aliases `--mode dry_run`. `--approved` authorizes request only, never enters request body. `tools search --limit <n>` and `--toolset <pack_id>` send canonical discovery query fields.
+`--json` is output alias for `--json-output` when used without a value. `tools run --json <body>`, `runs list --json <query>`, and `runs cancel --json <body>` keep JSON input meaning. `tools run --mode smoke_test|dry_run|live` sends canonical execution mode; `--dry-run` aliases `--mode dry_run`. Consent text and limits come only from `apps/backend/src/services/mcp/consentRule.json`; generated plugin guidance reads that file. `tools search --limit <n>` and `--toolset <pack_id>` send canonical discovery query fields.
 
 ## Stream contract and exit codes
 
-Every invocation writes one JSON envelope to stdout. Pipe stdout to `jq`; progress, warnings, confirmation codes, and version-skew notices use stderr. Error envelopes have `ok: false`, `executed: false`, `error`, and `meta.exit_code`; usage errors use same envelope.
-
-| Exit code | Meaning |
-| --- | --- |
-| 0 | Success |
-| 2 | Usage error |
-| 3 | Authentication failure |
-| 4 | Not found |
-| 5 | Server failure |
-| 6 | Rate limited |
-| 7 | Approval required |
-| 8 | Request timeout |
-| 9 | Server refusal (HTTP 4xx) |
-| 10 | Transport failure |
+Every invocation writes one JSON envelope to stdout. Pipe stdout to `jq`; progress, warnings, confirmation codes, and version-skew notices use stderr. Error envelopes have canonical `ToolEnvelope` shape: `ok: false`, `error` (`code`, `message`, and the server's `retryable`, `repair`, `details` unchanged) and `meta`. The server's own message is never reworded; guidance the CLI adds itself rides in `error.details.cli_hint`. `meta` keeps server fields (`trace_id`, `server_version`, `minimum_cli_version`, `release_sha`) plus request receipts (`retry_after`, `idempotency_key`). Process exit status stays outside JSON. Usage errors use the same envelope.
+
+`CLI_EXIT` in `src/errors.ts` is sole exit-code table. `dreamstate --help` prints its stable meanings. Exit 7 covers server approval, consent, spend, quote and mode gates; exit 9 covers other refusals.
+
+CLI-local error codes (raised by the CLI itself, never by the server): `network_error`, `request_timeout`, `invalid_response`, `invalid_tool_turn_token`, `invalid_web_url`, `web_url_unavailable`, `plugin_install_failed`, `skills_authentication_required`. Every other code in a CLI envelope is a server code.
+
+## Release skew and updates
+
+The CLI sends `X-Dreamstate-Client-Version` on every request. The server stamps `server_version`, `minimum_cli_version` and `release_sha` on every response, in `meta` and in `X-Dreamstate-Server-Version` / `-Minimum-Cli-Version` / `-Release-Sha` headers; the CLI reads both, on success and on error. A server that refuses this CLI as too old answers HTTP 426 `cli_update_required` before running anything; the CLI exits 8 and prints `npm install -g @trydreamstate/cli@latest`. A CLI that is only behind the server still runs and prints a warning on stderr. `dreamstate status` reports `cli_version`, `server_version`, `release_sha`, `minimum_cli_version` and `skew` (`compatible`, `cli_behind_server`, `cli_below_minimum`, or `unknown` when the server publishes nothing), and exits 8 when below the minimum.
+
+## Idempotency
+
+A live write gets a random key for one attempt. CLI persists that key by request digest in its config directory only while result is unknown or transient; retrying that pending request reuses it. Success or a definitive refusal clears it, so a later identical command gets a new key instead of replaying an old result. It is printed as `meta.idempotency_key`. After a timeout, read target back first; only if effect is absent repeat identical call once with first key. `--idempotency-key <key>` supplies a key explicitly and is used unchanged. Dry runs carry no key. `runs cancel` follows same attempt rule.
+
+## Sequences and workflows
+
+`sequences <verb>` and `workflows <verb>` run through the same gate as `tools run`: the same `--dry-run`/`--live`/`--mode`, `--approved`, `--approval-id`, `--quote-hash`, `--max-credits`, `--approved-effect-unknown`, `--turn-token`, `--idempotency-key`, turn cache and quote retry. A verb sends no mode unless you give one (the server answers `mode_required`, exit 7). Flag values are converted to the types the capability's live input schema declares, so `--max-new-enrollments-per-day 40` is sent as the number 40. `commands search <term>` returns real CLI commands (and the capability each runs) from the CLI's own tables, plus matching catalog capabilities when you are signed in. `tools run` refuses a capability the contract does not publish for the CLI (`unsupported_capability`, exit 9). The CLI has no `--agent-session-id`: that field selects the in-app Architect surface and the server refuses it for every other caller, so a request body that carries `agent_session_id` is rejected locally (exit 2).
+
+## Tables import
+
+`dreamstate tables import --table-id <uuid> --file <path>` uploads the file: it opens an upload (`tables.table_sources.csv_upload_create`), chooses the column mapping, stages rows in chunks of at most 5,000, attaches the source and lands rows until done, the same lifecycle the web app runs. CSV, JSON, JSONL and XLSX are read locally; nothing is uploaded by `--preview`. Pick the identity column with `--upsert-key <header>` (otherwise the strongest mapped field: email, linkedin_url, external_id; domain for `--row-kind company`). Every step is replay-safe: re-running the same command resumes where it stopped. The import always runs to completion in the command's own process; there is no background mode. `--background`, which servers before 1.3.3 added to the command text they generate, is refused with a usage error (exit 2) that says to run the command without it.
+
+`runs resume` was removed: the server has no generic run resume. A table run checkpoint resumes with `dreamstate tools run tables.table_runs.resume`.
+
+## Skills
+
+`skills install` writes every hosted skill with its supporting pages (`--copy` copies the whole skill directory, not only `SKILL.md`), and skips an agent that already loads Dreamstate skills from the plugin. `skills doctor` compares each installed skill's content stamp with the live skill (text, revision and supporting pages), reports `missing`, `extra` and `stale`, and prints the command that refreshes them; age alone no longer decides.
 
 Build and test:
 

package/agent-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamstate",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Dreamstate for AI agents: build workbooks of companies and people, run LinkedIn and email sequences, answer replies, post to LinkedIn and X, and manage your CRM from your coding agent.",
   "author": {
     "name": "Dreamstate",

package/agent-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamstate",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Dreamstate for AI agents: build workbooks of companies and people, run LinkedIn and email sequences, answer replies, post to LinkedIn and X, and manage your CRM from your coding agent.",
   "author": {
     "name": "Dreamstate",
@@ -31,8 +31,11 @@
       "Write"
     ],
     "websiteURL": "https://trydreamstate.com",
+    "supportURL": "https://trydreamstate.com/support",
     "privacyPolicyURL": "https://trydreamstate.com/privacy",
     "termsOfServiceURL": "https://trydreamstate.com/terms",
+    "composerIcon": "./assets/logo.png",
+    "logo": "./assets/logo.png",
     "defaultPrompt": [
       "Get me started with Dreamstate",
       "Build a list of companies hiring SDRs",

package/agent-plugin/hooks/approve-readonly.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Claude Code PreToolUse hook for the Dreamstate plugin. Generated by
+# packages/cli/scripts/build-agent-plugin.mjs; do not edit by hand.
+# Auto-allows 11 read-only Dreamstate MCP tools: whoami, packs_list, packs_get, packs_route, skills_list, skills_get, tools_search, tools_get, runs_list, runs_get, runs_events.
+# Anything else, including tools_run and runs_cancel, falls through to the normal prompt.
+set -fu
+
+input="$(cat)"
+
+# Tool names look like mcp__plugin_dreamstate_dreamstate__whoami (installed plugin)
+# or mcp__dreamstate__whoami (server added by hand).
+if printf '%s' "$input" | grep -Eq '"tool_name"[[:space:]]*:[[:space:]]*"mcp__(plugin_dreamstate_dreamstate|dreamstate)__(whoami|packs_list|packs_get|packs_route|skills_list|skills_get|tools_search|tools_get|runs_list|runs_get|runs_events)"'; then
+  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Dreamstate plugin auto-allows read-only Dreamstate tools; runs and cancels still prompt"}}'
+fi
+exit 0

package/agent-plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Lets Claude Code call Dreamstate's read-only MCP tools without a permission prompt. Anything that writes or spends still prompts.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^mcp__(?:plugin_dreamstate_dreamstate|dreamstate)__(?:whoami|packs_list|packs_get|packs_route|skills_list|skills_get|tools_search|tools_get|runs_list|runs_get|runs_events)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/approve-readonly.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/agent-plugin/skills/crm/SKILL.md

@@ -3,7 +3,7 @@ name: crm
 description: "Maintain trustworthy customer and company records by separating stable facts, judgement, and time-bound activity; deduplicating only from strong identity evidence; and keeping pipeline tied to recent, evidenced work. Use it when the user needs to create, review, clean up, merge, enrich, or progress relationship records and deals. It does not rebuild source worksheets (list-building does), run outreach (outreach does), or replace a workflow with record cleanup (workflows does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # CRM
 
@@ -47,7 +47,7 @@ Keeping a CRM in step with the workspace usually has a blueprint: HubSpot, Attio
 
 ## Credit posture and sensitive effects
 
-Reads, duplicate review, and timeline inspection are free and come before enrichment. For paid enrichment, state target records, fields sought, expected coverage, credit estimate, and how result will be reviewed, then run with credits as consent. Do not enrich records merely to fill blanks.
+Reads, duplicate review, and timeline inspection are free and come before enrichment. For paid enrichment, state target records, fields sought, expected coverage, credit estimate, and how result will be reviewed, then run it under the paid-run consent rule: a run above the server's row or provider-spend limit needs the user's yes first. Do not enrich records merely to fill blanks.
 
 Merging records, changing consequential pipeline state, bulk edits, or any action that may hide human judgment needs evidence and exact change shown first. Then act when the user asked or confirms. Keep adjacent cleanup separate.
 

package/agent-plugin/skills/diagnostics/SKILL.md

@@ -3,7 +3,7 @@ name: diagnostics
 description: "Answer one operational question with evidence, such as where a cell value came from or why it is empty, which runs failed and which are safe to retry, why a sequence has not sent, or where credits went and how to spend less. Use it when something in a worksheet, sequence or workflow looks wrong, stuck, missing or expensive. It reads before it changes anything. It does not redesign lists, sequences or workflows, or tidy worksheet structure (worksheet-tidy does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Diagnostics
 

package/agent-plugin/skills/dreamstate/SKILL.md

@@ -5,12 +5,20 @@ description: "Use Dreamstate for sales and marketing work: finding companies or
 
 # Dreamstate
 
-Dreamstate is reached through its MCP server, which exposes thirteen tools.
+Dreamstate is reached through its MCP server. Its tool list is the door, not the catalog: a small set of controls reaches every capability.
+
+Prefer the narrower `dreamstate:*` skill for the job when one fits; `skills_get` returns the workspace's current copy of any skill.
 
 1. `whoami` names the user and the active workspace. If it lists several workspaces, confirm the right one before writing anything.
 2. `packs_route` maps a goal to a domain; `packs_get` returns that domain's capabilities and skills.
-3. Prefer the narrower `dreamstate:*` skill for the job when one fits. `skills_get` returns the workspace's current copy of any skill.
-4. `tools_search` with the goal, `tools_get` for the exact schema, then `tools_run` with `capability_id` and `params`. Read the schema every time.
-5. Follow long work with `runs_get`, `runs_events` and `runs_list`; `runs_cancel` stops a run.
+3. `tools_search` finds the capability for the goal; `tools_get` returns its exact input schema. Read the schema every time, never guess params from memory.
+4. `tools_run` runs it with `capability_id` and `params`. The gating inputs (`mode`, `max_credits`, `idempotency_key`, `quote_hash`, `max_rows`, `approved`) go on the run call itself, never inside `params`.
+5. `runs_get` follows long work; `runs_events` and `runs_list` read more of it and `runs_cancel` stops a run.
+
+Lists, finds, enrichments and signals happen only inside a workbook worksheet. Report only what tools returned.
+
+## Paid and outward-facing runs
+
+Anything that writes, spends credits or reaches a real person: run mode dry_run first, show the user the preview, the row count and the credit estimate, then run live with the quote_hash that dry_run returned, a max_credits ceiling and an idempotency_key. A live run that spends credits states max_rows, the number of rows the user asked for. A quote returned by a refused live call is only a price, never a confirmation.
 
-Lists, finds, enrichments and signals happen only inside a workbook worksheet. Anything that writes, spends credits or reaches a real person runs `dry_run` first, then live with `max_credits` and an `idempotency_key`. Report only what tools returned.
+A paid run above the server's row or provider-spend limit, or that turns on a recurring trigger, also needs the user's yes. Ask them, and only then send approved: true with the same quote_hash. You are asserting that you asked a person; never send it on your own.

package/agent-plugin/skills/first-win/SKILL.md

@@ -3,7 +3,7 @@ name: first-win
 description: "Run a short first session in a new workspace that confirms the user and workspace, builds or reads Company Context, creates one small sampled worksheet from the ideal customer, and suggests three next plays. Use it on a fresh workspace, when the user says \"get me started\", or when nothing has been built yet. It does not launch outreach, publish content or run anything at scale."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # First Win
 
@@ -40,7 +40,7 @@ Search the tool for each task. The search returns runnable schemas for its top h
 
 - No sequence starts, no posts published, no emails or DMs sent in this session.
 - No contact data lookups yet. They come after the user agrees the sample is the right people.
-- Warm reads and free preview come before every cold source run. Keep paid work to one bounded sample, or zero credits when warm rows suffice. Show coverage, preview and estimate, then run; there is no approval step to wait for.
+- Warm reads and free preview come before every cold source run. Keep paid work to one bounded sample, or zero credits when warm rows suffice. Show coverage, preview and estimate, then run the bounded sample from that preview. Anything larger follows the paid-run consent rule: the user's yes comes first when the server's row or provider-spend limit applies.
 - A missing account never blocks building. Build the worksheet, then name the account to connect.
 - Do not start a play on the user's behalf. Recommend one and let them pick.
 

package/agent-plugin/skills/inbox-replies/SKILL.md

@@ -3,7 +3,7 @@ name: inbox-replies
 description: "Triage and answer existing LinkedIn and email conversations, classify the latest inbound message, confirm the sequence stopped, and draft a reply grounded in the real thread and Company Context. Use it when someone replied, when the user wants to work through unanswered threads, or when a positive reply should move toward a meeting. It does not start new conversations with people who have not been contacted (the outreach skill does) or build automated reply handling (the workflows skill does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Inbox Replies
 

package/agent-plugin/skills/knowledge/SKILL.md

@@ -3,7 +3,7 @@ name: knowledge
 description: "Read and update what the workspace knows, across the knowledge digest, the workspace wiki, cited claims, and conflict-aware revisions."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Knowledge
 

package/agent-plugin/skills/linkedin-posts/SKILL.md

@@ -3,7 +3,7 @@ name: linkedin-posts
 description: "Write and revise LinkedIn posts that earn the click and the reply: the 210 character hook, structure and formatting, length by post type (story, list, case study, belief disruption, short, paragraph), specificity, the CTA close, and phrases to avoid. Use it for the copy of any post going to LinkedIn. It does not cover scheduling, publishing or automations (social does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # LinkedIn posts
 

package/agent-plugin/skills/linkedin-warm-signals/SKILL.md

@@ -3,7 +3,7 @@ name: linkedin-warm-signals
 description: "Warm people come from worksheet sources such as post engagers, followers, profile viewers and website visits. Judge worksheet rows against Required criteria, then build a capped warm sequence while protecting sender account. Use when user wants leads from LinkedIn presence or network-first motion. Does not cover cold lists from search (list-building does), writing posts (social does) or replying in existing threads (inbox-replies does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # LinkedIn Warm Signals
 
@@ -52,7 +52,7 @@ Search the tool for each task. The search returns runnable schemas for its top h
 
 - Name public engagement only; never write as if you watched someone.
 - Quote the captured comment or leave it out. Never invent what someone said.
-- Credits are the consent: show the estimate for paid research and contact data, then run.
+- Show the estimate for paid research and contact data, then run it under the paid-run consent rule: a run above the server's row or provider-spend limit needs the user's yes first.
 
 ## What to return
 

package/agent-plugin/skills/list-building/SKILL.md

@@ -3,7 +3,7 @@ name: list-building
 description: "Build a workbook of companies or people: as few sources as possible, people at companies through the employees enrichment fanned out to a second worksheet, one column per criterion marked Required or Nice to have, run conditions that skip rows already failing, an optional score, sample then scale, and honest coverage."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Workbook building
 
@@ -36,7 +36,7 @@ A list is worth contacting when every row would recognise itself in the reason y
 
 Before building, see if a blueprint does exactly what you need: its source is the right source for the hardest criterion and its columns are the chain you would build. If one does, install it, then configure its columns. If not, build your own workbook. Never install a near miss to have something to start from.
 
-When calling `workspace.blueprints.recommend`, pass `required_filters` for every user-stated hard constraint, using its closed filter enum. Read `unmet_required_filters`; do not install a recommendation that cannot apply every Required filter.
+When asking for a blueprint recommendation, pass `required_filters` for every user-stated hard constraint, using its closed filter enum. Read `unmet_required_filters`; do not install a recommendation that cannot apply every Required filter.
 
 For people engaging with competitor company posts, `signal-engaged-company-posts` exact match. Prefer it. It sets `max_posts_per_company=2`, `max_engagers_per_post=25`, `sample_size=25`, then excludes employees of selected companies in first paid qualification. Attach the company engager source directly only when a custom workbook is needed: send `company_urls` as literal string array, keep same caps, add employee-exclusion qualification before outreach.
 
@@ -81,7 +81,7 @@ Disqualifiers and the fit score:
 3. **Hardest criterion first.** Select source that natively owns every Required company fact before convenient connected-account search. Search resolved executable definitions for ready people-source definitions and their exact input contracts. Select the returned hard-firmographic people source when it owns person location, company size, and industry, then attach that source. If no resolved people source owns hard company facts, source companies first with the resolved company search using exact company size and industry, then fan out people from qualified companies. The resolved LinkedIn people search owns role and LinkedIn facets but does not declare company headcount. Never replace missing size or industry with `SaaS` keyword. Use LinkedIn source only when declared facets cover every Required pre-spend fact, or after company-first qualification. If LinkedIn provider contract later exposes company headcount, use declared facet; never claim it exists before contract says so.
 4. **Free source preview, then configure chain.** Call the zero-credit source preview first when available. Read named rows against every criterion. Aim for more than half right at source. If source can filter failing criterion, fix input and preview again; if it returns nothing, find over-narrow input. If source cannot express hardest criterion, switch source now, before workbook attachment or spend. After free preview, build complete Required qualification, 0 to 100 fit-score, and work-email preview chain with run conditions.
 5. **Paid sample only after chain exists.** Run bounded paid source sample, then run configured chain on sample and read cells. Fix and rerun until correct. Follow every run to end.
-6. **Audit.** Report qualified of total and cost per qualified row. Under about 30 percent qualified, name the Required criterion failing most and propose one change; under about 10 percent, propose a different source. Then ask how far to grow the list.
+6. **Audit.** When zero rows qualify and near misses show stated-role equivalents, widen once inside stated intent, resample, and say what you widened. Report qualified of total and cost per qualified row. Under about 30 percent qualified, name the Required criterion failing most and propose one change; under about 10 percent, propose a different source. Then ask how far to grow the list.
 7. **Scale the same source** in bounded batches toward the target, running paid columns only on rows their conditions admit. Only qualified rows count. Call a source exhausted only when a run returned fewer rows than it asked for.
 
 To grow an existing list, rerun its source with a higher target and widen only with levers that keep every Required criterion; report near matches separately.
@@ -94,7 +94,7 @@ To grow an existing list, rerun its source with a higher target and widen only w
 
 ## Gates
 
-- A paid run's ceiling is its preview's maximum; credits within it are already consented.
+- A paid run's ceiling is its preview's maximum. Run it under the paid-run consent rule: a run above the server's row or provider-spend limit needs the user's yes first, and the server refuses it without one.
 - A refusal names what to fix: fix that input and retry, three times at most, then report it.
 - A missing account blocks running, never building: build everything and say what to connect.
 - Never invent a count. Never delete rows unless the user asks.

package/agent-plugin/skills/outreach/SKILL.md

@@ -3,7 +3,7 @@ name: outreach
 description: "Build a multi-channel sequence and enroll a workbook into it: preview one real message first, fixed scaffold with small personalized slots, channel steps with the wait inside each step, column filters decide who enrolls, paced sends."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Sequence building
 

package/agent-plugin/skills/outreach/steps-and-timing.md

@@ -1,6 +1,6 @@
 # Steps and timing
 
-Authorable steps are an email, a LinkedIn connection request, a LinkedIn message and a Slack message; read the step schema for the exact shape. There is no standalone wait step: set the delay on the sending step that follows the earlier touch. A LinkedIn message never sends an invite. To reach someone who is not connected, put a connection request step first (after a profile view when there is one), then the message steps; a message waits until the request is accepted. Leave the connection request note empty by default: a blank invitation is accepted more often and the message after acceptance does the talking. Write a note only when the user asks for one. Skip the connection request only when the audience is already connected (first-degree) or an earlier step waits for the person to connect. Fetching the profile happens on its own, so never add fetch-profile steps. Timing is part of a sending step.
+Authorable steps are the ids `sequence.sequences.step_options` returns. That list is `canonicalSequencePaletteOptionIds()` in `packages/types/src/canonicalSequences.ts` (`CANONICAL_SEQUENCE_STEP_KINDS`, `CANONICAL_SEQUENCE_ACTIONS`, `CANONICAL_SEQUENCE_LINKEDIN_ACTIONS`, user-pickable nodes only). Read the schema for the exact shape, including whether a delay is its own step (`canonicalSequenceStepDelaySecondsSchema`). Do not invent a step the palette does not list. A LinkedIn message never sends an invite. To reach someone who is not connected, put a connection request step first when the palette offers one, then the message steps; a message waits until the request is accepted. Leave the connection request note empty by default: a blank invitation is accepted more often and the message after acceptance does the talking. Write a note only when the user asks for one. Skip the connection request only when the audience is already connected (first-degree) or an earlier step waits for the person to connect.
 
 Typical cadence: three to five touches over two to three weeks, two to five days apart, mixing channels when both are available. An email follow-up reads best as a reply in the same thread. Put the strongest message first, and make the last touch an easy way to close the loop.
 

package/agent-plugin/skills/plays/SKILL.md

@@ -3,7 +3,7 @@ name: plays
 description: "Recommend and run one named, proven go-to-market play when the user asks what to do next, picking by stage and what the workspace already has, and stating prerequisites, credit estimate and checkpoints before starting. Use it for \"what should I do\", \"how do I get leads\", \"help me start outbound or content\", or a weekly review. It does not replace the skills each step uses (knowledge, list-building, outreach, social, writing, visibility, workflows)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Plays
 
@@ -26,7 +26,7 @@ A play has no pack of its own. It routes across packs: brain for Company Context
 ## Practice
 
 1. **Read the workspace.** Search first for three free, state-aware blueprint recommendations. That read uses registry requirements plus connected LinkedIn accounts, mailboxes, worksheets and credit posture. For one candidate, read the exact describe result the recommendation names next. Then read Company Context (Ideal Customer, Offer, Tone of Voice), connected LinkedIn and X accounts, existing worksheets, sequences, drafts and analytics freshness. Reuse what exists; never rebuild a worksheet or sequence that already does the job.
-2. **State the plan.** Steps in order, what each produces, the credit estimate for paid steps, and the checkpoints where the user sees real output. Credits are the consent: state the estimate, then proceed.
+2. **State the plan.** Steps in order, what each produces, the credit estimate for paid steps, and the checkpoints where the user sees real output. State the estimate, then proceed under the paid-run consent rule: a run above the server's row or provider-spend limit needs the user's yes first.
 3. **Run it step by step,** loading each step's skill with skills_get. Build everything buildable even when an account is missing, then name what to connect.
 4. **Show before it leaves.** Final copy of every message or post before anything sends or publishes, and say so before switching on any daily schedule.
 5. **Close with the leading metric** and when to check it.

package/agent-plugin/skills/reddit-posts/SKILL.md

@@ -3,7 +3,7 @@ name: reddit-posts
 description: "Draft Reddit posts the user posts themselves: subreddit choice and rules, the title, a value first body, disclosure, post types (success story, guide, resource list, problem solving, behind the scenes, question), and what gets posts removed. Use it for the copy of any Reddit draft. It does not cover scheduling or automations (social does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Reddit posts
 

package/agent-plugin/skills/skill-authoring/SKILL.md

@@ -3,7 +3,7 @@ name: skill-authoring
 description: "Read, edit and create this workspace's skills, the editable Markdown playbooks agents and people follow, keeping each one short, revision safe and in the workspace's own words. Use it when the user wants to change how a skill works, capture a repeatable practice as a new skill, or fix a skill that reports issues. It does not change what an agent is allowed to do (a skill grants nothing) and does not edit Company Context pages (knowledge does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Skill Authoring
 

package/agent-plugin/skills/social/SKILL.md

@@ -3,7 +3,7 @@ name: social
 description: "Own a short-form social post for its whole life across connected channels. Read the channel registry and learned brand voice, draft and revise, submit for review, approve, schedule or reschedule, publish now, unschedule, and archive."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Social
 
@@ -58,7 +58,7 @@ These automations run only when the post publishes. Setting them up sends nothin
 
 ## Schedule and publish
 
-Scheduling is separate from drafting: schedule only when the user asks. Publishing is outward delivery. Decide by judgment whether to confirm first; when the user already asked to publish, publish. There is no system approval step.
+Scheduling is separate from drafting: schedule only when the user asks. Publishing is outward delivery. Decide by judgment whether to confirm first; when the user already asked to publish, publish. If the server refuses and names an approval it needs (a governed workspace's reviewer pipeline, or consent for a paid or recurring run), get that approval from the person; never invent one.
 
 Resolve one explicit IANA timezone. Convert requested local time once into one timestamp for every channel. Never reinterpret “morning” per channel.
 

package/agent-plugin/skills/visibility/SKILL.md

@@ -3,7 +3,7 @@ name: visibility
 description: "Get found by search engines and answer engines. Pick the query set, gather crawl, index, mention and citation evidence, fix pages, then measure the change."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Visibility
 
@@ -25,7 +25,7 @@ Improve discoverability and qualified organic traffic in traditional search and
 actions: []
 ```
 
-Read measured evidence, propose prioritized changes, and treat paid or asynchronous measurement as bounded work: show scope and cost, then run it with credits as consent. Before a sensitive change, show the evidence and the exact change. Knowledge owns business facts; writing owns content changes.
+Read measured evidence, propose prioritized changes, and treat paid or asynchronous measurement as bounded work: show scope and cost, then run it under the paid-run consent rule: a run above the server's row or provider-spend limit needs the user's yes first. Before a sensitive change, show the evidence and the exact change. Knowledge owns business facts; writing owns content changes.
 
 ## Loop
 

package/agent-plugin/skills/workflows/SKILL.md

@@ -3,7 +3,7 @@ name: workflows
 description: "Best practices for building and running automations that are not outreach sequences: frame the job, smallest graph, validate after every change, runtime inputs, safe recovery of failed runs."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Workflows
 
@@ -19,7 +19,7 @@ Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabiliti
 Best practices for building and running automations. The workflow pack lists the tools and their exact inputs; this skill is how to use them well. Outreach cadences to people are sequences, covered by the outreach skill. Everything else is a workflow.
 
 1. Build new unless asked. A new request gets a new automation built from scratch. When the user names an existing one to change, resolve that name among existing automations by listing workflows and sequences with that name as the search text, then change the match. A named thing that is not a workflow or sequence may be a task, a record or a worksheet; check those only after automations come back empty. A step inside a workflow, such as a task step, is edited in that workflow's graph, not in the task list.
-1a. "Enroll these in a workflow" is never a missing input. Use a workflow whose table trigger is the worksheet the user is looking at, or one they named; otherwise build a new draft for that worksheet (worksheet rows trigger plus fitting steps, a follow-up task per person by default), validate, and enroll. Never ask which workflow.
+1a. "Enroll these in a workflow" is never a missing input. Use a workflow whose table trigger is the worksheet the user is looking at, or one they named; otherwise build a new draft for that worksheet (worksheet rows trigger plus fitting steps, a follow-up task per person by default), validate, and enroll. Never ask which workflow. Filters on any worksheet column narrow who enrolls; with no filter every row enrolls. When the user said who should enroll, filter on the columns that hold it and report how many enrolled and how many were held back.
 2. Frame the job before building: what triggers it, who or what it acts on, what it changes, what it costs, when it stops and how often it runs.
 2a. Use a blueprint when one does exactly what you need; otherwise build your own. Workflow blueprints already cover common jobs: CRM syncs, list and do-not-contact syncs, routers, digests and signal monitors. List blueprints of the workflow kind, read what the closest one creates and what it still needs, install it, then adapt it to this request. Installing never needs answers or connections; the result names what is still to pick, so say that. Build from scratch only when no blueprint fits, and say which one came closest.
 3. Ask one clarifying question only when a required input is missing. Otherwise build with sensible defaults and say what you assumed.
@@ -31,7 +31,7 @@ Best practices for building and running automations. The workflow pack lists the
 8a. Building never waits on rows. A worksheet trigger on an empty or still-filling worksheet is still a valid enrollment: build, validate and turn it on, and rows enroll as they land. Say it is waiting for rows, never stop because the worksheet is empty.
 8b. Use the row-created trigger when each new worksheet row must enter once. It watches future row arrivals on one worksheet, carries that row identity through the graph, and does not reuse or freeze a saved selection. Use the table trigger only when user wants a selected saved-view audience.
 8c. To tag or mark a triggering row, add the worksheet-row update step. Choose its column and either replace its value or append a value to its existing list. Do not ask user to export, reimport, or manually tag rows when workflow already has triggering row identity.
-9. Decide by judgment whether to confirm before activating something that sends or spends. When the user already asked for it, do it. There is no system approval step.
+9. Activating something that sends or spends follows the paid-run consent rule: preview first, then activate with the preview's quote and ceiling. When the user already asked for it and the run is within the server's row and provider-spend limits, do it. A larger run, or a recurring trigger, also needs the user's yes, and the server refuses it without one.
 10. Draft, published, active, running and finished are separate facts. Report only what the last result proves.
 
 ## Delete and archive

package/agent-plugin/skills/worksheet-tidy/SKILL.md

@@ -3,7 +3,7 @@ name: worksheet-tidy
 description: "Review a workbook worksheet's structure and values, including duplicate or overlapping columns, column order, types and formatting, columns to hide, criteria and run conditions that never vary, and suspicious values, then apply reversible fixes. Use it when a worksheet has grown messy, before sharing it, or before enrolling it into a sequence. It does not merge CRM records across the workspace, rebuild the list's source (list-building does) or explain failed runs (diagnostics does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Worksheet Tidy
 

package/agent-plugin/skills/writing/SKILL.md

@@ -3,7 +3,7 @@ name: writing
 description: "Draft, revise and publish articles and landing copy grounded in workspace context and a target query."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # Writing
 

package/agent-plugin/skills/x-posts/SKILL.md

@@ -3,7 +3,7 @@ name: x-posts
 description: "Write and revise X posts and threads: the first line, single post versus thread, weighted length and Premium limits, thread structure, post types, replies and links, and phrases to avoid. Use it for the copy of any post going to X. It does not cover scheduling, publishing or automations (social does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own. If the server asks you to sign in, approve it in the browser.
 
 # X posts
 

package/dist/agentGuidance.generated.json

@@ -0,0 +1,35 @@
+{
+    "generated_by": "packages/cli/scripts/build-agent-plugin.mjs from apps/backend/src/services/mcp/consentRule.json; do not edit by hand",
+    "consent": {
+        "summary": "Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. A larger paid run also needs the user's yes before you send approved: true; never send it on your own.",
+        "paid_run": "Anything that writes, spends credits or reaches a real person: run mode dry_run first, show the user the preview, the row count and the credit estimate, then run live with the quote_hash that dry_run returned, a max_credits ceiling and an idempotency_key. A live run that spends credits states max_rows, the number of rows the user asked for. A quote returned by a refused live call is only a price, never a confirmation.",
+        "human_approval": "A paid run above the server's row or provider-spend limit, or that turns on a recurring trigger, also needs the user's yes. Ask them, and only then send approved: true with the same quote_hash. You are asserting that you asked a person; never send it on your own."
+    },
+    "router_steps": [
+        {
+            "mcp": "whoami",
+            "cli": "dreamstate whoami --json",
+            "text": "names the user and the active workspace. If it lists several workspaces, confirm the right one before writing anything."
+        },
+        {
+            "mcp": "packs_route",
+            "cli": "dreamstate packs route --goal \"<goal>\" --json",
+            "text": "maps a goal to a domain; `packs_get` returns that domain's capabilities and skills."
+        },
+        {
+            "mcp": "tools_search",
+            "cli": "dreamstate tools search --goal \"<goal>\" --toolset <pack_id> --json",
+            "text": "finds the capability for the goal; `tools_get` returns its exact input schema. Read the schema every time, never guess params from memory."
+        },
+        {
+            "mcp": "tools_run",
+            "cli": "dreamstate tools run <capability_id> --params '{...}' --mode <dry_run|live> --json",
+            "text": "runs it with `capability_id` and `params`. The gating inputs (`mode`, `max_credits`, `idempotency_key`, `quote_hash`, `max_rows`, `approved`) go on the run call itself, never inside `params`."
+        },
+        {
+            "mcp": "runs_get",
+            "cli": "dreamstate runs get <run_id> --json",
+            "text": "follows long work; `runs_events` and `runs_list` read more of it and `runs_cancel` stops a run."
+        }
+    ]
+}