Cargo Context

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`. 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-ai workspaceManagement file upload) instead.

For RAG file attachments to agents, use `cargo-ai` (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.

Prerequisites

See `../cargo/references/prerequisites.md` for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below — runtime write and runtime edit push commits to the workspace's context repo, so confirming workspace.name first is non-negotiable.

Discover the context first

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

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

# 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`) 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`:

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

# 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.

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.

# 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.

# 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`; 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

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.
• 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):

   ---
   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:

   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:

   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.

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:

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

Context repo conventions

The conventions below are inherited from the canonical context repository `getcargohq/cargo-workspaces`. When in doubt, read its README.md and the _template.md file in the relevant domain.

Domains

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.
• 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):

   ---
   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):

   [[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:

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

global/_template.md

---
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

---
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

---
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

---
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:

---
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.

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

# 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

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

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:

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).

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

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

# 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:

   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

# 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`. 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.

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:

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), 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:

# Match the domain to a cargo business_id
cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"cargo","actionSlug":"matchBusiness","config":{}}' \
  --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,config:{}}')" \
    --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:

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.

# 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):

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:

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

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>","config":{}}. 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` — 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. 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:

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`.

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

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

Count entries per domain

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

Find every persona

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

Find personas that link to a specific play

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:

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

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:

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?

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:

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:

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` 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.

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:

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`. 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:

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:

{
  "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.

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.

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.

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); 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.

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.

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:

{
  "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:

# 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` (Reports section).

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