cargo-context

# Context repo conventions

The conventions below are inherited from the canonical context repository [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces). When in doubt, read its `README.md` and the `_template.md` file in the relevant domain.

## Domains

| Domain | Purpose |
|---|---|
| `global/` | Company-level context: mission, voice, positioning, narrative, pricing |
| `icp/` | Ideal Customer Profile segments |
| `persona/` | Buyer personas (roles inside an ICP) |
| `jtbd/` | Jobs-to-be-done framings |
| `alternative/` | Competitors, substitutes, status quo |
| `client/` | Customer profiles, case studies, reference accounts |
| `insight/` | Market insights and observations |
| `medium/` | Channel playbooks (email, LinkedIn, cold call, etc.) |
| `objection/` | Objections + responses + proof |
| `play/` | GTM plays (signal → audience → channel → sequence → outcome) |
| `proof/` | Atomic proof points (metrics, quotes, case data) |
| `signal/` | Buying signals and intent triggers |

## File conventions

- **Filename:** `kebab-case.md` (e.g. `vp-sales-mid-market.md`). Use ASCII letters, digits, and hyphens only.
- **Frontmatter:** YAML with `title` and `description` on every `.md`/`.mdx` file. This is a **strong convention, not enforced** — a write with missing, empty, or malformed frontmatter is still committed; it just indexes poorly. The graph reads `title` (fallback: filename) and `summary` (fallback: first paragraph), **not** `description`. See [Source references and the knowledge graph](#source-references-and-the-knowledge-graph).
- **Cross-references:** `domain/slug` form, **no `.md` extension** (e.g. `persona/vp-sales-mid-market`). To register as a graph **edge**, a reference must appear as a wikilink, a markdown link, or a frontmatter `references:` entry (see below) — a bare `domain/slug` or file path in plain prose is not parsed.
- **Templates:** each domain ships an `_template.md`. Read it (`cargo-ai context runtime read --path <domain>/_template.md`) before authoring a new entry. `_template.*` files are excluded from the graph — never reference them.
- **Bidirectional links:** keep cross-refs symmetric when it makes sense — a `play` that targets a `persona` should appear in the persona's `Preferred channels` or `How we land` sections when relevant.

## Source references and the knowledge graph

The graph is built from **every `.md`, `.mdx`, `.yaml`, and `.yml` file** in the repo (any folder; only `.git/` is excluded). Each file becomes a node. **Edges are created only from these three forms** — everything else is invisible to the graph:

1. **Frontmatter `references:` list** (preferred for source citations — keeps prose clean, and the edge carries a `frontmatter` origin):

   ```yaml
   ---
   title: AgoraPulse expansion thesis
   description: Why the AgoraPulse account is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---
   ```

2. **A Markdown link in the body** — use when the citation needs surrounding prose. Write standard `[label]` immediately followed by `(path)` link syntax pointing at the source file, e.g. an "AgoraPulse session outcomes" anchor linking to `outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md`.

3. **Wikilinks in the body** (extension optional):

   ```markdown
   [[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]
   ```

### Linking rules

- **Never cite a source as a bare path in prose.** A `Source:` line that just mentions `outputs/sales-notes/foo.md` as plain text is **not** parsed and creates **no** edge. Always use one of the three forms above.
- **Prefer root-relative paths.** Paths resolve root-relative first (from the repo root), then relative to the citing file's directory. Root-relative paths work regardless of where the citing document lives.
- **Extensions are optional.** The resolver auto-tries `.md`, `.mdx`, `.yaml`, `.yml` (in that preference order). Including the extension is fine too.
- **The target must exist.** A reference only resolves if the target file is actually in the repo — nonexistent targets become **broken** edges (dead links in the graph UI). Verify the path before citing it (`cargo-ai context runtime browse --path <dir>`).
- **`_template.*` files are excluded** from the graph — don't reference `_template.md` / `.mdx` / `.yaml` / `.yml`.
- **YAML data files:** `title`, `summary`, and `references` are read from top-level keys; YAML bodies produce no link edges.
- **Node title/summary:** titles come from frontmatter `title:` (fallback: filename); summaries from frontmatter `summary:` (fallback: the body's first paragraph, truncated to 280 chars). The graph does **not** read `description` — set a `summary:` if you want the node summary to differ from the first paragraph. Always set `title` so the node is discoverable.

### Citing sources in insight / learning documents

When a document has a **Source** or **Evidence** section, cite the source files in **frontmatter `references:`** — this keeps the prose clean and gives the edges a `frontmatter` origin. Use inline markdown links when the citation needs surrounding prose.

## How to read the context

Start at `global/` for company context. Walk `icp/` → `persona/` → `jtbd/` to understand the buyer. Use `play/` for outbound motions and `objection/` + `proof/` for live conversations.

## Domain templates

The most commonly authored domains. For domains not shown here (`icp/`, `jtbd/`, `alternative/`, `client/`, `insight/`, `medium/`, `signal/`), read the in-repo `_template.md` directly:

```bash
cargo-ai context runtime read --path icp/_template.md
cargo-ai context runtime read --path signal/_template.md
# ...
```

### `global/_template.md`

```markdown
---
title:
description:
---

## Summary

_One-line version._

## Detail

_Full version. Mission, voice, positioning, narrative, pricing — whatever this entry is._

## Source

_Where this comes from. Founder note, brand doc, board deck, prior conversation._
```

### `persona/_template.md`

```markdown
---
title:
description:
---

## Role

- Title:
- Seniority:
- Function:
- Reports to:

## KPIs

-

## Pains

-

## Motivations

-

## Day-to-day

_What this person actually does on a Tuesday._

## Preferred channels

_Cross-ref `medium/...`._

-

## Common objections

_Cross-ref `objection/...`._

-

## How we land

_The angle, the pitch, the moment they get it._
```

### `play/_template.md`

```markdown
---
title:
description:
---

## Hypothesis

_Why this play should work. The bet._

## Trigger

_Cross-ref `signal/...`._

-

## Audience

_Cross-ref `icp/...` or `persona/...`._

-

## Channel

_Cross-ref `medium/...`._

-

## Sequence

1.
2.
3.

## Proof

_Cross-ref `proof/...`._

-

## Success metric

_What we measure. Target._

## Owner

_Role accountable for running this._

## Variants

-
```

### `proof/_template.md`

```markdown
---
title:
description:
---

## Type

_metric | quote | case | benchmark | screenshot_

## Content

_The actual proof point. Number, quote, fact._

## Source

_Where it comes from. Customer, study, internal data._

## Client

_Optional. Cross-ref `client/...`._

## Context

_What claim this supports. Why we cite it._

## Use cases

_Where this shows up: objections, plays, posts, decks._

-
```

### `objection/_template.md`

Objections pair a stated buyer concern with the response and the proof that backs it up:

```markdown
---
title:
description:
---

## Objection

_The buyer's stated concern, in their own words._

## Response

_Our reframe. Short, calm, specific._

## Proof

_Cross-ref `proof/...`._

-

## Personas

_Cross-ref `persona/...` — who raises this most._

-
```

## Authoring rules of thumb

- **One concept per file.** If you're tempted to add a second `## Persona` or a second `## Play` heading inside one file, you actually want two files.
- **Title is a label, description is a hook.** `title` shows up in lists; `description` is the one-line that explains why this entry exists.
- **Cross-refs over duplication.** If a fact already lives in `proof/...`, link to it from the play or objection rather than re-stating it.
- **Atomic proof.** Each `proof/` entry is one fact / quote / metric. Bundled proof points break filtering in the knowledge graph.
- **Repetition threshold for call-derived claims.** A single sales call is anecdote, not evidence. Before promoting an objection / pain / missed-proof claim from call analysis into the context repo, require it to surface across multiple calls. Suggested defaults:
  - Call-rich workspaces (≥ 50 transcripts / quarter): **3 occurrences**.
  - Medium volume: **2 occurrences**.
  - New / call-poor workspaces (< 10 transcripts): **1 occurrence**, and cite the source via frontmatter `references:` (or a markdown link) so the citation registers as a graph edge — see [Source references and the knowledge graph](#source-references-and-the-knowledge-graph).
  The threshold applies to claims, not to facts a call directly confirms (a named customer, a verbatim quote, a competitor explicitly mentioned). See `examples/lifecycle.md` for the full refresh loop.

# Authoring examples

End-to-end recipes for adding, editing, and removing entries in the context repo. All examples assume you're authenticated (`cargo-ai whoami` works) and that the workspace already has a context repository configured.

> **Lead with frontmatter.** Every `.md`/`.mdx` write below starts with a YAML block carrying `title` and `description`. This is a strong convention, **not enforced** — a file with missing or malformed frontmatter is still committed, it just indexes poorly (the graph falls back to the filename for `title` and the first paragraph for the summary). To cite a source file so it shows up as a **graph edge**, list it in frontmatter `references:` (or use a markdown link / wikilink) — a bare path in prose creates no edge. See `../conventions.md` for the full linking rules.

## Discover before writing

```bash
# 1. What domains exist?
cargo-ai context runtime browse

# 2. What's already in the target domain? (avoid duplicates)
cargo-ai context runtime browse --path persona

# 3. What's the shape of an entry in this domain?
cargo-ai context runtime read --path persona/_template.md
```

## Add a persona

```bash
cargo-ai context runtime write \
  --path persona/head-of-revops.md \
  --content "$(cat <<'EOF'
---
title: Head of RevOps
description: Owns the GTM tech stack, data quality, and pipeline reporting at a 200–2,000-person B2B SaaS.
---

## Role

- Title: Head of RevOps / Director of RevOps
- Seniority: Director / VP
- Function: Revenue Operations
- Reports to: CRO or COO

## KPIs

- Pipeline velocity, forecast accuracy, data freshness, CRM hygiene, lead-to-opp conversion

## Pains

- Stale enrichment, broken CRM workflows, slow rep ramp because the data model is brittle
- Stitching together 6 point tools that don't talk to each other
- Manual segment refreshes for plays

## Motivations

- One source of truth across SDR, AE, CS
- Replace fragile Zapier chains with durable workflows
- Get out of the way of the frontline

## Day-to-day

Ops standup, reviewing failed syncs, building a new segment for an outbound play, fielding rep requests, and weekly forecast prep with the CRO.

## Preferred channels

_Cross-ref `medium/...`._

- medium/peer-community-slack
- medium/founder-led-linkedin

## Common objections

_Cross-ref `objection/...`._

- objection/we-already-have-clay
- objection/we-built-this-in-house

## How we land

Lead with the stack-replacement angle: "one durable workflow runtime that replaces enrichment + scoring + sync." Show, don't tell — run a workflow live against their domain on the demo call.
EOF
)" \
  --commit-message "Add Head of RevOps persona"
```

## Add a play with cross-refs

```bash
cargo-ai context runtime write \
  --path play/funding-triggered-outbound.md \
  --content "$(cat <<'EOF'
---
title: Funding-triggered outbound
description: Reach out to companies within 14 days of a Series A–C raise with a hiring-and-stack angle.
---

## Hypothesis

Companies hit a stack-and-headcount inflection right after a raise. If we land in the first two weeks with a stack-replacement angle, we beat the procurement freeze that sets in by week 4.

## Trigger

_Cross-ref `signal/...`._

- signal/series-a-funding-announcement
- signal/series-b-funding-announcement

## Audience

_Cross-ref `icp/...` or `persona/...`._

- icp/post-series-a-b2b-saas
- persona/head-of-revops

## Channel

_Cross-ref `medium/...`._

- medium/founder-led-linkedin
- medium/cold-email-personalized

## Sequence

1. Day 0: LinkedIn connect + congratulations note (no pitch).
2. Day 3: Personalized email referencing the raise + a single relevant stack-replacement angle.
3. Day 7: Follow-up with one proof point (cross-ref `proof/customer-x-replaced-three-tools`).
4. Day 14: Break-up message.

## Proof

_Cross-ref `proof/...`._

- proof/customer-x-replaced-three-tools
- proof/14-day-time-to-first-workflow

## Success metric

Reply rate ≥ 12% on Day 3 email; meetings booked / 100 contacted ≥ 4.

## Owner

Outbound AE pod lead.

## Variants

- Same play, swap LinkedIn for warm intro when one exists (cross-ref `medium/exec-warm-intro`).
EOF
)" \
  --commit-message "Add funding-triggered outbound play"
```

## Add a proof point

Keep `proof/` atomic — one metric or quote per file:

```bash
cargo-ai context runtime write \
  --path proof/14-day-time-to-first-workflow.md \
  --content "$(cat <<'EOF'
---
title: 14-day time to first workflow
description: New customers ship their first production workflow within 14 days of signing.
---

## Type

metric

## Content

Across the last 24 customers (Q1–Q3), median time from contract signature to first production workflow run was 14 days; P90 was 27 days.

## Source

Internal customer success tracker, pulled 2025-10-15.

## Client

_Aggregate across customers — no single cross-ref._

## Context

Used to counter the "another tool we'll never deploy" objection. Pairs well with `objection/we-already-have-clay`.

## Use cases

- objection/we-already-have-clay
- play/funding-triggered-outbound
- Sales decks, slide 9 ("Time to value")
EOF
)" \
  --commit-message "Add 14-day time-to-first-workflow proof point"
```

## Cite a source in an insight / learning doc

When an entry is derived from a specific source file in the repo (a sales-note, a call summary, a research output), cite it in frontmatter `references:` so the citation registers as a **graph edge** with a `frontmatter` origin. Prefer root-relative paths, and confirm the target exists first (`cargo-ai context runtime browse --path outputs/sales-notes`).

```bash
cargo-ai context runtime write \
  --path insight/agorapulse-expansion-readiness.md \
  --content "$(cat <<'EOF'
---
title: AgoraPulse expansion readiness
description: Why the AgoraPulse account is ready for a multi-thread expansion play.
references:
  - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
---

## Summary

AgoraPulse surfaced three net-new buying centers in the last build session — strong signal for a multi-thread expansion.

## Evidence

Drawn from the [[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes|June 5 build-session outcomes]]: the champion named two adjacent teams already evaluating workflow tooling.
EOF
)" \
  --commit-message "Add AgoraPulse expansion readiness insight"
```

Both the frontmatter `references:` entry and the body wikilink (the `|` sets the display text) resolve to the same node — a bare `Source: outputs/sales-notes/...` line in prose would not. A standard Markdown link to the same file works too.

## Edit a single line

```bash
cargo-ai context runtime edit \
  --path global/positioning.md \
  --old-string "We help RevOps automate workflows." \
  --new-string "We help RevOps run AI-native GTM motions." \
  --commit-message "Refresh positioning one-liner"
```

## Delete a line from a file

```bash
# Read first to copy the exact line (whitespace must match!)
cargo-ai context runtime read --path persona/head-of-revops.md --start-line 18 --end-line 22

cargo-ai context runtime edit \
  --path persona/head-of-revops.md \
  --old-string "- Stitching together 6 point tools that don't talk to each other\n" \
  --new-string "" \
  --commit-message "Drop outdated pain point on Head of RevOps"
```

## Rename / move an entry

There's no `rename` command. Use `write` at the new path, then delete the old file with `execute` + push by overwriting it with `write` after removing — easier path: write the new file, then leave the old one in place until you're ready to remove it (a follow-up `write` with empty content is not supported; deletes happen via the GitHub UI or via `execute` followed by a manual commit step in the Cargo app).

For most renames, the cleanest sequence is:

1. `write` the new file at the new path.
2. Update every file that cross-refs the old slug — find them with `execute` + `grep`:
   ```bash
   cargo-ai context runtime execute --command grep --args '["-r","-l","persona/old-slug","."]'
   ```
3. For each match, `edit` the cross-ref `persona/old-slug` → `persona/new-slug`.
4. Delete the stale file via the GitHub UI (file the rename in a single PR if your context repo uses PR review).

## Verify your work

```bash
# Confirm the file is in place
cargo-ai context runtime read --path persona/head-of-revops.md

# Confirm it lights up in the graph and its cross-refs resolve
cargo-ai context graph get | jq '.nodes[] | select(.slug == "persona/head-of-revops")'
```

# Bootstrap workspace context from a domain

The prescriptive, automatable version of Phase 1 of [`lifecycle.md`](lifecycle.md). Use this when the user wants to **seed an empty (or thin) context repo from public data**, starting from nothing more than their company's domain. The recipe enriches the company via cargo native + waterfall + theirStack, scrapes public sources in parallel sub-agents, and writes one file per atomic concept through `cargo-ai context runtime write` — skipping any domain that already has content.

Output: a populated `global/`, `icp/`, `persona/`, `client/`, `proof/`, `signal/` (and where evidence supports it, `alternative/`, `objection/`, `insight/`) — enough that a fresh agent session can hold a coherent conversation about the company. Phase 2 (call-driven refinement) is deliberately out of scope here — see the "What this recipe does NOT do" section.

**Trigger phrases:**
- *"Set up my workspace context from acme.com."*
- *"Bootstrap the context repo — my domain is acme.com."*
- *"Fill in the ICP and personas from our website."*
- *"My workspace is empty, just use our domain to populate everything."*

## What this recipe exercises

- `cargo-ai context runtime browse` / `graph get` for the idempotency check.
- Cargo native enrichments (`matchBusiness`, `enrichBusinessFirmographics`, `enrichBusinessTechnographics`, `enrichBusinessFundingAndAcquisitions`) for the factual spine.
- Parallel sub-agents for public-source scraping (website, careers, blog, news, review sites).
- The driving agent's native LLM to synthesize each digest into typed markdown matching the per-domain template (no `cargo-ai orchestration action execute` double-hop — that pattern is for workflow node graphs, not for an agent already in the loop).
- `cargo-ai context runtime write` to commit one file per concept.

## Required inputs

Before executing, the agent needs:
1. **`domain`** (required) — canonical domain (`acme.com`), no protocol, no path.
2. **`companyName`** (optional) — falls back to whatever cargo native returns from `matchBusiness`.
3. **`depth`** (optional, default `standard`) — `minimal` (global + 1 icp + 2 personas), `standard` (full domain coverage), `deep` (also scrapes G2/Capterra/Reddit/HN for objections + alternatives).

If `domain` is missing, ask **once** and stop. Don't guess from the user's email — workspace domain and user email often diverge.

## Recipe

### Step 1 — Confirm the target workspace

Each Cargo workspace maps to one company. `runtime write` pushes immediately. Wrong workspace = polluted repo for someone else.

```bash
cargo-ai whoami
# → user.email, workspace.uuid, workspace.name
```

Read back `workspace.name` to the user and confirm it matches the company the `domain` belongs to. **Stop and ask** if the name is generic (`"Main"`, `"Test"`, a person's name, an internal codename) — workspace names are user-set and frequently don't match the customer-facing brand.

**Non-interactive mode** (server-side trigger from signup, scheduled job, etc.): skip the read-back if `domain` was passed in at session start *and* `workspace.uuid` was pinned at login. The capture point at signup is the authority — don't add a blocking question that breaks the automation.

### Step 2 — Idempotency check (the "if not exists" part)

Inventory what's already in the repo so we only fill gaps, never overwrite:

```bash
cargo-ai context runtime browse > /tmp/ctx-browse.json
cargo-ai context graph get > /tmp/ctx-graph.json

# Count entries per domain (excluding _template.md)
jq -r '.files[] | select(.path | test("^[^/]+/[^_].*\\.md$")) | (.path | split("/")[0])' /tmp/ctx-browse.json \
  | sort | uniq -c
```

Build a skip-list: any domain (`global/`, `icp/`, etc.) with ≥ 2 non-template entries is considered "already seeded" — leave it alone. **Print the skip-list to the user** before any writes so they see what wasn't touched and can override.

For domains that exist but are thin (1 entry), still write *new* files into them, but never `runtime edit` an existing file in bootstrap mode. Edits are for the refresh phase (see [Phase 2](lifecycle.md#phase-2--refresh-from-real-calls)), not bootstrap.

### Step 3 — Enrich the seed with cargo native (factual spine)

Run these in parallel — they give you the factual scaffolding (industry, headcount, tech stack, funding) every downstream synthesis step will cite:

```bash
# Match the domain to a cargo business_id
cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"cargo","actionSlug":"matchBusiness"}' \
  --data '{"domain":"acme.com"}' \
  --wait-until-finished > /tmp/match.json

BUSINESS_ID=$(jq -r '.output.business_id' /tmp/match.json)

# Parallel enrichments — same business_id, four different signal families
for action in enrichBusinessFirmographics enrichBusinessTechnographics enrichBusinessFundingAndAcquisitions enrichBusinessFinancialMetrics; do
  cargo-ai orchestration action execute \
    --action "$(jq -nc --arg a "$action" '{kind:"connector",integrationSlug:"cargo",actionSlug:$a}')" \
    --data "{\"business_id\":\"$BUSINESS_ID\"}" \
    --wait-until-finished > /tmp/enrich-$action.json &
done
wait
```

If `matchBusiness` returns no `business_id`, fall back to website scraping only (Step 4) — note in every written file's `## Source` section that firmographics were unavailable.

### Step 4 — Scrape public sources in parallel sub-agents

Spawn one sub-agent per source. Each returns a **structured digest** (key claims + source URL), never raw HTML. Suggested fan-out:

| Sub-agent | Source URLs | Lands in |
|---|---|---|
| Website core | `https://<domain>`, `/about`, `/product`, `/pricing`, `/customers` | `global/positioning`, `global/narrative`, `global/mission`, `global/pricing`, `client/...` |
| Careers | `/careers`, `/jobs`, LinkedIn jobs | `persona/...`, `signal/hiring-intent-...` |
| Blog & launches | `/blog`, `/changelog`, `/news` | `insight/...`, `proof/...` |
| News & funding | Google News, Crunchbase summary | `signal/funding-...`, `proof/...` |
| Reviews *(depth=deep only)* | G2, Capterra | `objection/...`, `alternative/...` |
| Communities *(depth=deep only)* | Reddit, HN search | `objection/...`, `insight/...` |

For each digest, require a `source_url` per claim. **Skip anything you cannot source** — a thin context beats a fabricated one.

### Step 5 — Synthesize and write per domain

For each domain you intend to populate, read the template first so frontmatter (`title`, `description`) and section structure are valid. Missing `title` or `description` **breaks the knowledge graph**.

```bash
# Always read the template first
cargo-ai context runtime read --path global/_template.md
cargo-ai context runtime read --path persona/_template.md
cargo-ai context runtime read --path icp/_template.md
cargo-ai context runtime read --path client/_template.md
cargo-ai context runtime read --path proof/_template.md
cargo-ai context runtime read --path signal/_template.md
```

Then synthesize one markdown file per atomic concept **directly** — the agent running this recipe is already an LLM, so don't double-hop through `cargo-ai orchestration action execute` to call Anthropic / OpenAI. That pattern is for batch synthesis inside a workflow node graph (Play/Tool); here, the agent has the digest in context and can produce the file body itself.

For each domain, the agent should:

1. Read the template (already done above) and the relevant digest from Step 4.
2. Produce one complete markdown body per concept, including frontmatter (`title` + `description`, both required), section structure from the template, and source URLs cited in `## Source` or `## Day-to-day`.
3. Write each file with `cargo-ai context runtime write`. **One concept per file** — if you're tempted to write two `## Persona` headings into one file, split into two files instead.

Example for `persona/` (after the agent has drafted `vp-engineering.md` from the careers digest):

```bash
cargo-ai context runtime write \
  --path persona/vp-engineering.md \
  --content "$(cat <<'EOF'
---
title: VP of Engineering
description: Senior engineering leader at 50-500 person SaaS companies, owns platform reliability and developer productivity.
---

## Role
- Title: VP of Engineering
- Seniority: Executive
- Function: Engineering
- Reports to: CTO or CEO

## KPIs
- ...

## Source
- https://acme.com/careers/vp-engineering
EOF
)"
```

### Step 6 — Verify and report

Re-run the graph to confirm the writes landed and surface any orphan cross-refs:

```bash
cargo-ai context graph get > /tmp/ctx-graph-after.json

# Node delta
echo "Before: $(jq '.nodes | length' /tmp/ctx-graph.json)"
echo "After:  $(jq '.nodes | length' /tmp/ctx-graph-after.json)"

# Orphans (nodes referenced but not authored)
jq -r '.edges[] | select(.target.exists == false) | "\(.source.path) → \(.target.path)"' /tmp/ctx-graph-after.json
```

Report to the user:
- Files written, grouped by domain.
- Domains skipped (from Step 2).
- Orphan cross-refs (these usually mean the synthesis referenced a `persona/x` that wasn't actually written — either author the missing file or rewrite the reference).

## Credit budget

| Step | Cost per call | Calls (depth=standard) | Subtotal |
|---|---|---|---|
| matchBusiness | 0.5 | 1 | 0.5 |
| enrichBusinessFirmographics | 0.5 | 1 | 0.5 |
| enrichBusinessTechnographics | 1 | 1 | 1 |
| enrichBusinessFundingAndAcquisitions | 0.5 | 1 | 0.5 |
| enrichBusinessFinancialMetrics | 0.5 | 1 | 0.5 |
| Public-source scrapes (sub-agents) | 0 (agent LLM tokens, not Cargo credits) | 4–6 | 0 |
| Synthesis (agent native) | 0 (agent LLM tokens, not Cargo credits) | 6–8 | 0 |
| context runtime write | 0 | 15–30 files | 0 |
| **Total (standard)** | | | **~3 Cargo credits** |
| **Total (deep)** adds review-site + community sub-agents | | | **~3 Cargo credits** |

Bootstrap is one-shot per workspace. Re-running is a no-op for already-seeded domains thanks to Step 2's skip-list.

## Action shape

`{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"}`. **No `connectorUuid` in `config`.**

## Output deliverable

A summary the agent presents to the user:

```
Context repo bootstrapped from acme.com:

Written (24 files):
  global/         3 files  (positioning, narrative, pricing)
  icp/            2 files  (mid-market-saas, enterprise-fintech)
  persona/        4 files  (vp-eng, head-of-data, cto, vp-product)
  client/         5 files  (3 enterprise, 2 mid-market)
  proof/          7 files  (4 metrics, 3 quotes)
  signal/         3 files  (hiring-intent-data-eng, series-c-funding, snowflake-adoption)

Skipped (already had content):
  alternative/, objection/, insight/

Orphan refs: none.

Next steps:
  - Open a fresh agent session so the seeded files load clean.
  - Refine from real sales calls — see Phase 2 of lifecycle.md.
```

## What this recipe does NOT do

- **No refinement from sales calls.** That's [Phase 2 of `lifecycle.md`](lifecycle.md#phase-2--refresh-from-real-calls) — deliberately human-in-the-loop. Auto-promoting call-derived claims into context produces plausible-sounding but shallow ICPs.
- **No `runtime edit` on existing files.** Bootstrap is additive only. Edits belong to the refresh phase.
- **No invention.** If a claim has no `source_url`, drop it. Thin context is recoverable; fabricated context erodes trust in everything downstream.
- **No promotion past the repetition threshold.** See [authoring rules of thumb](../conventions.md#authoring-rules-of-thumb). Bootstrap claims come from public sources, which count as one source — note the URL in the file body, don't promote to a confident assertion.

## When stuck — file a workspace report

If `context runtime write` fails repeatedly, the workspace has no context repo configured, or a template has changed shape and the writes no longer match, file via:

```bash
cargo-ai workspaceManagement report create \
  --title "bootstrap-from-domain: <one-line summary>" \
  --description "<exact command(s) tried, errorMessage, domain attempted, workspace.uuid>"
```

See [`../../../cargo-workspace-management/SKILL.md`](../../../cargo-workspace-management/SKILL.md).

# Knowledge-graph queries

`cargo-ai context graph get` returns the typed knowledge graph derived from every markdown/MDX file in the context repo. Pipe it through `jq` to slice it.

> Field names below (`nodes`, `slug`, `frontmatter`, `links`, etc.) are illustrative — run `cargo-ai context graph get | jq '. | keys'` once at the top of your session to confirm the exact shape for your workspace before scripting against it.

## List every node

```bash
cargo-ai context graph get | jq -r '.nodes[].slug' | sort
```

## Count entries per domain

```bash
cargo-ai context graph get \
  | jq -r '.nodes[].slug' \
  | awk -F/ '{print $1}' \
  | sort | uniq -c | sort -rn
```

## Find every persona

```bash
cargo-ai context graph get \
  | jq '.nodes[] | select(.slug | startswith("persona/")) | {slug, title: .frontmatter.title}'
```

## Find personas that link to a specific play

```bash
cargo-ai context graph get \
  | jq --arg target "play/funding-triggered-outbound" '
      .nodes[]
      | select(.slug | startswith("persona/"))
      | select((.links // []) | index($target))
      | .slug'
```

## Find dangling cross-references

Nodes referencing a `domain/slug` that doesn't exist in the graph:

```bash
cargo-ai context graph get | jq '
  . as $g
  | ($g.nodes | map(.slug)) as $slugs
  | $g.nodes[]
  | .slug as $from
  | (.links // [])[]
  | select(. as $t | ($slugs | index($t)) | not)
  | {from: $from, missing: .}
'
```

## Find plays with no proof attached

```bash
cargo-ai context graph get | jq '
  .nodes[]
  | select(.slug | startswith("play/"))
  | select(
      ((.links // []) | map(select(startswith("proof/"))) | length) == 0
    )
  | .slug
'
```

## Find objections with no proof point

Same pattern as plays, scoped to objections:

```bash
cargo-ai context graph get | jq '
  .nodes[]
  | select(.slug | startswith("objection/"))
  | select(
      ((.links // []) | map(select(startswith("proof/"))) | length) == 0
    )
  | {slug, title: .frontmatter.title}
'
```

## Show inbound references to a node

Which files cross-ref `proof/14-day-time-to-first-workflow`?

```bash
cargo-ai context graph get | jq --arg target "proof/14-day-time-to-first-workflow" '
  .nodes[]
  | select((.links // []) | index($target))
  | .slug
'
```

## Audit frontmatter completeness

Files missing `title` or `description`:

```bash
cargo-ai context graph get | jq '
  .nodes[]
  | select((.frontmatter.title // "") == "" or (.frontmatter.description // "") == "")
  | .slug
'
```

## Snapshot the graph to disk

Useful before a bulk edit so you can diff before/after:

```bash
cargo-ai context graph get > /tmp/graph.before.json
# ...make edits via context runtime write/edit...
cargo-ai context graph get > /tmp/graph.after.json
diff <(jq -r '.nodes[].slug' /tmp/graph.before.json | sort) \
     <(jq -r '.nodes[].slug' /tmp/graph.after.json | sort)
```

# Context repo lifecycle

The repeatable playbook for keeping a workspace's context repo healthy over time. Two phases: a one-time **bootstrap** from public sources (delegated to the [`bootstrap-from-domain.md`](bootstrap-from-domain.md) recipe), then a **refresh loop** driven by sales-call analysis (this doc's focus). Use this when standing up a new workspace, or as a periodic rehydration. Recommended cadence: every 2–4 weeks.

The phases are deliberately separated. Bootstrapping from public data gets you to a baseline fast; call-driven refinement is where the quality lives. Step 2 (turning a single call into context edits) cannot be safely automated end-to-end — keep a human in the loop on every edit.

## Before you start — confirm the target workspace

Each Cargo workspace maps to one company. `runtime write` and `runtime edit` push to **that workspace's** context repo immediately, so the first thing to do is confirm you're pointed at the right one. This matters most for consultants and operators managing several client workspaces.

```bash
cargo-ai whoami
# → user.email, workspace.uuid, workspace.name
```

Read back the `workspace.name` to the human and confirm it matches the company you intend to harden context for. **If the name is generic or ambiguous** — `"Main"`, `"Test"`, a person's name, an internal codename, anything that doesn't unambiguously identify the company — stop and ask: "What's the company name and canonical domain (e.g. `acme.com`)?" Workspace names are user-set and frequently don't match the customer-facing brand; the domain is the disambiguator. If you logged in without pinning a workspace, re-login with the right one:

```bash
cargo-ai login --oauth --workspace-uuid <uuid>
# or, non-interactive:
cargo-ai login --token <workspace-scoped-token>
```

If you're working across multiple clients in one session, prefix the workspace name in your notes for every claim you record — it's easy to attribute a Phase 2 insight to the wrong company otherwise.

## Phase 1 — Bootstrap from public sources

For the automatable seed step, use [`bootstrap-from-domain.md`](bootstrap-from-domain.md). It takes a domain, inventories existing files via `runtime browse` + `graph get` so it only fills gaps, enriches via cargo native, scrapes public sources in parallel sub-agents, and writes one file per atomic concept through `context runtime write`.

Once the bootstrap commit lands, open a new agent session so the seeded files load clean (rather than mixed with scratch context from the bootstrap run), then continue with Phase 2.

## Phase 2 — Refresh from real calls

Goal: replace assumptions with evidence. Public sources tell you what the company *says*; calls tell you what prospects *do*.

### 1. Pull the last ~3 months of sales calls

Export transcripts from Gong / Chorus / Fathom / etc. Three months is a good default — long enough to see patterns, short enough that the language is current. For low-volume workspaces, take what you have.

While you're there, capture a **call volume estimate** (transcripts / quarter). It drives the repetition threshold in step 2b.

### 2. Analyze one call at a time, human in the loop

For each call:

1. Have an agent summarize the call against the existing context: which personas were on the call, which objections came up, which proof points were referenced or missed, which signals would have flagged this account.
2. The agent proposes edits — new `objection/...`, updated `persona/...` pains, additional `proof/...` quotes, etc.
3. A human approves each edit before it lands via `runtime write` or `runtime edit`.

Do **not** batch this. An agent processing 30 calls in a loop overweights the loudest objection and underweights nuance.

### 2b. Apply a repetition threshold

A single call's claim is anecdote. Before promoting a claim into context, require it to surface across multiple calls:

| Workspace volume | Threshold |
|---|---|
| Call-rich (≥ 50 transcripts / quarter) | **3 occurrences** before commit |
| Medium volume | **2 occurrences** |
| New / call-poor (< 10 transcripts) | **1 occurrence** — note the source in the file body |

Track candidates in a scratch doc (or draft `insight/` entries) until they cross the threshold. The threshold applies to *claims* — objections, pains, missed proof points. It does not apply to direct facts a call confirms (a customer name, a quote attributable to one named person, a competitor explicitly mentioned).

### 3. Validate by generating sequences

Before treating the context as production-ready, run permutations through the workspace's sequence-generating play or agent and read the outputs. Useful permutations:

- A persona + a play + an objection
- Two different personas with the same play
- A play with and without a specific proof point

If the generated sequences read like a different company between permutations, the context has internal contradictions. Find them by walking the knowledge graph for orphans and conflicting cross-refs — see `graph-queries.md` for queries that catch the common cases.

### 4. Push to production

`runtime write` and `runtime edit` already push to the default branch — there is no separate deploy step. "Push to production" here means flipping downstream agents and plays to read from the refreshed context. If your workspace pins a specific branch or commit, update the pin now.

### 5. Repeat every 2–4 weeks

Re-run Phase 2 on a cadence. Re-run Phase 1 only when something changes materially in public sources (rebrand, new pricing, new persona launch). On each refresh:

- Snapshot `cargo-ai context graph get` before and after, then diff to see what moved.
- Retire context not referenced in the last two cycles — staleness is the failure mode, not coverage gaps.

## What not to automate

Full automation of steps 2 / 2b does not reach acceptable quality in practice. The nuance lives in three decisions: which claim is worth committing, which file it belongs in, and whether an existing file should be edited or a new one created. Keep a human on each of those.

# Response shapes

JSON response structures returned by Cargo CLI commands used in the `cargo-context` skill.

> Unlike the workspace storage / orchestration skills, the context CLI commands return shapes that depend on the underlying file content and on the graph derived from it. Field names below are the ones used throughout this skill's examples (`nodes`, `slug`, `frontmatter`, `links`, etc.); for a given workspace, confirm the exact shape with `--help` and a one-shot invocation before scripting against it.

## Error shape (every command)

Failed commands exit non-zero and return:

```json
{
  "errorMessage": "..."
}
```

`cargo-ai context runtime edit` fails with this shape when `--old-string` matches zero or multiple times in the target file. See `references/troubleshooting.md`.

## cargo-ai context runtime browse

Lists entries at the sandbox root (or under `--path`). Returns the directory listing — file and folder names under the requested path. Combine with `cargo-ai context runtime read --path <file>` to inspect any entry.

```bash
cargo-ai context runtime browse
cargo-ai context runtime browse --path persona
```

Run once at the top of a session to confirm the exact JSON shape for your workspace.

## cargo-ai context runtime read

Returns the file content at `--path`, optionally restricted to `--start-line`/`--end-line` (1-indexed, inclusive). Use this to read frontmatter + body before editing.

```bash
cargo-ai context runtime read --path persona/vp-sales-mid-market.md
cargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40
```

## cargo-ai context runtime write

Creates (or overwrites) the file at `--path` and pushes a commit to the default branch. Returns the commit metadata. The `--commit-message` flag controls the commit subject.

```bash
cargo-ai context runtime write \
  --path persona/vp-sales-mid-market.md \
  --content "<file body with frontmatter>" \
  --commit-message "Add VP of Sales mid-market persona"
```

On failure it returns the generic error shape (see [Error shape](#error-shape-every-command)); the context-specific case to know is a denied write under `.files/` (update those via Content instead). Frontmatter is **not** validated — a file missing `title`/`description` or with malformed frontmatter is written, not rejected. Failure reasons are enumerated in `references/troubleshooting.md`.

## cargo-ai context runtime edit

Replaces a single exact substring in the file at `--path` and pushes a commit. `--old-string` must match **exactly once** — read the file with `runtime read` first and copy the substring verbatim, whitespace included. Pass an empty `--new-string` to delete the match. Returns the commit metadata on success.

```bash
cargo-ai context runtime edit \
  --path global/positioning.md \
  --old-string "We help RevOps automate workflows." \
  --new-string "We help RevOps run AI-native GTM motions." \
  --commit-message "Refresh positioning one-liner"
```

On failure it returns the generic error shape — most often because `--old-string` matched zero or multiple times. Frontmatter is not validated, so an edit that strips `title`/`description` still applies. Failure reasons are enumerated in `references/troubleshooting.md`.

## cargo-ai context runtime execute

Runs a shell command in the sandbox and returns its stdout / stderr / exit code. **Does not push** any file changes — use only for inspection (`grep`, `ls`, `pwd`, `find`). `--args` is a JSON array of string arguments; omit for a no-arg command.

```bash
cargo-ai context runtime execute --command grep --args '["-r","-l","persona/vp-sales-mid-market","."]'
cargo-ai context runtime execute --command ls --args '["-1","persona"]'
cargo-ai context runtime execute --command pwd
```

## cargo-ai context graph get

Returns the typed knowledge graph derived from every markdown/MDX file in the context repo. Shape used throughout `references/examples/graph-queries.md`:

```json
{
  "nodes": [
    {
      "slug": "persona/vp-sales-mid-market",
      "frontmatter": {
        "title": "VP of Sales, mid-market",
        "description": "Owns pipeline, quota, and rep productivity at a 200–2,000-person company."
      },
      "links": [
        "medium/linkedin-outbound",
        "medium/exec-warm-intro",
        "objection/we-already-have-an-ai-sdr"
      ]
    }
  ]
}
```

**Key fields:**

- `nodes[].slug` — `domain/slug` (no `.md` extension), the canonical identifier used in cross-references.
- `nodes[].frontmatter` — parsed YAML frontmatter. `title` and `description` are required on every file.
- `nodes[].links` — outbound `domain/slug` references found in the body. Missing or empty when the file links nowhere.

For ready-to-run queries (count per domain, dangling references, plays missing proof, inbound references to a node), see `references/examples/graph-queries.md`.

# Troubleshooting

Common errors and solutions for `cargo-ai context` commands.

## General

**`{"errorMessage": "..."}`**
All failed commands exit non-zero and return an error JSON. Read the `errorMessage` for the specific issue.

**`Unauthorized` / `403`**
Your API token may lack the required permissions, or the workspace's context repository isn't configured. Verify with `cargo-ai whoami`; if a context repo hasn't been set up for the workspace, ask an admin (or do it via the Cargo app under workspace settings).

## Runtime — browse / read

**Path not found**
The path does not exist in the runtime sandbox. Use `cargo-ai context runtime browse --path <parent>` to confirm the file layout before reading. Paths are relative to the repo root, no leading slash (`persona/vp-sales.md`, not `/persona/vp-sales.md`).

**Out-of-range lines**
`--start-line` and `--end-line` are 1-indexed and inclusive on both ends. If they fall outside the file's line count the read fails. Read the file without a range first to confirm length, or omit one end (e.g. only `--start-line`) to read to EOF.

## Runtime — write

**Push fails / commit not appearing**
`write` pushes to the context repo's default branch. Pushes fail if the configured GitHub connector lost permissions or the branch was deleted/renamed. Verify the connector via `cargo-ai connection connector list` and check the default-branch setting in the Cargo app under workspace settings.

**No `_template.md` for the domain**
Some workspaces customize their context repo. If a domain doesn't ship a template, browse the domain (`cargo-ai context runtime browse --path <domain>`) and model the new file after an existing entry.

**Missing / empty / malformed frontmatter (not an error)**
Frontmatter is a strong convention but **not validated** — `write` never rejects a file for a missing `title`/`description` or malformed YAML; the file is committed as-is. The graph fails soft: a missing `title` falls back to the filename, the node summary falls back to the body's first paragraph, and a malformed frontmatter block is stripped so it doesn't leak into the summary. Nothing dangles, but the node indexes poorly — set `title` (and a `summary:` if you want a specific summary) on every file. Note the graph reads `summary`, not `description`.

**Other `notWritten` reasons**
`write` can fail with `repositoryNotFound`, `syncConflict`, `syncFailed`, `failedToWrite`, or `deniedPath` (writing under `.files/` — update those via Content instead). `syncFailed` / `failedToWrite` / `deniedPath` carry an `errorMessage`. See `references/response-shapes.md`.

## Runtime — edit

**`--old-string` not found**
`--old-string` did not match any substring in the file. Whitespace must match exactly — escape newlines (`\n`) where present, and watch for trailing spaces. Read the file first and copy the substring verbatim.

**`--old-string` matches more than once**
`edit` requires the match to be unique. Add enough surrounding context to make the match unique (extend with the line before or after), or do multiple targeted edits in sequence.

**Other `notEdited` reasons**
Besides the `--old-string` cases above, `edit` can return `fileNotFound`, `noOp` (the new string equals the old), `syncConflict` / `syncFailed` (push race), `failedToEdit`, or `deniedPath` (editing under `.files/`). Frontmatter is **not** validated, so an edit that removes or empties `title`/`description` still applies — keep the block intact so the node stays discoverable.

**Edits not appearing in GitHub**
`edit` commits and pushes; `execute` does **not** push. If you ran a shell command that modified files (e.g. `sed -i`, redirecting into a file), the change stays in the ephemeral sandbox and is discarded. Use `write` or `edit` for any change that should land in git.

## Runtime — execute

**Command output is empty / unexpected**
The runtime sandbox starts clean for each call; mutations from prior `execute` calls are not preserved between invocations. Don't rely on state across `execute` runs — chain operations in a single `--command` (e.g. via `sh -c`) instead.

**Side effects not pushed**
By design, `execute` does not commit. Use `execute` for inspection (`grep`, `ls`, `find`, counting, validation); use `write`/`edit` for any persistent change.

**Argument escaping**
`--args` is a **JSON array** of strings, not a shell-quoted list. Wrap the whole thing in single quotes so the shell doesn't mangle the JSON:

```bash
# Correct
cargo-ai context runtime execute --command grep --args '["-r","vp-sales","."]'

# Wrong — shell will eat the inner double quotes
cargo-ai context runtime execute --command grep --args ["-r","vp-sales","."]
```

## Graph

**Stale results after writes**
`graph get` is cached. After a series of writes, expect a short delay before the graph reflects them. Re-run after a few seconds, or restructure logic so it does not depend on immediately-fresh graph data.

**Broken cross-references**
If a file references `domain/slug` and that target doesn't exist, the link won't resolve in the graph. Use `cargo-ai context runtime browse --path <domain>` to verify the target exists before writing the reference, or pipe `graph get` through `jq` to enumerate dangling refs (see `references/examples/graph-queries.md`).

## When to escalate

If the CLI errors and `--help` plus the notes above don't get you unstuck — **file a workspace management report** rather than retrying silently. See [`cargo-workspace-management/SKILL.md`](../../cargo-workspace-management/SKILL.md) (Reports section).

```bash
cargo-ai workspaceManagement report create \
  --title "context <subcommand> fails with <errorMessage>" \
  --description "Ran: cargo-ai context ...   Got: {...errorMessage...}   Expected: ..."
```

{
  "$comment": "Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .",
  "name": "cargo-context",
  "version": "1.2.2",
  "documents": [
    {
      "path": "SKILL.md",
      "kind": "entrypoint",
      "title": "Cargo CLI — Context"
    },
    {
      "path": "references/conventions.md",
      "kind": "reference",
      "title": "Context repo conventions"
    },
    {
      "path": "references/examples/authoring.md",
      "kind": "example",
      "title": "Authoring examples"
    },
    {
      "path": "references/examples/bootstrap-from-domain.md",
      "kind": "example",
      "title": "Bootstrap workspace context from a domain"
    },
    {
      "path": "references/examples/graph-queries.md",
      "kind": "example",
      "title": "Knowledge-graph queries"
    },
    {
      "path": "references/examples/lifecycle.md",
      "kind": "example",
      "title": "Context repo lifecycle"
    },
    {
      "path": "references/response-shapes.md",
      "kind": "reference",
      "title": "Response shapes"
    },
    {
      "path": "references/troubleshooting.md",
      "kind": "reference",
      "title": "Troubleshooting"
    }
  ],
  "contentHash": "7b32962da50a852e960ae7a51c335dfdb22ad586ab621b0b8ad7b6b42b807a42"
}

---
name: cargo-context
description: "Read and write the workspace GTM knowledge base — the git-backed repository of markdown describing ICPs, personas, plays, proof points, objections, competitors, and signals — plus its runtime sandbox and typed knowledge graph. Triggers: \"document our ICP\", \"write up this persona\", \"what is our positioning\", \"add a battlecard\", \"capture this objection\", \"what do we know about <segment>\", \"update our context\", \"what is in the context repo\", \"who do we sell to\". Skip when: discovering who actually buys from you by analyzing won/lost data — that is cargo-gtm (this skill writes the conclusion down, it does not derive it); storing structured records rather than prose — use cargo-storage; attaching documents to an agent for RAG — use cargo-content."
version: "1.2.2"
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 — Context

The **context** is a git-backed repository of typed markdown/MDX files that captures a workspace's GTM knowledge (company narrative, ICPs, personas, plays, proof, objections, etc.) and is read/written by both humans and agents. The `cargo-ai context` domain has two subdomains you'll use:

- **runtime** — browse, read, write, edit, and execute against the workspace's runtime sandbox (a checked-out copy of the context repo). `write`/`edit` are pushed to the default branch; `execute` runs are **not** pushed.
- **graph** — build/load the knowledge graph derived from every markdown/MDX file in the context repo.

> The canonical example of a context repository is [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces). Read its `README.md` to understand the domain layout and file conventions before writing new entries.
> For uploading runtime-independent files (CSVs, PDFs) used in batch runs, use [`cargo-workspace-management`](../cargo-workspace-management/SKILL.md) (`cargo-ai workspaceManagement file upload`) instead.
> For RAG file attachments to agents, use [`cargo-ai`](../cargo-ai/SKILL.md) (`cargo-ai content file upload`).

> See `references/conventions.md` for the full context repo structure and per-domain templates.
> See `references/response-shapes.md` for the JSON shapes returned by each `cargo-ai context` command.
> See `references/troubleshooting.md` for common errors and how to fix them.
> See `references/examples/authoring.md` for end-to-end add / edit / delete recipes.
> See `references/examples/lifecycle.md` for the bootstrap + refresh-from-calls playbook.
> See `references/examples/graph-queries.md` for inspecting the knowledge graph.

## Bootstrap

Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.

```bash
npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write
```

Every command prints JSON to stdout; failures exit non-zero with `{"errorMessage": "..."}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. `runtime write` and `runtime edit` commit and push to the workspace's context repo, so confirming `workspace.name` first is non-negotiable. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.

## Discover the context first

Before editing anything, see what's in the context repo:

```bash
cargo-ai context runtime browse                 # list entries at the runtime sandbox root
cargo-ai context graph get                      # full knowledge graph derived from the repo's md/mdx files
```

## Quick reference

```bash
# Runtime sandbox (checked-out copy of the context repo)
cargo-ai context runtime browse [--path <path>]
cargo-ai context runtime read --path <path> [--start-line <n>] [--end-line <n>]
cargo-ai context runtime write --path <path> --content <content> [--commit-message <message>]
cargo-ai context runtime edit --path <path> --old-string <old> --new-string <new> [--commit-message <message>]
cargo-ai context runtime execute --command <command> [--args <json>]

# Knowledge graph
cargo-ai context graph get
```

## Runtime sandbox

The **runtime sandbox** is a checked-out, executable copy of the context repository. It's the surface you use to read and modify context files, and to run commands against them.

Two important behaviors to remember:

- **`write` and `edit` push to the default branch** of the context repo. They are not local-only.
- **`execute` does *not* push.** Changes made to files by a shell command run via `execute` stay in the sandbox and are discarded — use `execute` for builds, tests, or inspection, not for committing edits.

**Uploaded content files are available read-only under `.files/`.** The workspace's `content file` uploads (PDFs, CSVs, text — see [`cargo-content`](../cargo-content/SKILL.md)) appear in the sandbox under a `.files/` directory, so a command run via `execute` (or `read`/`browse`) can consume them — e.g. `cargo-ai context runtime execute --command ls --args '["-1",".files"]'`. It sits **outside the committed context tree**: the sandbox's auto-commit skips it, so nothing under `.files/` is ever pushed to the context repo, and you can't add or change content files from here (use `cargo-ai content file …` instead).

Because writes push immediately, **confirm the target workspace before the first `write`/`edit`**:

```bash
cargo-ai whoami   # → workspace.uuid, workspace.name
```

Read the workspace name back to the user. If the session is for a specific client, make sure `workspace.name` matches before authoring anything — there is no dry-run mode. If `workspace.name` is generic or ambiguous (e.g. "Main", "Test", a person's name, an internal codename), don't guess — ask the user for the company name and canonical domain (`example.com`) and confirm both before the first write. If you logged in without pinning a workspace, re-run `cargo-ai login --oauth --workspace-uuid <uuid>` (or `--token <workspace-scoped-token>` for non-interactive use).

Edits derived from sales-call analysis should be applied **one at a time with human review**, not batched. Looping an agent over many calls tends to overweight the loudest signal and miss nuance — see `references/examples/lifecycle.md` for the call-refresh playbook.

### Browse and read

```bash
# List entries at the root of the runtime sandbox
cargo-ai context runtime browse

# List entries under a subpath (e.g. a domain folder like persona/ or play/)
cargo-ai context runtime browse --path persona

# Read a full file
cargo-ai context runtime read --path persona/vp-sales-mid-market.md

# Read only a line range (1-indexed, inclusive on both ends)
cargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40
```

### Write a new file

`write` creates (or overwrites) a file and pushes a commit to the default branch.

Begin every `.md`/`.mdx` file with a YAML frontmatter block setting `title` and `description`. Frontmatter is **not validated** — a file with missing, empty, or malformed frontmatter is still written and committed; it just indexes poorly in the graph (a missing `title` falls back to the filename, the node summary to the first paragraph). `write` can still fail for other reasons — `repositoryNotFound`, `syncConflict`, `syncFailed`, `failedToWrite`, or `deniedPath` (e.g. writing under `.files/`); see `references/response-shapes.md`.

```bash
cargo-ai context runtime write \
  --path persona/vp-sales-mid-market.md \
  --content "$(cat <<'EOF'
---
title: VP of Sales, mid-market
description: Owns pipeline, quota, and rep productivity at a 200–2,000-person company.
---

## Role
- Title: VP of Sales
- Seniority: Executive
- Function: Revenue
- Reports to: CRO or CEO

## KPIs
- New ARR, win rate, pipeline coverage, rep ramp time

## Pains
- Pipeline gaps, slow ramp, low rep activity, forecasting drift

## Motivations
- Hit the number, build a repeatable motion, get visibility

## Day-to-day
Forecast calls, deal reviews, pipeline reviews, 1:1s with frontline managers.

## Preferred channels
- medium/linkedin-outbound
- medium/exec-warm-intro

## Common objections
- objection/we-already-have-an-ai-sdr

## How we land
Lead with pipeline-coverage math, not features.
EOF
)" \
  --commit-message "Add VP of Sales mid-market persona"
```

### Edit an existing file

`edit` replaces a single exact substring. `--old-string` must occur **exactly once** in the file; pass an empty `--new-string` to delete the match.

`edit` does not validate frontmatter — an edit that strips or empties `title`/`description` still applies, so keep the block intact to keep the node discoverable. `edit` can fail for other reasons, though: `stringNotFound` / `stringNotUnique` (the `--old-string` match), `fileNotFound`, `noOp` (new string equals old), `syncConflict` / `syncFailed`, `failedToEdit`, or `deniedPath`.

```bash
# Replace one specific sentence
cargo-ai context runtime edit \
  --path global/positioning.md \
  --old-string "We help RevOps automate workflows." \
  --new-string "We help RevOps run AI-native GTM motions." \
  --commit-message "Refresh positioning one-liner"

# Delete a line (pass empty --new-string)
cargo-ai context runtime edit \
  --path persona/vp-sales-mid-market.md \
  --old-string "\n- Outdated stat: 4.2x pipeline\n" \
  --new-string ""
```

For larger restructures, prefer `write` (full-file overwrite) over many sequential `edit` calls.

### Execute a command in the sandbox

`execute` runs a shell command in the sandbox. Useful for inspecting structure or running checks; **changes are not pushed**.

```bash
# Find every file that cross-references a specific slug
cargo-ai context runtime execute \
  --command grep \
  --args '["-r","-l","persona/vp-sales-mid-market","."]'

# Count entries per domain
cargo-ai context runtime execute --command ls --args '["-1","persona"]'

# Run a one-shot script (no quotes/escaping needed inside --command beyond JSON for args)
cargo-ai context runtime execute --command pwd
```

`--args` is a JSON array of string arguments. Omit it for a no-arg command.

## Context repository structure and conventions

The Cargo context repo is a typed knowledge base. The canonical example — and the source of the conventions below — is [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces); read its `README.md` and `_template.md` files in each domain before writing new entries. For the full domain reference, see `references/conventions.md`.

### Domains

| Domain | Purpose |
|---|---|
| `global/` | Company-level context: mission, voice, positioning, narrative, pricing |
| `icp/` | Ideal Customer Profile segments |
| `persona/` | Buyer personas (roles inside an ICP) |
| `jtbd/` | Jobs-to-be-done framings |
| `alternative/` | Competitors, substitutes, status quo |
| `client/` | Customer profiles, case studies, reference accounts |
| `insight/` | Market insights and observations |
| `medium/` | Channel playbooks (email, LinkedIn, cold call, etc.) |
| `objection/` | Objections + responses + proof |
| `play/` | GTM plays (signal → audience → channel → sequence → outcome) |
| `proof/` | Atomic proof points (metrics, quotes, case data) |
| `signal/` | Buying signals and intent triggers |

### File conventions

- **Filename:** `kebab-case.md` (e.g. `vp-sales-mid-market.md`).
- **Frontmatter:** start every `.md`/`.mdx` file with YAML frontmatter setting `title` and `description`. This is a **strong convention, not enforced** — a write with missing, empty, or malformed frontmatter is still created and committed; it just indexes poorly. The graph reads `title` (fallback: filename) and `summary` (fallback: the file's first paragraph); it does **not** read `description`, so add a `summary:` if you want to control the node summary. See [Source references and graph edges](#source-references-and-graph-edges).
- **Cross-references:** use the `domain/slug` form, **no `.md` extension** (e.g. `persona/vp-sales-mid-market`). To register as a graph **edge** a reference must use one of the three link forms below — a bare `domain/slug` (or file path) in plain prose creates no edge.
- **Templates:** each domain ships an `_template.md`. Read it (`cargo-ai context runtime read --path persona/_template.md`) before authoring a new entry. `_template.*` files are excluded from the graph — never reference them.

### Source references and graph edges

The knowledge graph is built from every `.md`, `.mdx`, `.yaml`, and `.yml` file in the repo (any folder; only `.git/` is excluded). Each file is a node, but **edges are created only from three forms** — anything else is invisible to the graph:

1. **Frontmatter `references:` list** (preferred for source citations — keeps prose clean):
   ```yaml
   ---
   title: AgoraPulse expansion thesis
   description: Why AgoraPulse is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---
   ```
2. **A Markdown link** in the body — standard `[label]` followed immediately by `(path)` syntax, where the target is the file path, e.g. an anchor linking to `outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md`.
3. **Wikilinks** in the body (extension optional): `[[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]`.

Key constraints:

- **Never cite a source as a bare path in prose** (e.g. a `Source:` line that just mentions `outputs/sales-notes/foo.md` as text) — it is not parsed and creates **no** edge.
- **Prefer root-relative paths** (resolved from the repo root first, then relative to the citing file) so links work regardless of where the document lives.
- **Extensions are optional** — the resolver auto-tries `.md`, `.mdx`, `.yaml`, `.yml` in that order. Including the extension is fine.
- **The target must exist** or the edge is **broken** (a dead link in the graph UI). Verify with `runtime browse` before citing.
- For docs with a **Source**/**Evidence** section, cite the files in frontmatter `references:`; use inline markdown links when the citation needs surrounding prose. Full rules: `references/conventions.md`.

### Workflow: add a new entry

1. Confirm the target domain and copy its template:
   ```bash
   cargo-ai context runtime read --path persona/_template.md
   ```
2. `write` a new file at `<domain>/<slug>.md` with `title` + `description` and the body sections filled in.
3. Add cross-refs (`domain/slug`) where useful — keep them bidirectional when it makes sense.
4. Rebuild the knowledge graph to verify the new entry and its links:
   ```bash
   cargo-ai context graph get
   ```

For full per-domain templates and worked examples, see `references/conventions.md` and `references/examples/authoring.md`.

### Workflow: bootstrap and refresh

To stand up a new workspace's context repo from scratch, or to refresh an existing one on a cadence, follow the two-phase lifecycle in `references/examples/lifecycle.md`:

1. **Bootstrap (one-time):** seed `global/`, `persona/`, `client/`, `proof/`, `objection/`, `signal/` from public sources, then open a fresh agent session against the seeded repo. For the prescriptive, automatable version (domain in → files out, idempotent, with credit budget), use `references/examples/bootstrap-from-domain.md`.
2. **Refresh (every 2–4 weeks):** pull the last ~3 months of sales-call transcripts → analyze one at a time, human-in-the-loop → apply a repetition threshold before promoting any claim to context → validate by generating sequence permutations → diff the graph before/after and retire stale entries.

The repetition threshold (how many calls a claim must appear in before it lands in context) is documented in `references/conventions.md`.

## Knowledge graph

`context graph get` builds (or loads from cache) the knowledge graph over every markdown/MDX file in the context repo. Use it to:

- Audit cross-references between domains (e.g. find personas that link to plays with no proof attached).
- Discover what already exists before writing a new entry (avoid duplicates).
- Power downstream agents that need the typed structure of the workspace's context.

```bash
cargo-ai context graph get
```

The response includes the parsed frontmatter and outbound `domain/slug` references for each node — pipe it through `jq` to slice it. See `references/examples/graph-queries.md` for ready-to-run queries.

## Help

Every command supports `--help`:

```bash
cargo-ai context --help
cargo-ai context runtime browse --help
cargo-ai context runtime read --help
cargo-ai context runtime write --help
cargo-ai context runtime edit --help
cargo-ai context runtime execute --help
cargo-ai context graph get --help
```