getcargohq/cargo-skills包含需要注意的行为
SKILL DETAIL
cargo
getcargohq/cargo-skills/cargo
该技能作为 Cargo CLI 技能包的路由器，是处理任何 Cargo 相关任务或跨多个 Cargo 域的任务时的首选入口。它解释了每个技能所负责的领域，区分了声明式工作区即代码（cargo-cdk）与命令式 CLI 的用法，并说明了技能之间 UUID 和 slug 的流转、运行和批次的异步轮询、端到端用例，以及可能静默失败的常见陷阱（如 `conjonction` 拼写、运行与批次的区别、模型 UUID 与段 UUID）。 当用户需要设置 Cargo、了解 Cargo 功能、选择正确的 Cargo 技能、初始化工作区、登录 Cargo 账户，或执行任何域不确定的 `cargo-ai` 命令时，该技能会被触发。如果任务明显属于某个特定技能，则应直接加载该技能，而无需经过此路由器。
安装量 · 135查看来源
Installation
npx skills add https://github.com/getcargohq/cargo-skills --skill cargo
技能文件
SKILL.md
最近同步 · 2026年8月29日
cli-version›
1.0.47
references/glossary.md›
# Glossary
Key terms used across the Cargo CLI skills.
---
## A
**action**
A discrete operation that an AI agent or workflow can perform. Actions come in four kinds: `tool` (orchestration tool), `connector` (third-party integration action), `agent` (AI agent), and `native` (built-in platform action). Actions replace the previous "tools" terminology in AI releases and messages. Execute a single action with `orchestration action execute`, or a single action across multiple records with `orchestration action execute-batch`. To chain multiple actions, use `run create` with `--nodes` or `batch create`.
**actionSlug**
A string identifier for a specific action on a workflow node. Present on both `kind: "native"` and `kind: "connector"` nodes.
- **Native nodes** — built-in Cargo actions discovered via `cargo-ai connection native-integration get` (keys of the `actions` object): `start`, `end`, `branch`, `filter`, `variables`, `agent`, `python`, `script`, etc. These are generic platform actions, not third-party service actions.
- **Connector nodes** — third-party service-specific actions discovered via `cargo-ai connection integration get <slug>` (e.g. `integration get hubspot`). Examples: `company_enrich`, `create_contact`, `send_message`. **Do not use `native-integration get` for these** — it will not return HubSpot, Salesforce, or other connector-specific actions.
**agent**
An AI resource with configured instructions, a language model, and optional actions. Created and configured via `cargo-ai`. Used in workflows as a `kind: "agent"` node, or messaged directly via `cargo-orchestration`.
**app (Cargo Hosting)**
A hosted Vite single-page app served on `https://<slug>.cargo.app`, built on `@cargo-ai/app-sdk` (Vite + refine, with `getCargoEnv()` / `useCargoApi()` wired to the workspace). Scaffolded with `hosting app init`, registered as a slot with `hosting app create` (which sets the globally-unique `--slug`), shipped via a **deployment**. Managed in the **`cargo-hosting`** skill. Distinct from a **worker** (a UI-less edge HTTP handler).
**appUuid**
The UUID of a Cargo Hosting app, returned by `hosting app create`. Passed as `--app-uuid` to deployment commands (`deployment create|list|get-promoted`), mutually exclusive with `--worker-uuid`.
**autocomplete**
A mechanism to fetch the list of allowed values for an action config field at runtime. When an action's `uiSchema` marks a field with `"ui:widget": "IntegrationAutocompleteWidget"`, its valid values must be retrieved via `cargo-ai connection connector autocomplete --connector-uuid <uuid> --slug <slug> --params '<json>'`. The autocomplete slug and params come from the field's `ui:options` in the `uiSchema`. Returns `{ "results": [{ "label": "...", "value": "..." }] }` — use the `value` in node configs.
---
## B
**batch**
A bulk execution of a workflow across multiple records. Created with `orchestration batch create`. Returns a `batchUuid` which is polled until `status` reaches `success`, `error`, or `cancelled`. Batches can be scoped to a segment, a list of record IDs, a file, or a filter.
**batchUuid**
The UUID returned by `batch create`. Used to poll batch status (`batch get`), download results (`batch download`), and filter run metrics.
---
## C
**capability skill**
A skill that documents one CLI domain (orchestration, storage, connection, AI, content, context, analytics, billing, hosting, workspace management). Capability skills are the "standard library" — the agent loads them when it needs the syntax for a specific CLI command. They sit at the repo root alongside the outcome skill (`cargo-gtm`). Capability skills never reference outcome skills (one-way dependency: outcome → capability).
**chat**
A conversation session between a user and an agent. Created with `ai chat create --agent-uuid <uuid>`. Messages are sent to a chat via `ai message create --chat-uuid <uuid>`.
**conjonction**
The intentional French spelling used as the key name in Cargo filter JSON objects. Always `"conjonction"`, never `"conjunction"`. A typo here silently returns no records — no error is thrown.
**column**
A typed field on a Cargo model. Each column has a `slug`, `type` (see **column type** below), `label`, and `kind` (see **column kind** below). Columns have no `uuid` — they are identified by `slug` within the model. Managed via `cargo-storage` (`storage column list|create|update|remove|reorder`). Column `slug` values are used in filter conditions and in `storage query execute` SQL queries.
**column type**
The data type of a model column. Stored as the `type` field on the column object. Set on `column create --type <value>` and returned as `type` in `column list` and `model list` responses.
When building a filter condition, the condition's `kind` field must match the target column's `type`. A mismatch silently returns no records.
| `type` | Use for | Filter condition operators (when used as `kind`) |
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `string` | Text, names, URLs, slugs | `is`, `isNot`, `contains`, `doesNotContain`, `startsWith`, `endsWith`, `isNull`, `isNotNull`, `isEmpty`, `isNotEmpty` |
| `number` | Counts, amounts, scores | `is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull` |
| `boolean` | Flags, yes/no values | `isTrue`, `isFalse`, `isNull`, `isNotNull` |
| `date` | Timestamps, dates | `is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull` |
| `object` | Nested JSON objects | `isNull`, `isNotNull`, `matchConditions` |
| `array` | Lists of values | `isNull`, `isNotNull`, `matchConditions` |
| `vector` | Embedding vectors | `isNull`, `isNotNull` |
| `any` | Untyped / mixed values | `isNull`, `isNotNull` |
See `cargo-orchestration/references/filter-syntax.md` for the full filter reference with examples for each kind.
**column kind**
How a column is sourced. Stored as the `kind` field on the column object. Determines whether the column is raw data or derived.
| `kind` | Description |
| ---------- | ------------------------------------------------------------------------ |
| `original` | Comes directly from the data source (integration extractor or SoR sync) |
| `custom` | User-defined column added manually |
| `computed` | Derived from an expression over other columns (e.g. concatenation, AI) |
| `metric` | Aggregated value from a related model (e.g. count, sum, avg) |
| `lookup` | Single field pulled from a related model via a join |
`type` and `kind` are independent: a `computed` column can have `type: "string"`, a `metric` column has `type: "number"`, etc.
**connector**
An authenticated instance of an integration. For example, a specific HubSpot account connected to your workspace. Referenced by `connectorUuid` in workflow node graphs. Listed via `connection connector list`.
**connectorUuid**
The UUID of a specific authenticated connector. Required for `kind: "connector"` nodes in workflow graphs and for filtering billing metrics.
**context**
The workspace's git-backed knowledge base of typed markdown/MDX files capturing GTM truth: company narrative, ICPs, personas, JTBDs, plays, proof, objections, signals, mediums, alternatives, clients, insights. Read and written by both humans and agents. Managed via `cargo-context` (`cargo-ai context runtime ...` and `cargo-ai context graph ...`). Distinct from the **system of record** (Cargo storage queried with SQL) and from agent **memories** (per-agent mem0 entries).
**content domain**
The CLI domain (`cargo-ai content …`) for workspace **files** and **libraries** — the binary/grouped knowledge attached to agents for RAG. Files and libraries moved here from the `ai` domain in CLI ≥ 1.0.19 (the old `cargo-ai ai file …` commands no longer exist). Documented in the **`cargo-content`** skill; attaching them to an agent lives in `cargo-ai`. Distinct from **context** (git-backed markdown).
**context repository**
The GitHub repository that backs the workspace's context. Files in this repo follow strict conventions: `kebab-case.md` filenames, YAML frontmatter with required `title` and `description`, and `domain/slug` cross-refs without `.md`. The canonical example is [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces). See `cargo-context/references/conventions.md` for the full domain list and per-domain templates.
**credit**
The unit of consumption on Cargo. Workflows consume credits when they execute nodes — particularly connector and agent nodes. Tracked via `cargo-billing`.
---
## D
**dataset**
A logical grouping of models in the Cargo workspace. Similar to a schema or folder. Models belong to datasets. Listed via `storage dataset list`.
**DDL**
Data Definition Language. In Cargo context, the result of `storage model get-ddl <uuid>` — contains the SQL table name, column definitions, and SQL dialect (`language`). Run when you need column types or the SQL dialect; `storage query execute` and `storage query download` reference tables by `<datasetSlug>.<modelSlug>` directly.
**deployment (Cargo Hosting)**
One build+upload of a local source directory to a hosting **app** or **worker**, created with `hosting deployment create --source <pkg-root>` (the backend runs `npm ci && vite build` for apps, or bundles the entrypoint for workers). A deployment is **not live until promoted** — `hosting deployment promote` points the subdomain at it, and `hosting deployment get-promoted` shows what's currently live. Managed in the **`cargo-hosting`** skill.
**deploymentUuid**
The UUID returned by `hosting deployment create`. Poll it with `hosting deployment get <uuid>` until the build status is terminal, then pass it to `hosting deployment promote --uuid`.
---
## E
**enrollment filter**
A segment filter condition (`kind: "enrollment"`) that includes or excludes records based on their history with a workflow — whether they've entered it, how many times, or when they last left.
**expression**
A dynamic config value in a node graph. Either a `templateExpression` using `{{nodes.<slug>.<field>}}` syntax, or a `jsExpression` using raw JavaScript. Used to pass data between nodes at runtime.
---
## F
**filter**
A JSON object used to select records from a model or segment. Always has the structure `{"conjonction": "and"|"or", "groups": [...]}`. See `cargo-orchestration/references/filter-syntax.md` for the full reference.
**folder**
An organizational container for plays, tools, and agents in the Cargo app. Managed via `cargo-workspace-management`. Has no effect on workflow execution.
---
## G
**GTM (go-to-market)**
The set of activities for finding, qualifying, and engaging prospects: sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring. The `cargo-gtm` outcome skill is cargo's front door for any GTM task.
---
## H
**hosting**
The CLI domain (`cargo-ai hosting …`) for Cargo Hosting — **apps** (Vite SPAs on `*.cargo.app`), **workers** (serverless edge HTTP handlers), and the **deployments** that ship and promote them. The lifecycle is `init` (local scaffold) → `create` (slot + globally-unique slug) → `deployment create` (build+upload) → `deployment promote` (go live). Documented in the **`cargo-hosting`** skill.
---
## I
**ICP (Ideal Customer Profile)**
The target prospect description used to filter sourcing and qualification: industry, size band, geography, tech stack, role, funding stage, etc. Every prospecting recipe begins by translating the user's stated ICP into provider filters. Often captured as a `icp/<slug>.md` file in the context repo.
**ICP fit**
The degree to which a record matches the ICP. Often expressed as a 0–10 score from a scoring agent (`anthropic.instruct` or similar) over enriched record fields. See `cargo-gtm/guides/writing-outreach.md` for scoring patterns.
**intent signal**
An observable behavior suggesting a company is ready to buy: hiring for a relevant role, raising funding, adding/removing tech in their stack, posting recent LinkedIn updates, anonymous website visits, recent job changes among employees. Cargo surfaces intent signals via `cargo.enrichBusinessFunding…`, `theirStack.searchJobs`, `waterfall.detectJobChange`, `snitcher.searchSessions`, and others. Tracked as `signal/<slug>.md` files in the context repo.
**integration**
The external service type — e.g. HubSpot, Clearbit, Salesforce. Defines what actions are available. A single integration can have multiple connectors (multiple authenticated accounts). Listed via `connection integration list`.
**integrationSlug**
The string identifier for an integration type (e.g. `hubspot`, `clearbit`, `salesforce`). Used in `kind: "connector"` node definitions alongside `actionSlug`.
---
## K
**knowledge graph**
The typed graph of nodes and cross-references derived from every markdown/MDX file in the **context repository**. Built (or loaded from cache) via `cargo-ai context graph get`. Each node carries parsed frontmatter (`title`, `description`) and outbound `domain/slug` references. Used to audit cross-references, discover existing entries, and power downstream agents that need the typed structure of the workspace's context. See `cargo-context/references/examples/graph-queries.md` for ready-to-run queries.
---
## L
**languageModelSlug**
The identifier for an LLM used by an agent or inline agent node. Examples: `gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`. Set on `agent create` or `agent update`.
**library**
A collection in the **content domain** (`cargo-ai content library …`) that groups files into one resource an agent can reference for RAG. `native` libraries are workspace-managed; `connector`-backed libraries sync documents from an external source through an unstructured-data extractor (`--extractor-slug`).
---
## M
**MCP server**
A Model Context Protocol server. Three distinct things wear this name in Cargo. The **platform MCP** (`https://mcp.getcargo.io/mcp`) is first-party and always there: a fixed toolset for operating a workspace (search/execute actions, inspect runs, query models), reached over HTTP with OAuth or over stdio via `cargo-ai mcp`. A **curated MCP server** (`ai mcp-server create`, served at `/v1/ai/mcpServers/<uuid>/mcp` or `cargo-ai mcp --server <uuid>`) exposes only the tools, agents, and models a workspace chose to publish. An **MCP client** (`ai mcp-client connect`) points the other way — someone else's server, attached to an agent release so the agent can call its tools during conversations or workflow runs.
**memory**
A piece of information an agent stores from a conversation for future reference. Listed via `ai memory list --agent-uuid <uuid>`. Can be cleared with `ai memory remove`. Distinct from the **context repository** (workspace-wide, structured, git-backed) and from agent files / RAG resources.
**model**
A structured data table in the Cargo workspace — e.g. Companies, Contacts, Deals. Has columns, relationships, and an associated SQL table in the system of record. Not to be confused with a language model.
**modelUuid**
The UUID of a Cargo data model (table). Required for `segment fetch`, `segment download`, and as input to `model get-ddl`. Note: `storage query execute` references models by their **slug** (`<datasetSlug>.<modelSlug>`), not their UUID.
---
## N
**native integration**
A built-in Cargo integration type (distinct from third-party connector integrations). Native nodes (`kind: "native"`) include built-in workflow actions like `start`, `end`, `branch`, `filter`, `variables`, `agent`, `python`, `script`. They have no rate limits.
**node**
A single step in a workflow graph. Has a `kind` (`native`, `connector`, `tool`, or `agent`), a `slug`, a `config`, and `childrenUuids` pointing to downstream nodes.
**node graph**
A directed acyclic graph (DAG) of nodes defining a workflow's execution steps. Passed as a JSON array to `run create --nodes` or `batch create --nodes` to override a workflow's deployed release.
---
## O
**outcome skill**
A skill the agent loads when the user states a real-world goal (e.g. "build a TAM list", "find 5 fintech CTOs", "monitor job changes"). The repo ships one outcome skill, **`cargo-gtm`**, which routes across all GTM scenarios via internal recipes (`cargo-gtm/recipes/*.md`). It composes actions across multiple CLI domains and delegates to capability skills via relative paths (`../<name>/...`). The "application library" sitting on top of the capability "standard library".
**output node**
The terminal node of a workflow / tool / play whose output is the canonical result of a run. Identified by its `slug` (typically `output` or `end`) on the deployed release. Required input to `cargo-ai orchestration run download-outputs --output-node-slug <slug>` for retrieving action results.
---
## P
**play**
A segment-driven workflow that reacts automatically to data changes (records added, updated, or removed from a segment). Listed via `orchestration play list`. Triggered via `batch create` (not `run create`). The strategy behind a play is often captured as `play/<slug>.md` in the context repo (hypothesis, trigger, audience, channel, sequence, proof).
**polling**
The pattern of repeatedly calling `run get`, `batch get`, or `message get` until the operation reaches a terminal state. See `cargo-orchestration/references/polling.md` for intervals and shell snippets.
**persona**
A role / title shape that's part of the ICP. Example personas: "Head of RevOps at a B2B SaaS", "Founder at a seed-stage fintech". Used as filters for `salesNavigator.searchLeads`, `peopleDataLabs.searchPeople`, etc. Captured as `persona/<slug>.md` in the context repo with role, KPIs, pains, motivations, preferred channels, and common objections.
**priority stack**
The 8 default credits-based providers used as the spine of every recipe in `cargo-gtm/`: **salesNavigator** (sourcing), **cargo** native (firmographic + signal intelligence), **aiArk** (LinkedIn-anchored enrich + cheapest per-record search), **waterfall** (multi-source enrichment + verification + job-change signal), **FullEnrich** (premium contact lookup), **apolloio** (1-credit niche-coverage enrich), **theirStack** (tech-stack + hiring intent), **peopleDataLabs** (heavyweight backfill). See `cargo-gtm/SKILL.md` for the full stack reference and per-provider playbooks.
**proof**
An atomic proof point — one metric, quote, case fact, or benchmark — stored as `proof/<slug>.md` in the context repo. Cross-referenced from plays, objections, and decks. Keep proof entries atomic (one fact per file) so they can be filtered in the knowledge graph.
**prospect**
A person being marketed or sold to — typically resolved to a `prospect_id` via `cargo.matchProspect`. Distinct from a "lead" (which usually implies an inbound or marketing-qualified context); cargo uses "prospect" generically.
**prospecting**
The activity of finding prospects matching an ICP, enriching them with contact details and signals, and preparing them for outreach. Cargo's prospecting recipe lives at `cargo-gtm/recipes/prospecting.md`.
---
## R
**RAG (Retrieval-Augmented Generation)**
A pattern where an agent references uploaded files (PDFs, CSVs, text) or libraries to ground its responses in specific knowledge. Files are uploaded via `cargo-ai content file upload` (libraries via `content library`) and attached to agents through the release's `resources`.
**record**
A single row in a Cargo model (e.g. one company, one contact). Identified by a `recordId`. Processed individually by runs or in bulk by batches.
**recordId**
The identifier of a specific record in a model. Used in `batch create --data '{"kind":"recordIds","recordIds":["id1","id2"]}'` to target specific records for processing.
**release**
A snapshot of a workflow's node graph at a point in time. When a workflow is deployed, a release is created. Runs and batches execute against a specific release. Referenced by `releaseUuid`.
**releaseUuid**
The UUID of a specific workflow release. Returned by `batch get` → `.releaseUuid`. Used to fetch node slugs via `release get` (needed for `batch download --output-node-slug`).
**run**
A single execution of a tool workflow against one record. Created with `orchestration run create`. Returns a `runUuid` polled until `status` reaches `success`, `error`, or `cancelled`.
**runUuid**
The UUID of a single workflow run. Used to poll status (`run get`), inspect results, and filter analytics.
**runtime sandbox**
A checked-out, executable copy of the **context repository** that backs every `cargo-ai context runtime ...` command. `runtime write` and `runtime edit` commit and **push to the default branch**; `runtime execute` runs a shell command in the sandbox but **does not push** any file changes. Use `execute` for inspection (grep, ls, find); use `write`/`edit` for any change that should land in git.
---
## S
**segment**
A filtered, live view of records in a model. Defined by a filter condition. Used as the trigger population for plays and as a data source for batch runs. Listed via `segmentation segment list`.
**segmentUuid**
The UUID of a segment. Used in `batch create --data '{"kind":"segment","segmentUuid":"..."}'` — but only for a **standalone** segment from `segmentation segment list`. The `segmentUuid` returned by `play list` is the play's internally generated segment and is rejected by `batch create`; trigger a play with `{"kind":"filter","modelUuid":"<play.modelUuid>","filter":{"conjonction":"and","groups":[]}}` instead. Note: `segment fetch` and `segment download` require `--model-uuid`, not `--segment-uuid`.
**slug**
A human-readable string identifier used throughout the platform. Node slugs identify nodes within a graph (e.g. `enrich_company`). Integration slugs identify integration types (e.g. `clearbit`). Column slugs identify model columns. Slugs use only `[a-zA-Z0-9_]`. In the **context repository**, slugs are kebab-case filenames without the `.md` extension and are referenced as `domain/slug`.
**signal**
See **intent signal**. In cargo recipes, signals are the basis for segment construction (e.g. "all companies that just raised funding AND are hiring engineers") and outbound timing. Captured as `signal/<slug>.md` files in the context repo.
**sourcing**
The activity of finding companies or people matching ICP criteria. Cheapest at-scale options: `salesNavigator.searchLeads` (0.02 cred/record), `salesNavigator.searchAccounts` (0.05). For investor / funding / complex filters: `peopleDataLabs.queryCompanies` (3). For local SMBs: `serper.searchPlaces` (1).
**system of record (SoR)**
Cargo's storage layer, backed by a customer-connected database (BigQuery, Snowflake, etc.) that Cargo queries via SQL. Queried with `cargo-ai storage query execute "<sql>"` (or `storage query download --query "<sql>"` for full exports), which references tables as `<datasetSlug>.<modelSlug>` (e.g. `default.companies`). Use `cargo-ai storage model get-ddl <model-uuid>` for column types and SQL dialect. Distinct from the **context repository** (markdown/MDX knowledge base, not relational data) and from the **orchestration query** surface (`cargo-ai orchestration query execute`, which targets the `runs`/`batches`/`spans`/`records` runtime tables).
---
## T
**TAM (Total Addressable Market)**
The full universe of companies (and optionally contacts at those companies) matching an ICP. Cargo's TAM-build recipe lives at `cargo-gtm/recipes/build-tam.md`, typically producing 100–10,000 company lists.
**template**
A pre-built blueprint for a workflow node graph (`orchestration template list`) or an AI agent (`ai template list`). Used to bootstrap common patterns without building from scratch. In the **context repository**, every domain also ships a `_template.md` documenting the expected sections (read it with `cargo-ai context runtime read --path <domain>/_template.md`).
**temperature**
A float between `0.0` and `1.0` controlling how deterministic an agent's responses are. `0.0` = fully deterministic; `1.0` = highly creative. Set on `agent create` or `agent update`.
**tool**
An on-demand workflow triggered manually, via API, or on a cron schedule. Listed via `orchestration tool list`. Supports both `run create` (single record) and `batch create` (multiple records).
---
## U
**uiSchema**
A companion object to `jsonSchema` in action and extractor configs. While `jsonSchema` defines the types and structure of fields, `uiSchema` provides UI rendering hints. The most important hint for CLI usage is `"ui:widget": "IntegrationAutocompleteWidget"` — this signals that the field's allowed values must be fetched dynamically using `connector autocomplete` rather than set to a freeform value. The `ui:options.slug` identifies which autocomplete endpoint to call, and `ui:options.params` (if present) specifies dependencies on other fields. See `cargo-connection` for the full autocomplete workflow.
---
## W
**waterfall enrichment**
A pattern where multiple providers are run sequentially, each filling gaps the prior step missed. Cheap providers do the heavy lifting; premium providers fill the long tail. Implemented as N sequential `action execute-batch` calls with the records pruned between calls. See `cargo-gtm/references/waterfall-strategy.md` for canonical chains by enrichment goal.
**worker (Cargo Hosting)**
A hosted serverless HTTP handler that runs on the edge — a standard `fetch(request, env)` entrypoint built on `@cargo-ai/worker-sdk` (automatic OpenAPI 3.1 spec at `/openapi.json`, Swagger UI at `/docs`). Scaffolded with `hosting worker init`, registered with `hosting worker create`, shipped via a **deployment**. Has no `env` subcommand (unlike an **app**) — runtime config arrives via the `env` argument to `fetch`. Managed in the **`cargo-hosting`** skill.
**workerUuid**
The UUID of a Cargo Hosting worker, returned by `hosting worker create`. Passed as `--worker-uuid` to deployment commands, mutually exclusive with `--app-uuid`.
**workflow**
A DAG of nodes that defines the execution logic for a play or tool. Workflows don't have a `name` field — find them by name via `play list` or `tool list`, then extract `workflowUuid`.
**workflowUuid**
The UUID of a workflow. The primary key for most orchestration, analytics, and billing commands. Get it from `play list` or `tool list` → `.workflowUuid`.
**workspace**
The top-level organizational unit in Cargo. All resources (models, agents, workflows, connectors, the context repository) belong to a workspace. Identified by a `workspaceUuid`. Managed via `cargo-workspace-management`.
references/gotchas.md›
# Common gotchas
Silent-failure footguns and frequently confused command pairs across the Cargo CLI. Skim before designing a new workflow or debugging unexpected empty results.
| Gotcha | Detail |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conjonction` spelling | Filter JSON uses `conjonction` (not `conjunction`). This is intentional. A typo here fails silently — no records returned. |
| `run create` vs `batch create` | `run create` only works with **tool** workflows. Using a play's `workflowUuid` returns `playNotCompatible`. |
| Inputs in `config` are dropped, not rejected | On a top-level action (`action execute` / `execute-batch`) the inputs go in `--data` / `--records`, and `config` is omitted entirely. It used to fail loudly (`A top-level action does not use action.config…`); that guard is gone, so `config` is stripped and the action runs with **no inputs** — a provider-side missing-field error, or an empty result, that never mentions `config`. |
| `get-output-schema` still requires `config` | Alone among the action commands. Paste the `action` object from `action list` (which carries no `config`) into `execute` and it runs; into `get-output-schema` and it fails `400 — expected record, received undefined` at `action.config`. Add `"config": {}` for that one call. The CLI's own `--help` examples for it omit `config` and therefore all 400. |
| Guessing an action slug | `cargo-ai orchestration action list <keywords>` searches connector, native, tool, and agent actions in one free call and hands back the `action` object (with `connectorUuid`) plus the action's credit costs. `unknown command` = the CLI predates it; refresh. |
| `cargo-ai mcp` with no `--server` | Now bridges the first-party **platform MCP** (`mcp.getcargo.io/mcp`). It used to resolve "the workspace's only MCP server" and fail when there were none or several — so a bare `cargo-ai mcp` on an old CLI is a different server from a bare `cargo-ai mcp` on a new one. Pass `--server <uuid>` for a curated server either way. |
| `node execute` vs `action execute` | `action execute` is the default for running an operation (`--action` + `--data`, no workflow needed). `node execute` is **debug-only** — testing one node of a workflow you're authoring — and requires all five of `--workflow-uuid`, `--release-uuid`, `--node`, `--computed-config`, `--context`. Both bill credits. |
| Triggering a play | Use `batch create --data '{"kind":"filter","modelUuid":"<play.modelUuid>","filter":{"conjonction":"and","groups":[]}}'`. The `segmentUuid` from `play list` points at the play's internally generated segment and is rejected (`segmentLinkedToPlay`, or a misleading `noRecords` on older backends) however many rows the model holds. `{"kind":"segment"}` is for standalone segments from `segmentation segment list` only. |
| `--model-uuid` vs `--segment-uuid` | `segment fetch` and `segment download` require `--model-uuid`. Get it from `segment list` → `.modelUuid`. |
| `run list` can't find "the last run" | `orchestration run list` **requires** `--workflow-uuid` — there is no unfiltered form, and a play's UUID is not a workflow UUID. To find a run from a symptom alone, query the `runs` table instead (no filter required): `orchestration query execute "SELECT uuid, workflow_uuid, record_title, status, created_at FROM runs ORDER BY created_at DESC LIMIT 10"`, or match `record_title ILIKE '%<domain>%'`. Full ladder: `../../cargo-diagnostics/references/run-trace.md` § 0. |
| `SELECT *` fails on `runs` | Orchestration SQL caps a query at **50 columns read** and `runs` has 51, so `SELECT * FROM runs` returns `Limit for number of columns to read exceeded` — an error that reads like the table is unavailable when it isn't. Always name columns. |
| Node slugs repeat within a release | `nodes[].slug` is **not** unique — one shipped waterfall has six nodes slugged `variables`, and a play has an `agent` and a `variables` node both slugged `classify`. Anything that walks the graph (diagrams, edge maps, "which node produced this") must key on `uuid`. Note the knock-on: `{{nodes.<slug>...}}` and `runContext.<slug>` are ambiguous for a repeated slug, so give nodes you reference downstream distinct slugs. |
| Run graph: `nodes` **or** `releaseUuid` | `run get` returns the inline `nodes` for an `action execute` run and a `releaseUuid` with **no** graph for a run from a deployed tool/play. Reading the graph means `run.nodes` first, `release get <releaseUuid>` otherwise. |
| Storage query table names | `storage query execute` and `storage query download` reference tables as `<datasetSlug>.<modelSlug>` (e.g. `default.companies`). |
| Token shown once | API token values are only returned at creation. Store immediately. `workspaceManagement token create` requires `--name` (no more `--from-user`). |
| Invoice amounts in cents | `subscription get-invoices` returns `amount` in cents. Divide by 100. |
| Plays vs tools | **Play** = reacts to data changes (segment-driven). **Tool** = triggered on demand (manual, API, cron). |
| Batch data kinds | Play workflows accept: `segment`, `change`, `filter`, `recordIds`. Tool workflows accept: `file`, `records`. |
| Third-party connector rate limits | Only `kind: "connector"` nodes (Clearbit, HubSpot, etc.) have rate limits — native nodes do not. Errors grow silently as the batch runs. Start at 1 record, then 50, then 500 before full-scale. Add `retry` with backoff to connector nodes. |
| Template expressions fail silently | A `{{nodes.foo.bar}}` referencing a missing path resolves to `undefined` (no error) and the run still reports `success` — so branches take the wrong path and end-node values come out empty, silently. Verify the real shape with `run get <uuid>` → `runContext.<slug>` (node-level outputs **are** returned by the CLI). Agent output is nested under `.answer`. |
| Group results are an array | A `group` node's output is an array of per-iteration `end` outputs: `{{nodes.<groupSlug>[0].<field>}}`. There is **no `.results` wrapper**, and `.map(x => …)` arrow callbacks aren't supported in expressions. |
| Context survives a `delay` | Prior node outputs are **not** wiped by a `delay` — the run context is checkpointed (as JSON) and restored. The catch is JSON-serializability: store anything needed post-delay in a `variables` node, not a `python` node's `result`. |
| `context runtime execute` is ephemeral | `context runtime execute` runs commands in the sandbox but **does not push** any file changes. Use `runtime write` / `runtime edit` for persistent edits to the context repo. |
| `context runtime edit` must match exactly once | `--old-string` must occur exactly once in the file. Whitespace counts — read the file first and copy the substring verbatim. For multi-spot changes, do multiple targeted edits or use `write` to overwrite the whole file. |
| Large exports don't belong in context | Never read a full CSV/JSON export into the conversation — inspect with `head`/`jq` or a storage SQL query and pass files by path. A few preview rows in context, never the dataset. |
| Never enroll a full batch first | `batch create` / `action execute-batch` fan out across **every** record in the source — the mistake and the bill land together. Sample 10–20 records, report observed cost + hit-rate, then ask for approval quoting the **record count** and **credit estimate**. `kind: "segment"`/`"change"` have no limit — sample via `kind: "filter"` + `limit` or `recordIds`. See `../../cargo-orchestration/SKILL.md` → "Create a batch". |
| Count before you pay | Search actions bill on **returned** rows, not matched totals. Keep `limit` strict; a `limit: 1` probe sizes the whole pool for the price of one row. See `../../cargo-gtm/references/cost-discipline.md`. |
| Phone lookup is the ~10× lever | Phone actions run 3–7 credits/record vs ~0.1–1 for email. Never in a default chain — explicit user request on qualified leads only. |
| Receipt before next step | After any paid action: report credits spent, balance remaining, and hit-rate before proposing what to do next. Estimates diverging from actuals get a one-line why (`billing usage get-metrics` is the source of truth). |
references/interaction.md›
# Interaction conventions — plan gates, choices, and presenting
How an agent working with Cargo communicates: when to stop and ask, how to offer choices, and how to present what happened. These defaults apply across every skill in this pack; recipes and runbooks link here instead of restating them.
They exist because Cargo work is collaborative and (often) paid: building a play, wiring a node graph, or fanning out a batch is a back-and-forth with the user, not a fire-and-forget task.
## 1. The plan gate — design approval before building
Before creating or editing a node graph, deploying a release, or launching anything beyond a trivial single-node change, present the plan and **wait for approval**:
- **Trigger** — how the play/workflow is launched (manual/CLI run, batch over a segment, schedule, segment change). Ask if it isn't stated; it shapes the whole graph (input shape, volume, where outputs land).
- **Nodes and data flow** — what each node does and what feeds it, in human-readable names. Past three nodes, draw it: a [Mermaid flowchart](../../cargo-orchestration/references/node-diagram.md) of the graph, with the paid steps marked, is the artifact the user approves.
- **Cost shape** — which nodes are paid, rough per-record estimate.
Treat this as a hard gate: don't start building from an unconfirmed plan. It complements the **cost gate** in [`../../cargo-gtm/references/cost-discipline.md`](../../cargo-gtm/references/cost-discipline.md), which stays authoritative for spend (sample → approval → full run): the plan gate approves the *design*, the sample gate approves the *spend*. A trivial change (fix one expression, rename a node) doesn't need the ceremony — say what you changed and why.
**Batches get their own gate, every time.** Launching a batch is the one action that turns a design mistake into a full bill in a single command, so it never goes straight to full scope: run 10–20 records, show what came back and what it cost, then ask whether to enroll the rest — with the **record count** and the **credit estimate** in the question, not just "proceed?". This holds even when the plan gate already passed, and even when the batch arrived through `cargo-orchestration` or `cargo-cdk` with no GTM framing. Mechanics per data kind: [`../../cargo-orchestration/SKILL.md`](../../cargo-orchestration/SKILL.md) → "Create a batch".
## 2. Real choices: ask, with a recommended default
Many Cargo stages can be built more than one way — several providers cover the same enrichment, several actions do nearly the same thing, a step can be an agent node or a deterministic one. When alternatives genuinely differ:
- **Never pick silently.** List the options by human-readable name (never raw `actionSlug`s or UUIDs), with cost and what each is best at.
- **Mark a recommended default** and say why — the simplest option that fits the use case. The user should be able to accept in one word.
- **Batch related questions** into one round (trigger + provider + output destination), not a drip of one-offs.
- Don't ask when there's nothing to decide: one obvious option, or a pure read. Asking permission to look something up is friction, not collaboration.
```
How should this play be triggered?
1. Manual / CLI runs (recommended) — start with one-off test runs; attach a
schedule or segment trigger later.
2. Segment change — every record entering the segment becomes a run.
3. Schedule — recurring batch over the segment.
And for email lookup: waterfall verify-first (~0.4 cr/row, recommended) or
FullEnrich premium (~1 cr/row, better coverage on small companies)?
```
## 3. Presenting defaults
- **Narrate meaningful steps.** One or two sentences before a change (what and why) and after it (what happened). Refer to nodes, actions, and plays by name.
- **Summarize, don't dump.** Raw JSON, full SQL results, or CSV contents are never the primary answer — turn them into a short table, a count, or a one-line takeaway, and keep large exports out of the conversation entirely (context discipline: [`../../cargo-gtm/references/cost-discipline.md`](../../cargo-gtm/references/cost-discipline.md) §6). Show raw output only when the user asks.
- **Lead with the conclusion.** State what happened or what you found first; evidence after.
- **Show the structure at checkpoints.** After building or editing a graph, after a pilot, and when reporting a run: a picture beats prose. For a node graph that means a **Mermaid flowchart** from `cargo-ai orchestration node diagram` (free, runs nothing) rather than a transcription — routing, fallback edges, and which nodes bill all survive the trip. Sources and rules: [`../../cargo-orchestration/references/node-diagram.md`](../../cargo-orchestration/references/node-diagram.md). For anything else structural (a schema, a segment breakdown), a compact table.
- **Always surface the URL.** Every created or touched resource gets its `app.getcargo.io` link (URL patterns: [`uuid-flow.md`](uuid-flow.md)) so the user can open it in the Cargo app.
- **Receipts after paid actions** are their own convention — format in [`cost-discipline.md`](../../cargo-gtm/references/cost-discipline.md) §2.
## 4. Show the rows, not the schema
A user who has just built a model can't tell from a column list whether they built the right thing. Ten real rows tell them in one glance. So whenever a model gains structure or data, show the table:
- **After creating a model or adding columns** — echo the resulting schema as a compact table (column, type, what fills it). The model is still empty at this point; don't run a preview query expecting rows, and don't present emptiness as a result.
- **After the first data lands** (a batch, a play, an import writes into the model) — run `cargo-ai storage query execute "SELECT * FROM <dataset>.<model> LIMIT 10"` and show those rows. This is the checkpoint that matters: it's the first moment the user can see what they actually built.
- **After a play populates a new column** — preview that column alongside the record's identifying fields (`name`, `domain`, …), so filled vs. empty is obvious at a glance.
Storage queries are free and fast, so this preview costs nothing but a line of output. Keep it to ~10 rows and the columns that carry meaning — this is a glance, not an export (§3: summarize, don't dump). If the preview comes back empty or full of nulls when it shouldn't, that's a finding — say so instead of moving on.
## Where these apply most
- Building or editing plays/workflows (`cargo-orchestration`, and node-graph steps in `cargo-gtm` recipes).
- Activating GTM recipes end-to-end (`cargo-gtm` — the pilot gate already encodes §1's spirit for spend).
- Reporting diagnostics (`cargo-diagnostics` — conclusion-first tables).
- CDK plans (`cargo-cdk` — `cdk plan` output is the plan-gate artifact; present the diff, not the raw state).
references/prerequisites.md›
# Cargo CLI — prerequisites
The same install, login, and runtime conventions apply to every Cargo skill in this bundle. Each capability skill links here instead of duplicating the boilerplate. Load the [`cargo` router skill](../SKILL.md) first if you haven't already — it covers session refresh and skill routing.
## Install
```bash
npm install -g "@cargo-ai/cli@$(cat <path-to-the-cargo-skill-dir>/cli-version 2>/dev/null || echo latest)"
```
The skills bundle pins the CLI version it was written against in `cli-version`, which sits inside the `cargo` router skill directory — read it from wherever this bundle is installed (on Claude Code with `skills add`: `~/.claude/skills/cargo/`; plugin installs converge to the pin automatically via their SessionStart hook). Installing the pinned version avoids docs/CLI drift; `latest` is the fallback when the pin isn't readable. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.
## Authenticate
```bash
cargo-ai login --oauth # browser sign-in (recommended)
# or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)
# Pin a default workspace at login (with --oauth)
cargo-ai login --oauth --workspace-uuid <uuid>
```
**A new account starts with 100 free credits, no card required** — `--email` and `--oauth` both create the account on first use, so signing up and running real paid work can happen in a single agent turn. Quote the free balance to a first-time user before the first paid call.
`--oauth` runs the OAuth 2.0 Device Authorization Flow — no client setup. For CI / scripts, use `--token` with a workspace-scoped API token from **Settings > API**. Token values are shown only once; store immediately in a secrets manager.
## Verify
```bash
cargo-ai whoami
# → { "user": { "uuid": ..., "email": ... }, "workspace": { "uuid": ..., "name": ... } }
```
Always confirm `workspace.name` before any write — there is no dry-run mode for destructive commands. If the active workspace is wrong, re-run `cargo-ai login --oauth --workspace-uuid <uuid>` (or `--token <workspace-scoped-token>` for non-interactive use).
## Output conventions
- All commands output **JSON to stdout**.
- Successful commands exit `0`.
- Failed commands exit non-zero and return `{"errorMessage": "..."}` — read this field for the cause.
- Async commands (`run create`, `batch create`, `message create`, `action execute`, `action execute-batch`) return a UUID and a status that starts as `pending` / `running`. Pass `--wait-until-finished` to block, or poll the matching `get` command. See [`cargo-orchestration/references/polling.md`](../../cargo-orchestration/references/polling.md) for intervals and retry guidance.
## Permission prompts
When the Cargo plugin (or the installer's hook scaffolding) is present, an approval hook — wired per agent as `PreToolUse` (Claude Code), `PermissionRequest` (Codex), or `beforeShellExecution` (Cursor) — auto-approves ordinary `cargo-ai` calls — reads, queries, run/batch operations, and pipelines through read-only helpers (`jq`, `grep`, `head`, …) — so they don't prompt. Four categories always still prompt, deliberately: credentials (`login`/`logout`), token minting (`workspaceManagement token …`), report egress (`workspaceManagement report …` — reports can carry session traces, so consent stays explicit), and destruction/deploys (`cdk deploy`/`destroy`, any `remove`/`delete`). The hook is allow-only: it can skip a prompt but never override a deny rule. Don't restructure commands to dodge a prompt — if one of these prompts appears, it's supposed to.
## Admin-only commands
Some domains require a token with **admin access** on the workspace:
- All of `cargo-billing` (usage metrics, subscription, invoices).
- Most of `cargo-workspace-management` (users, roles, tokens — folder and report writes work with non-admin tokens).
If a command returns `{"errorMessage":"forbidden"}` or `unauthorized`, the token likely lacks admin scope. Re-issue with an admin user, or ask a workspace admin to run the command.
## When the CLI fails
Whenever a CLI command misbehaves, a documented flag is missing, or you've retried the same command twice without progress, file a workspace management report:
```bash
cargo-ai workspaceManagement report create \
--title "<one-line summary>" \
--description "<command(s) tried, errorMessage, expected vs actual, relevant UUIDs>"
```
This is the official feedback channel — every report is reviewed by the Cargo team. See [`cargo-workspace-management/SKILL.md`](../../cargo-workspace-management/SKILL.md) (Reports section) for the full template.
references/use-cases.md›
# End-to-end use cases
Worked recipes showing which skills to load and the command sequence for common Cargo scenarios. Use these as a starting point — each links to the relevant skill docs for the full per-command reference.
## 1. Enrich a single company (simplest path)
**Skills needed:** `cargo-orchestration`
```
1. orchestration action execute → run a connector action on one record
--action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich"}'
--data '{"domain":"acme.com"}' --wait-until-finished
```
## 2. Enrich a list of companies and push to CRM
**Skills needed:** `cargo-storage`, `cargo-connection`, `cargo-orchestration`, `cargo-analytics`
```
1. storage model get-ddl → get exact table name
2. connection connector list → get enrichment + CRM connector UUIDs
3. connection integration get <slug> → discover third-party action slugs (e.g. HubSpot, Clearbit)
4. orchestration tool list → find the enrichment tool
5. orchestration batch create → run on a segment of companies
6. orchestration batch get → poll until status is terminal
7. analytics run download → export results
```
## 3. Score leads with AI and update the model
**Skills needed:** `cargo-ai`, `cargo-orchestration`, `cargo-billing`
```
1. ai agent list → find or create the scoring agent
2. ai agent create → configure instructions, model, temperature 0.0
3. orchestration play list → find the scoring play
4. orchestration batch create → trigger on a segment of new leads
5. orchestration batch get → poll until status is terminal
6. billing usage get-metrics → check credit consumption
```
## 4. Build a custom enrichment workflow from scratch
**Skills needed:** `cargo-connection`, `cargo-orchestration`
```
1. connection connector list → get connector UUID
2. connection integration get <slug> → get actionSlug for the third-party service
3. orchestration node validate --nodes → validate graph before running
4. orchestration run create --nodes → run with custom node graph
5. orchestration run get → poll to terminal state
```
## 5. Monitor workflow health and alert on errors
**Skills needed:** `cargo-orchestration`, `cargo-analytics`
```
1. orchestration tool list / play list → discover workflowUuid
2. analytics run count --statuses error → count errors in period
3. analytics run get-metrics → get success/error rate breakdown
4. analytics run download --statuses error → download failed runs for inspection
```
## 6. Bootstrap a fresh workspace
**Skills needed:** `cargo-workspace-management`, `cargo-storage`, `cargo-connection`, `cargo-ai`
```
1. workspaceManagement token create --name <label> → create a dedicated, named API token
2. workspaceManagement role list → discover available roles
3. workspaceManagement user create → invite team members
4. storage model create → create Companies and Contacts models
5. storage column create → add columns (name, domain, employee_count, etc.)
6. storage relationship set → link Contacts → Companies
7. connection connector create → connect enrichment and CRM integrations
8. ai agent create → configure an AI agent for research or scoring
9. workspaceManagement folder create → organize plays and tools into folders
```
**Credentials in step 1:** the `token create` response is the **only** time the token
value is shown — hand it to the user for a secrets manager (GitHub Secrets, AWS Secrets
Manager) rather than echoing it into a file, a commit, or the transcript. Scope it to
what the job needs: most of this bootstrap requires **admin**, but the token that later
runs plays or batches does not. Steps 1 and 3 change who can see and touch workspace
data, so confirm the token's scope and the invite list with the user before running them.
## 7. Export and analyze segment data
**Skills needed:** `cargo-storage`, `cargo-analytics`
```
1. storage model list → get modelUuid
2. analytics segment download → export with filter and sort
--filter '{"conjonction":"and","groups":[
{"conjonction":"and","conditions":[
{"kind":"string","columnSlug":"country","operator":"is","values":["US"]}
]}
]}'
--sort '[{"columnSlug":"created_at","kind":"desc"}]'
```
## 8. Author and audit the workspace's GTM context repo
**Skills needed:** `cargo-context`
```
1. context runtime browse → see the domain layout
2. context runtime read --path persona/_template.md → grab the template for the target domain
3. context runtime write --path persona/<slug>.md → add the entry (frontmatter + body, pushes to default branch)
4. context graph get | jq … → audit cross-refs, find plays missing proof, etc.
```
See `../../cargo-context/references/examples/authoring.md` and `../../cargo-context/references/examples/graph-queries.md` for full recipes.
references/uuid-flow.md›
# UUID flow between skills
Most `cargo-orchestration` operations require UUIDs from other skills. This table maps which skill produces each UUID and which commands consume it.
| UUID | Produced by | Consumed by |
| --------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
| `workflowUuid` | `orchestration play list` / `tool list` | `run create`, `batch create`, `run get-metrics`, `run download` |
| `modelUuid` | `storage model list` / `orchestration play list` | `batch create --data '{"kind":"filter",...}'` (the way to trigger a play), `segment fetch`, `segment download`, `model get-ddl`. Note: `storage query execute` references models by slug, not UUID |
| `segmentUuid` | `segmentation segment list` | `batch create --data '{"kind":"segment",...}'`. Standalone segments only — the `segmentUuid` from `play list` is rejected |
| `agentUuid` | `ai agent list` | `ai chat create`, node graph (`kind: "agent"`) |
| `connectorUuid` | `connection connector list` | Node graph (`kind: "connector"`), `billing usage --connector-uuid` |
| `actionSlug` | `connection integration get <slug>` (third-party) or `connection native-integration get` (built-in) | Node graph (`kind: "connector"` or `kind: "native"`) |
| `releaseUuid` | `orchestration batch get` → `.releaseUuid` | `orchestration release get`, `batch download` |
| `batchUuid` | `orchestration batch create` | `batch get`, `batch download`, `run get-metrics --batch-uuid` |
| `folderUuid` | `workspaceManagement folder list` | `play list --folder-uuid`, `tool list --folder-uuid` |
| `roleSlug` | `workspaceManagement role list` | `workspaceManagement user create --role-slug` |
## Standard discovery sequence
Before running a workflow:
```bash
# 1. Confirm identity
cargo-ai whoami
# 2. Find the tool or play to run
cargo-ai orchestration tool list
cargo-ai orchestration play list
# 3. Find the model (and dataset slug) for SoR queries
cargo-ai storage model list
cargo-ai storage dataset list
cargo-ai storage model get-ddl <model-uuid> # optional — for column types and SQL dialect
# 4. Find connectors needed by the workflow nodes
cargo-ai connection connector list
# 5. Find agents used in workflow nodes
cargo-ai ai agent list
# 6. Find the segment to process (for plays / batch with segment data)
cargo-ai segmentation segment list
```
## Retrieve in the UI
Each resource has a dedicated page in the Cargo app. Use these URL patterns to cross-reference a UUID returned by the CLI with the UI, or to extract a UUID from a URL the user pastes.
| Resource | URL pattern |
| -------- | ------------------------------------------------------------------- |
| Play | `app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID>` |
| Tool | `app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID>` |
| Agent | `app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>` |
| Model | `app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>` |
The workspace UUID is returned by `cargo-ai whoami` under `workspace.uuid`.
skill-metadata.json›
{
"$comment": "Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .",
"name": "cargo",
"version": "1.23.0",
"documents": [
{
"path": "SKILL.md",
"kind": "entrypoint",
"title": "Cargo CLI — Skills Overview"
},
{
"path": "cli-version",
"kind": "asset"
},
{
"path": "references/glossary.md",
"kind": "reference",
"title": "Glossary"
},
{
"path": "references/gotchas.md",
"kind": "reference",
"title": "Common gotchas"
},
{
"path": "references/interaction.md",
"kind": "reference",
"title": "Interaction conventions — plan gates, choices, and presenting"
},
{
"path": "references/prerequisites.md",
"kind": "reference",
"title": "Cargo CLI — prerequisites"
},
{
"path": "references/use-cases.md",
"kind": "reference",
"title": "End-to-end use cases"
},
{
"path": "references/uuid-flow.md",
"kind": "reference",
"title": "UUID flow between skills"
}
],
"contentHash": "886490892220b1d3fd44d17976013df246892b84a95e87635fabdca6dd5275b5"
}
SKILL.md›
---
name: cargo
description: "Router for the Cargo CLI skill bundle — load first for anything Cargo, and whenever a task spans two Cargo domains. Explains what each skill owns, declarative workspace-as-code (cargo-cdk) vs the imperative CLI, the UUID and slug flow between skills, async polling of runs and batches, end-to-end use cases, and the gotchas that fail silently (`conjonction` spelling, run vs batch, model-uuid vs segment-uuid). Triggers: \"set up Cargo\", \"what can Cargo do\", \"which Cargo skill\", \"bootstrap my workspace\", \"I have a Cargo account\", \"cargo-ai …\", or any `cargo-ai` command whose domain you are unsure of. Skip when: the task obviously belongs to one skill — load that skill directly."
version: "1.23.0"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/cargo-skills
metadata:
author: getcargo
openclaw:
requires:
bins:
- cargo-ai
install:
- kind: node
package: "@cargo-ai/cli@latest"
bins:
- cargo-ai
homepage: https://github.com/getcargohq/cargo-skills
---
```
██████ ████ █████ ██████ ██████
██ ░ ██ ██░ ██ ██ ██ ░ ██ ██░
██ ██████░ █████ ░ ██ ███ ██ ██░
██ ██ ██░ ██ ██ ██ ██░ ██ ██░
██████ ██ ██░ ██ ██ ██████░ ██████░
░░░░░░ ░░ ░░ ░░ ░░ ░░░░░░ ░░░░░░
```
# Cargo CLI — Skills Overview
This repository contains 19 skills at the repo root: this **router** (`cargo`), one **onboarding skill** (`cargo-quickstart`), one **outcome skill** (`cargo-gtm`), and sixteen **capability skills**.
- **`cargo-quickstart`** — guided first-run demo. Fresh workspace → real deliverable (25 leads for the user's persona, with a cost receipt) in under two minutes, ending by saving the demo as a recurring play. Load for new users, demo/tour requests, or empty workspaces.
- **`cargo-gtm`** — application library. The front door for any GTM task ("build a TAM list", "find 5 fintech CTOs", "monitor job changes"). Routes via internal recipes (`../cargo-gtm/recipes/*.md`) and provider playbooks (`../cargo-gtm/provider-playbooks/*.md`).
- **Capability skills** — standard library. One per CLI domain (orchestration, storage, segmentation, connection, AI, content, context, analytics, billing, observability, hosting, cdk, mailbox management, workspace management), plus `cargo-diagnostics` (cross-domain forensics over runs, batches, and credit spend) and `cargo-mcp` (the hosted MCP server, the one surface that is not the CLI). Loaded by `cargo-gtm`, or directly when you need a specific CLI domain.
- **`cargo-cdk`** — the declarative one. Where the other capability skills wrap **imperative** one-off `cargo-ai <domain>` calls, `cargo-cdk` defines the whole workspace as code (`define*` builders + `cargo-ai cdk deploy`) and reconciles it. It spans every resource type — see "Declarative vs imperative" below to route between it and the imperative skills.
`cargo-gtm` delegates to capability skills; capability skills never reference `cargo-gtm` (one-way dependency).
**Glossary:** See [`references/glossary.md`](references/glossary.md) for term-by-term definitions (UUIDs, slugs, `conjonction`, run/batch/play/tool, signal/persona/ICP, etc.).
**Interaction conventions:** See [`references/interaction.md`](references/interaction.md) for the pack-wide defaults on when to stop and ask (plan gate before building, recommended-default choices) and how to present results (narrate, summarize — never dump raw JSON).
## Installation
```bash
npm install -g @cargo-ai/cli
# Recommended: emailed code, no browser at any point.
# Creates the account and a workspace on first use — there is no separate sign-up step.
cargo-ai login --email [email protected] # sends the code, then exits
cargo-ai login --email [email protected] --code 123456
# Alternatives
cargo-ai login --oauth # browser sign-in (OAuth device flow)
cargo-ai login --token <your-api-token> # existing workspace-scoped API token (CI)
# Optional: pick the workspace at login instead of being prompted
cargo-ai login --email [email protected] --workspace-name "Acme GTM"
# Verify
cargo-ai whoami
```
**A new account starts with 100 free credits and needs no card**, so an agent can sign a user up and produce a real deliverable in the same turn — there is no purchase gate between install and first value. Useful anchors for what that buys: ~5,000 leads sourced (`salesNavigator.searchLeads`, 0.02/record), ~1,000 profile+verified-email enriches (`aiArk.enrichPerson`, 0.1), ~1,000 email verifications (`waterfall.verifyEmail`, 0.1), or ~50 fully enriched contacts (`waterfall.enrichContact`, 2). The [quickstart demo](../cargo-quickstart/SKILL.md) spends about **0.5**. Say the free balance out loud before the first paid call on a new account.
`--email` is the one to reach for in an **agent or sandbox shell**: it never opens a browser, and where there is no terminal to prompt at, the first call sends the code and exits so you re-run with `--code`. To keep the code out of shell history, pass it on stdin: `echo 123456 | cargo-ai login --email [email protected] --code -`. Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re-run.
`--oauth` runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. Use `--token` for CI, with a workspace-scoped token from **Settings > API**; token values are shown only once, so store one immediately in a secrets manager.
Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.
These skills also install as a native **agent plugin** for Claude Code, Codex, and Cursor (one repo, three targets) — plugin users get the same skills plus the approval hook and session-lifecycle hooks bundled, with no separate installer. See the repo `README.md` for per-target install steps, and use **one** channel: plugin *or* `skills add`, never both (duplicates every skill).
All commands output JSON to stdout. Failed commands exit non-zero and return `{"errorMessage": "..."}`. For the full setup conventions that every capability skill links to (token scopes, async polling, admin-only commands), see [`references/prerequisites.md`](references/prerequisites.md).
## Every Cargo session has three jobs
> **Automated on Claude Code.** Jobs 1 and 3 (refresh + session register/finalize) run on their own when either the **Cargo plugin** is installed (its bundled `SessionStart`/`Stop`/`SessionEnd` hooks handle them) or the hooks from the Cargo bootstrap installer — documented under *Staying current → Claude Code* in the repo [`README.md`](../README.md) — are present. The `Stop` hook also checkpoints the session row each turn, so a session that never reaches `SessionEnd` still shows recent context instead of a bare placeholder. Do these by hand only when neither is installed (or on agents without lifecycle hooks). Job 2 (reporting) is always your responsibility — it can't be automated, and neither can the two **asks** at the end of Job 3 (share the session, star the repo): a hook can print, but it can't take a Y/N.
>
> **Never run that installer on the user's behalf without asking.** Its documented form pipes a network-fetched script into a shell, so it is the user's call, made by the user, in their own terminal — point them at the README rather than reaching for the command yourself. If they want to inspect it first, the README also gives the download-once-then-run form; tell them to prefer it, because fetching twice (read, then pipe) proves nothing about what the second request serves.
### 1. At session start — refresh and register
Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management:
```bash
# Refresh — idempotent, ~10s. Skills first, then the CLI at the version the
# bundle pins. The pin file `cli-version` sits in the same directory as this
# SKILL.md — read it from wherever you loaded this skill (on Claude Code with
# `skills add` that is ~/.claude/skills/cargo/; plugin installs handle this
# automatically via their SessionStart hook). Fall back to latest.
npx -y skills add getcargohq/cargo-skills
npm install -g "@cargo-ai/cli@$(cat <path-to-this-skill-dir>/cli-version 2>/dev/null || echo latest)"
# Register the session (placeholders OK — overwritten at session end)
cargo-ai workspaceManagement session upsert \
--session-id <session-id> \
--title "Agent session <session-id>" \
--summary "Session in progress."
```
Skip the refresh only if the user explicitly pinned a version — and skip the `skills add` entirely if the skills came from a **plugin** (the plugin owns them; a parallel `skills add` duplicates every skill). Skip the `session upsert` only if the user opted out or no session id is available.
**Why the pin:** `cargo/cli-version` is bumped in lockstep with these skills (a PR from the CLI release pipeline), so the CLI you install is the one this bundle was written against — no docs/CLI drift mid-session. If the pin file is missing or unreadable, `latest` is the safe fallback. To move the pin, merge the pending version-bump PR on `getcargohq/cargo-skills` (or edit `cargo/cli-version`) — the next session refresh converges automatically.
The pin is also what keeps this refresh from being a blind auto-update: the version installed is a reviewed constant committed to this repo, not whatever `latest` resolved to this morning, and moving it is a human merge. Two things follow for you as the agent. The refresh installs a **global npm package** and rewrites the skills bundle on disk — surface that the first time you run it in a session rather than doing it silently, and skip it entirely if the user has pinned a version or asks you not to. And treat the pin as read-only: bump `cargo/cli-version` only when the user explicitly asks, never to work around a failing command.
### 2. Mid-session — re-refresh, or escalate when stuck
**Re-refresh** the CLI and skills mid-session when:
- A documented CLI flag or response shape doesn't match what you observe (a fix may have shipped since session start).
- The user explicitly asks ("bump cargo", "make sure I'm on latest").
**Send a workspace management report** when the CLI is failing in a way the skill references and `--help` cannot resolve, the user or agent is repeatedly retrying the same command without progress, the syntax for a flag / JSON payload is unclear, or a needed capability seems missing:
```bash
cargo-ai workspaceManagement report create \
--title "<one-line summary of the problem>" \
--description "<exact command(s) tried, errorMessage, expected vs actual, UUIDs involved>"
```
Trigger conditions (any one is enough):
- A command failed ≥ 2 times in a row on the same task and the cause is not obvious.
- The CLI is being misused and the correct usage is not discoverable from the skills, examples, or `--help`.
- A documented behavior contradicts what you observe.
- A feature appears to be missing entirely.
This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI and these skills. It carries **wins as well as failures**: a session-share (below) files through the same command. **Do not give up silently — file a report.** See `../cargo-workspace-management/SKILL.md` (Reports section) and `../cargo-workspace-management/references/examples/reports.md` for templates.
### 3. At session end — finalize the session row, then ask to share
Produce a short title (5–8 words) and a 1–2 sentence summary of what the session actually worked on, then overwrite the placeholder row and stamp `finished_at`:
```bash
cargo-ai workspaceManagement session upsert \
--session-id <claude-session-id> \
--title "<5-8 word title>" \
--summary "<1-2 sentence summary of what was accomplished or attempted>" \
--finished
```
`--title` and `--summary` are required (NOT NULL). `--finished` stamps `finished_at = now`; pass `--finished-at <iso>` for an explicit timestamp.
**Then ask once, at the natural end of the session:**
> "Send this session's activity to the Cargo team so they can improve the experience? (Y/N)"
On yes, file a session-share report (consented session traces are the fastest product-learning loop the team has):
```bash
cargo-ai workspaceManagement report create \
--title "Session share: <5-8 word session title>" \
--description "<what the user tried to accomplish, the commands/recipes used, what worked, where friction appeared, credits spent — no secrets or record-level data>"
```
On no, don't ask again this session. Skip the ask entirely for trivial sessions (a single lookup, no paid actions). See `../cargo-workspace-management/references/examples/reports.md` for the session-share template.
#### Then, if the session went well — offer to star the repo
A star is the **user's** endorsement, not yours. Never run the command unprompted; ask, and act only on an explicit yes. Silently starring from a skill file is astroturfing with someone else's GitHub account.
Ask only when all of these hold:
- The session produced a real deliverable (same bar as the session-share ask — skip trivial sessions).
- Nothing is still failing or unresolved. Asking after a broken session reads as tone-deaf.
- The marker file `~/.config/cargo-ai/.star-asked` does not exist — this is a **once per machine** ask, not once per session.
```bash
# gate
test -f ~/.config/cargo-ai/.star-asked || echo "ask"
```
> "Glad that worked. Want me to star `getcargohq/cargo-skills` for you? (Y/N)"
On yes (`gh` must be authenticated with the `repo` or `public_repo` scope — note there is no `gh repo star` subcommand):
```bash
gh api -X PUT /user/starred/getcargohq/cargo-skills # 204 No Content = starred
```
Touch the marker on **either** answer, so a no is never re-asked and a yes is never double-asked:
```bash
mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked
```
If `gh` is missing or unauthenticated, don't fix it and don't offer a workaround — say the repo is at `https://github.com/getcargohq/cargo-skills` and move on. This is the lowest-stakes item in the session; it never becomes a task.
---
## Skills at a glance
### Declarative (CDK) vs imperative (CLI) — pick the mode first
Two ways to create/manage the same Cargo resources. Decide which the task wants
before picking a domain:
- **Declarative → [`cargo-cdk`](../cargo-cdk/SKILL.md).** The user is managing
resources **as an artifact**: "set up / bootstrap a whole workspace as code",
"make this reproducible / version-controlled / in git", "deploy these
connectors + models + agents together", or anything that should be re-runnable
and diffable across environments. Define it in `define*` files and
`cargo-ai cdk deploy`.
- **Imperative → the matching capability skill below.** The user is doing a
**one-off operation** or **exploring**: "create one connector", "add a column",
"list connectors", "run this workflow", "query storage", "read a memory". A read,
ad-hoc query, or single mutation that needn't live in code.
When unsure: should the result be committed and re-deployable? Yes → CDK. A quick
action or a read → the capability skill.
### Onboarding skill
Load for a brand-new user or an empty workspace.
| Skill | Load when you need to… |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| [`cargo-quickstart`](../cargo-quickstart/SKILL.md) | Run the guided first-run demo: one persona question → 25 leads in under two minutes → cost receipt → save as a recurring play. Routes to `cargo-gtm` afterwards. |
### Outcome skill
Load when the user states a real-world goal.
| Skill | Load when you need to… |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`cargo-gtm`](../cargo-gtm/SKILL.md) ([recap](#cargo-gtm)) | Any GTM task — sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring (job changes, funding, tech-stack/hiring intent). Routes via recipes (`recipes/`), guides (`guides/`), and provider playbooks (`provider-playbooks/`). |
### Capability skills
Load for a specific CLI domain. The first link in each row jumps to the actual SKILL.md; the parenthetical jumps to the recap on this page.
| Skill | Load when you need to… |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`cargo-orchestration`](../cargo-orchestration/SKILL.md) ([recap](#cargo-orchestration)) | Execute actions, run workflows, trigger batches, chat with agents, query orchestration with SQL (ClickHouse) |
| [`cargo-analytics`](../cargo-analytics/SKILL.md) ([recap](#cargo-analytics)) | Download run results, export segment data, monitor error rates and metrics |
| [`cargo-billing`](../cargo-billing/SKILL.md) ([recap](#cargo-billing)) | Check credit usage, view subscription details, track costs per workflow or connector |
| [`cargo-diagnostics`](../cargo-diagnostics/SKILL.md) ([recap](#cargo-diagnostics)) | Diagnose after the fact: trace why one run misbehaved, sweep a batch/play for errors grouped by root cause, profile where a play's credits go |
| [`cargo-observability`](../cargo-observability/SKILL.md) ([recap](#cargo-observability)) | Create and manage **alerts** — scheduled threshold checks on spans/runs/records, a model's health, or a SQL query — that fire actions (connector/tool/agent runs) on breach. Proactive counterpart to diagnostics |
| [`cargo-storage`](../cargo-storage/SKILL.md) ([recap](#cargo-storage)) | Inspect or modify data models, columns, datasets, and relationships; query workspace storage with SQL |
| [`cargo-segmentation`](../cargo-segmentation/SKILL.md) ([recap](#cargo-segmentation)) | Build and manage segments — the saved filters that name the audience for a batch, a play trigger, or an export — and read their change (delta) feed |
| [`cargo-connection`](../cargo-connection/SKILL.md) ([recap](#cargo-connection)) | Manage connector authentication, discover available integrations and their actions |
| [`cargo-ai`](../cargo-ai/SKILL.md) ([recap](#cargo-ai)) | Create and configure agents, configure releases, attach knowledge for RAG, manage MCP servers and memories |
| [`cargo-content`](../cargo-content/SKILL.md) ([recap](#cargo-content)) | Upload and organize knowledge files, build native/connector-backed knowledge libraries for RAG (the `content` domain) |
| [`cargo-context`](../cargo-context/SKILL.md) ([recap](#cargo-context)) | Browse/read/write/edit the workspace's git-backed GTM context repo, run commands in its runtime sandbox, inspect the knowledge graph |
| [`cargo-hosting`](../cargo-hosting/SKILL.md) ([recap](#cargo-hosting)) | Scaffold, deploy, and promote hosted apps (Vite SPAs on `*.cargo.app`) and edge workers (serverless HTTP handlers), and manage their deployments |
| [`cargo-cdk`](../cargo-cdk/SKILL.md) ([recap](#cargo-cdk)) | **Declarative — spans every resource type.** Define a whole workspace in code (`define*` builders) and deploy it with `cargo-ai cdk` (init → types → plan → deploy). Use for workspace-as-code / reproducible / version-controlled setups; see "Declarative vs imperative" above. |
| [`cargo-mailbox-management`](../cargo-mailbox-management/SKILL.md) ([recap](#cargo-mailbox-management)) | Provision sending mailboxes Cargo owns, run warm-up and the 5→40/day send ramp, send with the `sendEmail` action, and read threads, replies, delivery events, and suppressions |
| [`cargo-workspace-management`](../cargo-workspace-management/SKILL.md) ([recap](#cargo-workspace-management)) | Invite users, create API tokens, organize folders, manage roles, report CLI issues to management |
| [`cargo-mcp`](../cargo-mcp/SKILL.md) ([recap](#cargo-mcp)) | Drive Cargo from the hosted MCP server at `https://mcp.getcargo.io/mcp` with no CLI install — connect a client, discover and price an action, execute one record or a batch, poll it, read models; and route between the MCP tools and the CLI |
> **Agent knowledge for RAG:** **files** + **libraries** live in the `content` domain → [`cargo-content`](../cargo-content/SKILL.md); how they attach to an agent → [`cargo-ai`](../cargo-ai/SKILL.md). (Files/libraries moved out of the old `ai file …` path in CLI ≥ 1.0.19.)
### These skills vs an MCP server
**Three distinct things wear the name MCP here.** They share no answers, so
establish which one is meant before replying:
| | What it is | Skill |
|---|---|---|
| **Hosted server** | Cargo's own endpoint at `https://mcp.getcargo.io/mcp`. Thirteen platform tools (discover, price, execute, poll, read models), plus whatever this workspace published. The way to drive Cargo with no CLI installed. | [`cargo-mcp`](../cargo-mcp/SKILL.md) |
| **Workspace server** | A curated set *this workspace* publishes (`ai mcp-server create --actions … --resources …`), served to any stdio client by `cargo-ai mcp`. | [`cargo-ai`](../cargo-ai/SKILL.md) |
| **Agent MCP client** | Somebody else's MCP server attached *to* a Cargo agent (`release update-draft --mcp-clients`). | [`cargo-ai`](../cargo-ai/SKILL.md) |
The first is new and is what "does Cargo have an MCP server?" now means. It
authenticates by OAuth discovered from its own `401` challenge, or by a
workspace-scoped bearer token:
```bash
claude mcp add --transport http cargo https://mcp.getcargo.io/mcp
```
The second is the curation path, and remains the right answer when a workspace
wants to expose one approved tool rather than the whole platform:
```bash
claude mcp add cargo -- cargo-ai mcp # the platform MCP
claude mcp add cargo -- cargo-ai mcp --server <uuid> # a curated server instead
```
With no `--server`, the bridge uses `CARGO_MCP_SERVER_UUID` when set, otherwise the platform `/mcp`. (Older CLIs instead fell back to "the workspace's only MCP server" and failed outright when there wasn't exactly one.)
Route between the CLI and either MCP surface by shape of the request:
| | **These skills (CLI)** | **An MCP server** |
|---|---|---|
| What it is | The whole CLI surface, every domain | The platform runtime tools, plus whatever the workspace chose to expose |
| Best for | Anything that builds something reusable: workflows, plays, schema changes, CDK deploys, diagnostics, exports, warehouse SQL | In-conversation execution: look this record up, enrich this list, run this one approved tool |
| Cost control | Full pilot → approval → receipt discipline ([`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md)) | Per-call; `search_actions` returns each action's credit cost before you run it |
| Reproducible | Yes — commands, plays, and CDK files are artifacts | No — a tool call leaves no artifact behind |
Rule of thumb: **anything the user will want to re-run or version belongs in the CLI.** Never fan an MCP tool out record-by-record over a list — that is what `execute_action_batch` (and `orchestration action execute-batch` on the CLI) exists for, and it is cheaper and observable. Conversely, when the workspace has already curated a tool for a job, calling it beats hand-assembling the same thing from raw actions.
### CLI domains without a dedicated skill yet
The CLI exposes several domains that no capability skill wraps yet. Reach for them directly (`cargo-ai <domain> --help`) when a task needs them, and file a `workspaceManagement report` if the surface is unclear:
| CLI domain | Covers |
| --- | --- |
| `expression` | Recipes and expression evaluation (`eval`, `recipe`) — generate/evaluate the template expressions used in node graphs. |
| `system-of-record` | System-of-record, client, and log operations. |
| `revenue-organization` | Allocations, capacities, members, territories (revenue/territory planning). |
| `user-management` | Current-user operations with no workspace context. |
---
## How the skills relate
```
┌─────────────────────────────────────┐
│ cargo-gtm │
│ Outcome / front door for GTM │
│ Recipes, guides, provider-playbks │
└─────────────────┬───────────────────┘
│ delegates to ↓ (one-way)
┌──────────────────────┴──────────────────────┐
│ │
┌──────────────────────────────────────────────────────────────┐
│ cargo-workspace-management │
│ Authentication, users, tokens, folders │
└──────────────────────────────────────────────────────────────┘
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ cargo-storage │ │ cargo-connection │ │ cargo-ai │
│ Models, columns,│ │ Connectors, │ │ Agents, docs, │
│ datasets │ │ integration actions│ │ MCP, memory │
└────────┬────────┘ └─────────┬──────────┘ └────────┬────────┘
(cargo-content feeds
files/libraries to agents)
│ │ (UUIDs flow down) │
└──────────────────────┼───────────────────────┘
▼
┌───────────────────────────────────────┐
│ cargo-orchestration │
│ Runs, batches, plays, tools, SoR │
└───────────────┬───────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌────────────────────────┐ ┌───────────────────────────┐
│ cargo-analytics │ │ cargo-billing │
│ Results, metrics, │ │ Credit usage, costs │
│ exports │ │ │
└────────────────────────┘ └───────────────────────────┘
┌───────────────────────────────────────┐
│ cargo-context │
│ Git-backed GTM markdown knowledge: │
│ personas, plays, proof, signals… │
└───────────────────────────────────────┘
(orthogonal: not part of the workflow flow)
┌───────────────────────────────────────┐
│ cargo-cdk │
│ Declarative authoring layer: define │
│ connectors/models/plays/agents/… as │
│ code, deploy with `cargo-ai cdk`. │
└───────────────────────────────────────┘
(cross-cutting: PRODUCES the same resources the imperative
skills manage — an alternative mode, not a workflow stage)
┌───────────────────────────────────────┐
│ cargo-mailbox-management │
│ Sending inboxes Cargo owns: warm-up, │
│ send ramp, threads, replies, events, │
│ suppressions. The send itself is the │
│ `sendEmail` orchestration action. │
└───────────────────────────────────────┘
(owns the mailbox; orchestration owns the send — and every
send is gated by cargo-gtm's acceptable-use checks)
┌───────────────────────────────────────┐
│ cargo-observability │
│ Scheduled threshold alerts over the │
│ telemetry above (spans/runs/records), │
│ a model's health, or a SQL query — │
│ fire actions as runs on breach. │
└───────────────────────────────────────┘
(watches orchestration/storage; fires orchestration
actions — proactive counterpart to cargo-diagnostics)
```
**Dependency rules in practice:**
- `cargo-gtm` delegates to capability skills via relative paths (`../cargo-orchestration/...`). Capability skills never reference `cargo-gtm`.
- `cargo-workspace-management` provides auth context for every skill — set it up first.
- `cargo-storage`, `cargo-connection`, and `cargo-ai` are peer skills that supply UUIDs to `cargo-orchestration`. They don't depend on each other.
- `cargo-content` owns workspace **files** and **libraries** (the `content` domain). It produces file/library UUIDs that `cargo-ai` consumes as agent release `resources` (RAG). Uploaded content files also surface read-only under `.files/` in the `cargo-context` runtime sandbox.
- `cargo-mailbox-management` owns **sending inboxes** (the `mailboxManagement` domain) — provisioning, warm-up, the send ramp, threads, events, and the workspace suppression list. It deliberately does **not** send: delivery is the `sendEmail` native action under `cargo-orchestration`, which is why a send inherits orchestration's pacing, retry and credit accounting. The mailbox itself is also declarable as code via CDK's `defineMailbox` (with `defineDomain` for the sending domain).
- `cargo-cdk` is **cross-cutting**: it's a declarative *authoring mode* that produces the very connectors/models/plays/agents/etc. the imperative capability skills manage one at a time. Route to it when the task is "manage the workspace as code" (reproducible, in git, multi-resource); route to the imperative domain skills for one-off ops, reads, and ad-hoc queries. See "Declarative vs imperative" under Skills at a glance.
- `cargo-context` is **orthogonal** to the workflow-execution flow. It touches the git-backed GTM knowledge base (markdown/MDX), not storage or workflow runs. Use it for capturing/editing the workspace's prose context — personas, plays, proof, objections, signals — and for inspecting the typed knowledge graph.
- For SQL queries against storage, use `cargo-ai storage query execute "<sql>"` (tables as `<datasetSlug>.<modelSlug>`). Load `cargo-storage` to discover dataset and model slugs, and to fetch the DDL when you need column types or the SQL dialect.
- For SQL queries against orchestration runtime tables (`runs`, `batches`, `spans`, `records`) — error rates, per-node failures, time-series — use `cargo-ai orchestration query execute "<sql>"`. Workspace scoping is automatic; tables are referenced without a schema prefix.
- Before building a workflow node graph, load `cargo-connection` to get `connectorUuid` and `actionSlug`. If any node calls a **credits-based provider action**, also load `cargo-gtm` and read that provider's playbook (`../cargo-gtm/provider-playbooks/<slug>.md`) — including its **Recurring use** section whenever the workflow is a scheduled tool or play, since a bad config or wrong cadence re-bills on every run. This applies even when the task arrived through `cargo-orchestration` or `cargo-cdk` directly, without a GTM framing.
- Before executing a workflow that uses an agent node, load `cargo-ai` to get `agentUuid`.
- After runs complete, load `cargo-analytics` to download results or measure performance. **For action output retrieval, prefer `cargo-ai orchestration run download-outputs` over `run download` — the former returns a signed-URL CSV/JSON of just the output node's data.**
- Load `cargo-billing` to understand credit consumption for any of the above.
- When a run failed, a run "succeeded but looks wrong", a batch has errors, or a play costs too much, load `cargo-diagnostics` — it sequences the `run get` / orchestration-SQL / billing surfaces into forensic runbooks (trace one run, sweep a batch, profile credit spend).
- To be told about a problem *before* you go looking — an error-rate spike, a cost ceiling, a slow node, a stalled sync, a workflow that stopped running — load `cargo-observability`. It creates **alerts**: scheduled threshold checks over the same telemetry (`spans`/`runs`/`records`), a model's health, or a SQL query, that fire actions on breach. Diagnostics is reactive (explain what happened); observability is proactive (watch for it). Alerts can also be declared as code via CDK's `defineAlert`.
---
## Per-skill critical rules
The non-obvious rules for each skill — the things that fail silently or cost money if you guess. Each skill's own SKILL.md carries the full surface; these are the ones worth knowing *before* you pick.
### cargo-gtm
**Recipes shipped:**
| Recipe | Use when… |
|---|---|
| `recipes/source-planning.md` | Decide the source before spending: probe candidates, cost per hit. |
| `recipes/prospecting.md` | End-to-end find → enrich → verify → sync (P1/P2/P3 variants). |
| `recipes/build-tam.md` | Build a Total Addressable Market list at scale (100–10,000 companies). |
| `recipes/linkedin-url-lookup.md` | Resolve LinkedIn URL from name + company with strict validation. |
| `recipes/portfolio-prospecting.md` | Investor / accelerator → portfolio companies → contacts. |
| `recipes/job-change-monitoring.md` | `waterfall.detectJobChange` (cargo-unique) on a contact segment. |
| `recipes/funding-watch.md` | Track companies that recently raised funding. |
| `recipes/tech-intent.md` | Find companies by tech-stack or hiring-intent signals. |
| `recipes/icp-discovery.md` | Diff Closed-Won vs Closed-Lost segments, surface ICP signals. |
| `recipes/custom-datapoints.md` | Design which custom attributes + live signals to collect, gated on a real source and cost. |
| `recipes/outreach-activation.md` | Turn a signal segment into send-ready outreach (enrich → verify → personalize → sequencer handoff). |
| `recipes/ads-audience-activation.md` | Push a segment to Google Ads Customer Match / LinkedIn Matched Audiences. |
| `recipes/review-and-iterate.md` | Human review loop for judgment output; corrections become permanent rules. |
| `recipes/re-engagement.md` | Wake up stale contacts only when a fresh signal fires (job change, funding, tech intent). |
| `recipes/lost-deal-revival.md` | Revive Closed-Lost CRM deals by branching on `lost_reason` (champion left, budget, timing). |
| `recipes/account-expansion.md` | Multi-thread customer accounts — net-new buyers, deduped against the Contacts model. |
**Priority provider stack** (recipes lead with these): salesNavigator (sourcing), cargo native (firmographics + signals), aiArk (LinkedIn-anchored enrich + cheapest search), waterfall (multi-source enrichment + email verify + job-change), FullEnrich (premium contact lookup), apolloio (1-credit niche-coverage enrich), theirStack (tech-stack + hiring intent), peopleDataLabs (heavyweight backfill). **Already have LinkedIn URLs (or an event URL)?** Don't source — go straight to `aiArk.enrichPerson` (0.1, profile **+ verified email**, bills 0 on no-email), or `linkedin` (`enrichProfile`/`enrichCompany` 0.25, `extractEventAttendees`) when you don't need the email; these are the cheapest URL-anchored enriches and easy to miss because the stack above is sourcing-first.
**Critical rules:**
- **Acceptable use gates every step that touches a person** (`../cargo-gtm/references/acceptable-use.md`): B2B professional identities from licensed providers only, three free blocking checks before any outreach step (*basis*, *suppression*, *relevance*), and a refusal list — undifferentiated fan-out, consumer targeting, lists with no stated origin, contacting a suppressed record, filter or identity evasion, auto-dialing, batch-blasting LinkedIn engagement actions. The pack never sends: outreach stops at send-ready variables for the user's own sequencer.
- All recipes use credits-based actions (`cargo-ai connection integration list` → 145 credits-based actions across 120 integrations).
- Action shape: `{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"}` — no `config` on a top-level action, and **`connectorUuid` is never nested inside one**; it sits at the top level of a node.
- Output retrieval: `cargo-ai orchestration run download-outputs --output-node-slug <slug>` (NOT `run download`).
- peopleDataLabs filter shape: `searchX` uses cargo's `{conjonction, groups, conditions}` shape; `queryX` takes a PDL **SQL string** — never Elasticsearch.
### cargo-orchestration
**Critical rules:**
- See the decision flowchart at the top of `../cargo-orchestration/SKILL.md` for when to use `action execute` vs `run create` vs `batch create`.
- **Never enroll a full batch on the first attempt.** `batch create` / `action execute-batch` fan out across every record in the source. Sample **10–20 records**, report observed cost + hit-rate, then ask the user to approve the full enrollment — quoting the **record count** and the **credit estimate**. Mechanics: `../cargo-orchestration/SKILL.md` → "Create a batch"; spend rules: `../cargo-gtm/references/cost-discipline.md` §1.
- **Search for the action; never browse the catalog for it.** `cargo-ai orchestration action list <keywords> [--kind connector|native|tool|agent] [--integration-slug <slug>] [--limit 20]` covers the integration catalog, Cargo native actions, workspace tools, and agents in one free call, and returns a ready-to-paste `action` object (`connectorUuid` resolved) plus the action's **credit costs**. Its sibling `cargo-ai connection action search <keywords>` is connector-only but adds `--credits-only` and `--category`, the two filters `action list` lacks. Both beat paging `connection integration list`; reach for `integration get <slug>` only once you have picked the action and need its full input schema.
- **Omit `config` on `action execute` / `action execute-batch`** — inputs go in `--data` / `--records`. That is the shape `action list` returns, so its result pastes straight in. **`action get-output-schema` is the exception and still requires it** (`400` at `action.config` without `"config": {}`), as do workflow **nodes**, alert `--actions`, play `healthAlertActions`, and agent / MCP-server `--actions`. Inputs misplaced in `config` are now dropped rather than rejected — the action runs with no input and the error never mentions `config`.
- **`action execute` is the default for running an operation; `node execute` is debug-only.** Use `node execute` only to test a single node of a workflow you're authoring — it requires `--workflow-uuid`, `--release-uuid`, `--node`, `--computed-config` and `--context` (all five). Anything else — enrich a record, call a connector action, invoke a tool or agent — goes through `action execute` / `action execute-batch`.
- **Prefer built-in actions + expressions when building a node graph.** Avoid `python`, `script` (JS), and raw HTTP nodes unless necessary: use `variables` for transforms, the native `agent` node for LLM calls, the integration's dedicated connector action for APIs, and `branch`/`filter`/`switch` for routing. See `../cargo-orchestration/references/node-selection.md`.
- **Show a node graph, don't describe it.** Before deploying a draft, and whenever the user asks what a workflow or play does: `cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw` (free, runs nothing, CLI ≥ 1.0.54; `references/node-diagram.md`). Routing, fallback edges, and which nodes bill are what's being approved. Let the command draw it rather than transcribing — node **slugs repeat within a release**, so a hand-drawn diagram keyed on slug merges nodes that aren't the same.
- Filter JSON uses `conjonction` (not `conjunction`) — breaks silently if misspelled.
- Query orchestration runtime tables (ClickHouse) with `cargo-ai orchestration query execute "<sql>"` against `runs`, `batches`, `spans`, `records` (no schema prefix; workspace scoping is automatic).
- For SQL against workspace storage (Companies, Contacts, …), use `cargo-ai storage query execute "<sql>"` — documented in `cargo-storage`.
- All operations are async — poll or pass `--wait-until-finished`. See [Async polling](#async-polling).
### cargo-analytics
**Critical rules:**
- `segment download` requires `--model-uuid`, not `--segment-uuid`.
- For batch result download, get the `output-node-slug` from `release get <release-uuid>` → `nodes[].slug`.
- For billing and credit usage, use `cargo-billing` instead.
- Analytics answers "what happened" (metrics, counts, exports). When the question is **why** — a failing run, a batch full of errors, surprising cost — hand off to `cargo-diagnostics`; its sweep runbook picks up exactly where analytics' error counts leave off.
### cargo-billing
**Critical rules:**
- Requires a token with **admin access**.
- Invoice amounts are in cents — divide by 100 for dollars.
- `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get` = remaining credits.
### cargo-diagnostics
**Critical rules:**
- Start with the **sweep** when you don't know which run to look at; it ends with exemplar UUIDs for the **trace**.
- `runContext` is the source of truth for what a node produced; an execution's `title` is a truncated summary — never evidence.
- Credit attribution (`billing …`) needs an **admin** token; the SQL and `run get` steps don't.
- Any fix that re-runs paid nodes goes through the pilot gate in `../cargo-gtm/references/cost-discipline.md`.
- Diagnostics explains; it doesn't export. For bulk retrieval after the diagnosis (`run download-outputs`, `batch download`, `segment download`) go back to `cargo-analytics`.
- Present conclusions first, evidence as compact tables — per `references/interaction.md` (in the `cargo` router skill).
### cargo-observability
**Critical rules:**
- **`preview` before `create`.** `alert preview --scope … --threshold … [--window-minutes 60]` evaluates now without firing — the only way to size a threshold against reality and to catch an invalid scope/threshold pairing (`outcome: "notComputed"`) before it becomes a schedule that errors every tick.
- **Scope and threshold are a matched pair.** Telemetry metrics (`errorRate`, `duration`+aggregation, `credits`+aggregation, `count`) need `spans`/`runs`/`records`; `query` needs a query scope; `recordsCount`/`recordsShare`/`freshness`/`syncDuration` need `model`. Full matrix + units in `references/scopes-and-thresholds.md`.
- **Empty window vs real zero.** Most metrics report an idle window as `empty` (healthy, no fire). Only `count` and `recordsCount` return a real `0` — pair with `lte 0` for a **dead-man's switch** (alert when a workflow *stops*, a model *empties*).
- **Firing is at-most-once and costs credits.** Actions fire as runs (`runUuids` on the event); a sustained breach re-fires once per tick it's still true, never on the same rows twice. If an action calls a paid provider, apply `../cargo-gtm/references/cost-discipline.md` — a scheduled alert re-bills on every breach.
- **`--enabled` is strict** (`true`/`false` only); model-scope `filter` uses the segmentation shape spelled **`conjonction`**.
- Permissions are `observability:read` / `observability:write` (not admin-only). The declarative equivalent is CDK's `defineAlert` — see `cargo-cdk`.
### cargo-storage
**Critical rules:**
- Query via `cargo-ai storage query execute "<sql>"` (or `storage query download --query "<sql>"` for full exports) using `<datasetSlug>.<modelSlug>` table names (e.g. `default.companies`). `model get-ddl` is optional — useful for column types and SQL dialect.
- For SQL against orchestration runtime tables (`runs`/`batches`/`spans`/`records`), use `cargo-ai orchestration query execute "<sql>"` — documented in `cargo-orchestration`.
- For advanced record queries (filtering, sorting, pagination), use `segmentation segment fetch` — documented in `cargo-segmentation`.
- `storage relationship set` **replaces** the dataset's whole relationship set — anything absent from the payload is deleted. `list` first, send the full array back.
### cargo-segmentation
**Critical rules:**
- Filter JSON uses `conjonction` (not `conjunction`). A misspelling is **not** an error — the filter silently matches nothing.
- **Size before you spend.** `segment fetch --limit 1` counts an inline filter for free; a saved segment's `recordsCount` is the authoritative size. Quote it before proposing any paid run over the audience.
- `segment download` takes `--model-uuid` **plus the filter**, never `--segment-uuid`.
- `change list` needs `--segment-uuid`; `change fetch` needs the **change** UUID plus `--kinds` (`added`/`updated`/`removed`/`unchanged`).
- `updatedRecordsCount` stays `0` unless the segment was created with `--tracking-column-slugs` — those columns define what "updated" means.
- Segments named `GENERATED_PLAY_SEGMENT` (`fromPlay: true`) are owned by a play. Never edit or remove them by hand.
### cargo-connection
**Key concepts:**
- **Integration** = external service type (HubSpot, Clearbit, Salesforce, …)
- **Connector** = authenticated instance of an integration (referenced by `connectorUuid` in nodes)
### cargo-ai
**Critical rules:**
- Knowledge for RAG attaches to an agent via the release's `resources`: **files** + **libraries** come from [`cargo-content`](#cargo-content). Wire them in with `release update-draft --resources …` then `release deploy-draft`.
- **`cargo-ai mcp` with no `--server` now bridges the first-party platform MCP** (`mcp.getcargo.io/mcp`), not "the workspace's only MCP server". `ai mcp-server` still builds a curated server; pass its uuid with `--server`. See "These skills vs Cargo's MCP surfaces" above.
- **CLI ≥ 1.0.19:** files and libraries moved out of the `ai` domain into the top-level **`content`** domain (now the `cargo-content` skill). The old `cargo-ai ai file …` commands no longer exist.
> For _using_ agents (sending messages, multi-turn chat, polling), use `cargo-orchestration`.
See `../cargo-ai/SKILL.md` for model and temperature guidance by use case.
### cargo-content
**Critical rules:**
- New top-level **`content`** domain in CLI ≥ 1.0.19 — `cargo-ai content file …` / `cargo-ai content library …`. The old `cargo-ai ai file …` path is gone (`unknown command` → you're on the old path; bump the CLI).
- A file or library is inert until attached to an agent's deployed release `resources` — that wiring lives in [`cargo-ai`](#cargo-ai).
- Uploaded content files are also readable (read-only) under `.files/` in the `cargo-context` runtime sandbox.
- For batch-run **input** files (CSVs that drive a batch), use `cargo-ai workspaceManagement file upload` (a different surface) — see `cargo-workspace-management`.
### cargo-context
**Key concepts:**
- **Context repository** = the GitHub repo backing the workspace's context. Canonical example: [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces). Files use `kebab-case.md` names, YAML frontmatter with required `title` + `description`, and `domain/slug` cross-refs (no `.md`).
- **Runtime sandbox** = a checked-out, executable copy of the context repo. `runtime write` and `runtime edit` push to the default branch; `runtime execute` does **not** push.
- **Knowledge graph** = the typed graph over every md/mdx file, with frontmatter and outbound cross-refs per node. Built via `cargo-ai context graph get`.
**Critical rules:**
- `runtime write` / `runtime edit` commit and push. `runtime execute` is ephemeral — use it for `grep`/`ls`/inspection, never for persistent changes.
- `runtime edit --old-string` must match the file content **exactly once**. Read first, copy whitespace verbatim.
- Set `title` + `description` frontmatter on every `.md`/`.mdx` file — a **strong convention, not enforced**: missing/malformed frontmatter is still committed, it just indexes poorly (graph falls back to filename + first paragraph, and reads `summary`, not `description`).
- Graph **edges** form only from frontmatter `references:`, markdown links, or wikilinks — a bare path in prose creates no edge. Cite source files in `references:`.
- For domains, conventions, and per-domain templates, see `../cargo-context/references/conventions.md`.
**Lifecycle:**
- For bootstrapping a fresh workspace's context from a domain (ICP, personas, proof, signals — idempotent, skips already-seeded domains), see [`../cargo-context/references/examples/bootstrap-from-domain.md`](../cargo-context/references/examples/bootstrap-from-domain.md).
- For the full bootstrap + ongoing call-driven refresh playbook (Phase 1 + Phase 2 + cadence), see [`../cargo-context/references/examples/lifecycle.md`](../cargo-context/references/examples/lifecycle.md).
### cargo-hosting
**Lifecycle:** `init` (local scaffold) → `create` (slot + globally-unique slug) → `deployment create` (build+upload) → `deployment promote` (go live).
**Critical rules:**
- `--slug` is the live subdomain — **globally unique within the hosting domain**.
- **Deploying ≠ going live.** `deployment create` builds; the URL only moves on `deployment promote`. `deployment get-promoted` shows what's live.
- `--source` is the **package root**, not `dist/` — the build (`npm ci && vite build` for apps, bundling for workers) runs server-side.
- Builds are async — poll `deployment get` until terminal before promoting.
- `--app-uuid` / `--worker-uuid` are mutually exclusive on deployment commands; `remove` cascades to deployments.
- Folders come from [`cargo-workspace-management`](#cargo-workspace-management); `--folder-uuid null` moves to root.
### cargo-cdk
entire Cargo workspace in TypeScript (`defineConnector`/`defineModel`/`defineAgent`/
`definePlay`/`defineTool`/`defineMcpServer`/`defineContext`/`defineSegment`/
`defineFolder`/`defineFile`/`defineWorker`/`defineApp`/`defineAlert`/`defineDomain`/
`defineMailbox`) and reconcile
it to live infra with `cargo-ai cdk`. Spans **every** resource type, so it overlaps
every imperative capability skill — route with "Declarative vs imperative" above.
**Lifecycle:** `cdk init` (scaffold from a template) → `cdk types` (type config
against the workspace) → author `define*` files → `cdk plan` (offline diff) →
`cdk deploy` (create/update, write state) → `cdk destroy`. Plus `refresh` (drift),
`import` (adopt existing), `rollback`.
**Critical rules:**
- **Commit `cargo.state.json`** — it links code to created resources and is the
*only* handle on deployed plays/agents (no slug); losing it orphans them.
- **Wire by handle, not `.uuid`** — pass a `define*` handle or `xxRef("uuid")`.
- **Secrets** go through `secret("ENV_VAR")` — resolved at deploy, never written to
state or the content hash. Export the env var first.
- **`--yes`** is required for non-interactive `deploy`/`destroy` (CI).
- **Run `cargo-ai cdk types`** after workspace integrations change so config
type-checks; typing is a bonus, deploy works without it.
- **`definePlay`/`defineTool` graphs with credits-based connector actions:** read
the provider's playbook in `../cargo-gtm/provider-playbooks/` (esp. its
**Recurring use** section) before `cdk deploy` — a deployed play re-bills its
nodes on every scheduled run.
**Recipes shipped:** `recipes/scaffold-a-workspace.md`, `add-connector-and-model.md`,
`build-an-agent.md`, `migrate-existing-workspace.md`, `deploy-from-ci.md`.
**Cookbooks:** ~20 pre-written GTM outcomes (TAM building,
inbound flow, contact sourcing, account scoring, AI SDR, …) live in
[`getcargohq/gtm-skills`](https://github.com/getcargohq/gtm-skills) beside its one-off
skills. The menu is local:
[`../cargo-cdk/references/cookbooks.md`](../cargo-cdk/references/cookbooks.md).
Check it before authoring a common GTM outcome from scratch.
**The routing question is one-off versus standing.** "Build our TAM" is `cargo-gtm`
when the user wants a list today, and `tam-building` when they want a pipeline that
keeps producing it. The words are the same; listen for whether the result is meant to
keep arriving. Each cookbook is a self-contained worked example the installing agent
copies into the project and adapts, not a template to fill in:
`npx skills add getcargohq/gtm-skills/<name>`. See the section in
`../cargo-cdk/SKILL.md` for the caveats and the `--force` warning.
### cargo-mailbox-management
**Critical rules:**
- **A mailbox is a *monthly, recurring* credit charge**, not a per-record one — 100–160 credits per mailbox per month (`mailboxManagement pricing get` for live figures), for as long as it exists. `mailbox remove` is the only way to stop it; there is no pause. Quote the fleet size and the **credit estimate** per month, and get an explicit yes, before the first `create`.
- **This domain does not send.** Delivery is the native action `sendEmail` (`{"kind":"native","actionSlug":"sendEmail"}`, inputs in `--data`), **0.1 credits per send**, run through `cargo-orchestration`. A play that calls it **re-bills** — and re-contacts — on every run.
- **Volume is a ramp, not a setting.** Real sends go 5/day → 40/day linearly over 45 days from `warmupStartedAt`. A mailbox that never ran `start-warmup` is pinned at 5/day forever, `stop-warmup` resets the anchor to day 0, and `dailySendLimit` can only *tighten* the ramp, never loosen it.
- **Every send is gated by `../cargo-gtm/references/acceptable-use.md` §3** (basis, suppression, relevance). Suppression is workspace-wide, checked before every send, has no removal command, and `List-Unsubscribe` writes to it automatically. Raising the ramp — or spreading one campaign across extra mailboxes to clear the same volume — is the §2 evasion refusal.
- **Nothing here is async** — no run to poll. The exception that looks like one: `mailbox create` returns `status: "pending"`, cleared by `mailbox refresh-status`, not by `run get`.
- `--type outlook` is accepted by the flag and **always** fails (`transportNotSupported` — Graph delivery hasn't shipped). `--statuses`/`--kinds`/`--reasons` are comma-separated **with no spaces**. `mailbox list` is the only list with **no `count`**, and `mailbox`/`suppression` lists have **no default limit** (max 1000) where message/thread/event default to 50.
- **`bounced` has no producer yet** — nothing parses delivery-status notifications, so bounces write no events and do not auto-suppress. Never report an empty bounce count as a clean list.
- **There is no CLI surface for sending domains.** `mailbox create --domain-uuid` is required and `domainManagement` has no `cargo-ai` commands — take the UUID from the web app or CDK's `defineDomain`. Permissions are `mailboxManagement:read` / `:write` (not admin-only).
### cargo-workspace-management
**Critical rules:**
- Most commands require a token with **admin access**.
- `workspaceManagement token create` requires `--name` (the legacy `--from-user` flag was removed). Pick a name that makes the token's purpose obvious in `token list` later.
- Token values are only shown **once** at creation — store immediately in a secrets manager (GitHub Secrets, AWS Secrets Manager, etc.).
- **Always send a `workspaceManagement report create`** when the CLI errors, is being used incorrectly, or you (user or agent) are struggling to make progress on a CLI task — see the section at the top of this file and `../cargo-workspace-management/references/examples/reports.md`.
### cargo-mcp
**Critical rules:**
- **`whoami` first, every session.** The token binds the session to exactly one workspace with no override. A wrong-workspace session returns real records belonging to someone else, which reads as success.
- **Never loop `execute_action` over a list** — `execute_action_batch` is cheaper, observable, and returns one object plus an output CSV.
- `search_actions` returns each action's `credits[].cost`, so quote the price before running it, and sample 10–20 records before a full fan-out.
- `query_models` is not SQL: it lists records with a limit and offset, and will not aggregate or join. Route those to `cargo-storage`.
- The tool list varies by workspace — the endpoint serves the platform tools plus whatever that workspace published with `defineMcpServer`.
## Async polling
All operations are asynchronous. Pass `--wait-until-finished` to block, or poll:
| Result type | Poll command | Interval | Terminal when |
| ------------- | ----------------------------------------- | -------- | ---------------------------------------------- |
| Run | `cargo-ai orchestration run get <uuid>` | 2s | `status` is `success`, `error`, or `cancelled` |
| Batch | `cargo-ai orchestration batch get <uuid>` | 5s | `status` is `success`, `error`, or `cancelled` |
| Agent message | `cargo-ai ai message get <uuid>` | 2s | `status` is `success` or `error` |
`action execute` returns a run; `action execute-batch` returns a batch — same polling applies.
See `../cargo-orchestration/references/polling.md` for retry strategies, error handling, and large-batch guidance.
---
## UUID flow between skills
See [`references/uuid-flow.md`](references/uuid-flow.md) — producer/consumer table for every UUID and slug that crosses skill boundaries (`workflowUuid`, `modelUuid`, `connectorUuid`, `actionSlug`, …), the standard discovery sequence to run before any workflow, and the `app.getcargo.io` URL patterns for resolving UUIDs in the UI.
---
## End-to-end use cases
See [`references/use-cases.md`](references/use-cases.md) — 8 worked recipes (single-record enrich, batch + CRM sync, AI lead scoring, custom workflow from scratch, error monitoring, fresh-workspace bootstrap, segment export with filter+sort, GTM context audit) showing which skills to load and the command sequence for each.
---
## Common gotchas
See [`references/gotchas.md`](references/gotchas.md) — silent-failure footguns and frequently confused command pairs (`conjonction` spelling, `run create` vs `batch create`, `--model-uuid` vs `--segment-uuid`, storage query table naming, token-shown-once, invoice cents, third-party connector rate limits, `context runtime execute` vs `write`/`edit`, …).