cargo-context — Skillopedia

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 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). / are pushed to the default branch, and auto-commits and pushes any tracked working-tree changes its command leaves behind. - graph — build/load the knowledge graph derived from ev…

...'` quoting for multi-line matches.\n\n`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), `failedToEdit` (including a push that did not land), or `deniedPath`.\n\n```bash\n# Replace one specific sentence\ncargo-ai context runtime edit \\\n --path global/positioning.md \\\n --old-string \"We help RevOps automate workflows.\" \\\n --new-string \"We help RevOps run AI-native GTM motions.\" \\\n --commit-message \"Refresh positioning one-liner\"\n\n# Delete a line (pass empty --new-string)\ncargo-ai context runtime edit \\\n --path persona/vp-sales-mid-market.md \\\n --old-string

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\\n- Outdated stat: 4.2x pipeline\\n' \\\n --new-string \"\"\n```\n\nFor larger restructures, prefer `write` (full-file overwrite) over many sequential `edit` calls.\n\n### Execute a command in the sandbox\n\n`execute` runs a shell command in the sandbox (90-second timeout). Useful for inspecting structure or running checks; **tracked file changes it leaves are committed and pushed**, so keep inspection commands read-only.\n\n```bash\n# Find every file that cross-references a specific slug\ncargo-ai context runtime execute \\\n --command grep \\\n --args '[\"-r\",\"-l\",\"persona/vp-sales-mid-market\",\".\"]'\n\n# Count entries per domain\ncargo-ai context runtime execute --command ls --args '[\"-1\",\"persona\"]'\n\n# Run a one-shot script (no quotes/escaping needed inside --command beyond JSON for args)\ncargo-ai context runtime execute --command pwd\n```\n\n`--args` is a JSON array of string arguments. Omit it for a no-arg command.\n\n## Context repository structure and conventions\n\nThe 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`.\n\n### Domains\n\n| Domain | Purpose |\n|---|---|\n| `global/` | Company-level context: mission, voice, positioning, narrative, pricing |\n| `icp/` | Ideal Customer Profile segments |\n| `persona/` | Buyer personas (roles inside an ICP) |\n| `jtbd/` | Jobs-to-be-done framings |\n| `alternative/` | Competitors, substitutes, status quo |\n| `client/` | Customer profiles, case studies, reference accounts |\n| `insight/` | Market insights and observations |\n| `medium/` | Channel playbooks (email, LinkedIn, cold call, etc.) |\n| `objection/` | Objections + responses + proof |\n| `play/` | GTM plays (signal → audience → channel → sequence → outcome) |\n| `proof/` | Atomic proof points (metrics, quotes, case data) |\n| `signal/` | Buying signals and intent triggers |\n\n### File conventions\n\n- **Filename:** `kebab-case.md` (e.g. `vp-sales-mid-market.md`).\n- **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: `description`, then the file's first paragraph), so add a `summary:` only if you want the node summary to differ from `description`. See [Source references and graph edges](#source-references-and-graph-edges). The exception is context declared in a project (`defineContext`, see `../cargo-project/SKILL.md`): there `project check`/`plan`/`deploy` fail on frontmatter that doesn't parse and on a `references:` entry, `[[wikilink]]` or relative `.md` link that matches no file declared under `files` — including one that exists in the workspace repo but not in code. A missing `title`/`description` still passes.\n- **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.\n- **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.\n\n### Source references and graph edges\n\nThe 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:\n\n1. **Frontmatter `references:` list** (preferred for source citations — keeps prose clean):\n ```yaml\n ---\n title: AgoraPulse expansion thesis\n description: Why AgoraPulse is ready for a multi-thread expansion play.\n references:\n - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md\n ---\n ```\n2. **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`.\n3. **Wikilinks** in the body (extension optional): `[[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]`.\n\nKey constraints:\n\n- **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.\n- **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.\n- **Extensions are optional for wikilinks and frontmatter `references:`**: the resolver auto-tries `.md`, `.mdx`, `.yaml`, `.yml` in that order. A **Markdown link** only counts as an edge when its target ends in `.md`, `.mdx`, `.yaml`, or `.yml`, so keep the extension there.\n- **The target must exist** or the edge is **broken** (a dead link in the graph UI). Verify with `runtime browse` before citing.\n- 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`.\n\n### Workflow: add a new entry\n\n1. Confirm the target domain and copy its template:\n ```bash\n cargo-ai context runtime read --path persona/_template.md\n ```\n2. `write` a new file at `\u003cdomain>/\u003cslug>.md` with `title` + `description` and the body sections filled in.\n3. Add cross-refs (`domain/slug`) where useful — keep them bidirectional when it makes sense.\n4. Rebuild the knowledge graph to verify the new entry and its links:\n ```bash\n cargo-ai context graph get\n ```\n\nFor full per-domain templates and worked examples, see `references/conventions.md` and `references/examples/authoring.md`.\n\n### Workflow: bootstrap and refresh\n\nTo 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`:\n\n1. **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`.\n2. **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.\n\nThe repetition threshold (how many calls a claim must appear in before it lands in context) is documented in `references/conventions.md`.\n\n## Knowledge graph\n\n`context graph get` builds (or loads from cache) the knowledge graph over every markdown/MDX file in the context repo. Use it to:\n\n- Audit cross-references between domains (e.g. find personas that link to plays with no proof attached).\n- Discover what already exists before writing a new entry (avoid duplicates).\n- Power downstream agents that need the typed structure of the workspace's context.\n\n```bash\ncargo-ai context graph get\n```\n\nThe response is `{\"graph\": {\"nodes\", \"edges\", \"broken\", \"computedAt\"}}`: each node carries `id` (the file path, extension included), `title`, `summary`, and `cluster` (top-level folder); each edge carries `source`, `target`, and `origin` (`frontmatter`, `wikilink`, or `mdlink`); `broken` lists edges whose target does not exist. Pipe it through `jq` to slice it. See `references/examples/graph-queries.md` for ready-to-run queries.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai context --help\ncargo-ai context runtime browse --help\ncargo-ai context runtime read --help\ncargo-ai context runtime write --help\ncargo-ai context runtime edit --help\ncargo-ai context runtime execute --help\ncargo-ai context graph get --help\n```","attachment_filenames":["references/conventions.md","references/examples/authoring.md","references/examples/bootstrap-from-domain.md","references/examples/graph-queries.md","references/examples/lifecycle.md","references/response-shapes.md","references/troubleshooting.md","skill-metadata.json"],"attachments":[{"filename":"references/conventions.md","content":"# Context repo conventions\n\nThe 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.\n\n## Domains\n\n| Domain | Purpose |\n|---|---|\n| `global/` | Company-level context: mission, voice, positioning, narrative, pricing |\n| `icp/` | Ideal Customer Profile segments |\n| `persona/` | Buyer personas (roles inside an ICP) |\n| `jtbd/` | Jobs-to-be-done framings |\n| `alternative/` | Competitors, substitutes, status quo |\n| `client/` | Customer profiles, case studies, reference accounts |\n| `insight/` | Market insights and observations |\n| `medium/` | Channel playbooks (email, LinkedIn, cold call, etc.) |\n| `objection/` | Objections + responses + proof |\n| `play/` | GTM plays (signal → audience → channel → sequence → outcome) |\n| `proof/` | Atomic proof points (metrics, quotes, case data) |\n| `signal/` | Buying signals and intent triggers |\n\n## File conventions\n\n- **Filename:** `kebab-case.md` (e.g. `vp-sales-mid-market.md`). Use ASCII letters, digits, and hyphens only.\n- **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. (A project's `defineContext` fails `plan` on frontmatter that doesn't parse and on links to undeclared files; a missing `title`/`description` still passes.) The graph reads `title` (fallback: filename) and `summary` (fallback: `description`, then the first paragraph). See [Source references and the knowledge graph](#source-references-and-the-knowledge-graph).\n- **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.\n- **Templates:** each domain ships an `_template.md`. Read it (`cargo-ai context runtime read --path \u003cdomain>/_template.md`) before authoring a new entry. `_template.*` files are excluded from the graph — never reference them.\n- **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.\n\n## Source references and the knowledge graph\n\nThe 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:\n\n1. **Frontmatter `references:` list** (preferred for source citations — keeps prose clean, and the edge carries a `frontmatter` origin):\n\n ```yaml\n ---\n title: AgoraPulse expansion thesis\n description: Why the AgoraPulse account is ready for a multi-thread expansion play.\n references:\n - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md\n ---\n ```\n\n2. **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`.\n\n3. **Wikilinks in the body** (extension optional):\n\n ```markdown\n [[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]\n ```\n\n### Linking rules\n\n- **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.\n- **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.\n- **Extensions are optional for wikilinks and frontmatter `references:`.** The resolver auto-tries `.md`, `.mdx`, `.yaml`, `.yml` (in that preference order). Including the extension is fine too. A **Markdown link** only registers when its target ends in `.md`, `.mdx`, `.yaml`, or `.yml`, so keep the extension there.\n- **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 \u003cdir>`).\n- **`_template.*` files are excluded** from the graph — don't reference `_template.md` / `.mdx` / `.yaml` / `.yml`.\n- **YAML data files:** `title`, `summary` (fallback: `description`), and `references` are read from top-level keys; YAML bodies produce no link edges.\n- **Node title/summary:** titles come from frontmatter `title:` (fallback: filename); summaries from frontmatter `summary:` (fallback: `description`, then the body's first paragraph, truncated to 280 chars). Set a `summary:` only if you want the node summary to differ from `description`. Always set `title` so the node is discoverable.\n\n### Citing sources in insight / learning documents\n\nWhen 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.\n\n## How to read the context\n\nStart at `global/` for company context. Walk `icp/` → `persona/` → `jtbd/` to understand the buyer. Use `play/` for outbound motions and `objection/` + `proof/` for live conversations.\n\n## Domain templates\n\nThe most commonly authored domains. For domains not shown here (`icp/`, `jtbd/`, `alternative/`, `client/`, `insight/`, `medium/`, `signal/`), read the in-repo `_template.md` directly:\n\n```bash\ncargo-ai context runtime read --path icp/_template.md\ncargo-ai context runtime read --path signal/_template.md\n# ...\n```\n\n### `global/_template.md`\n\n```markdown\n---\ntitle:\ndescription:\n---\n\n## Summary\n\n_One-line version._\n\n## Detail\n\n_Full version. Mission, voice, positioning, narrative, pricing — whatever this entry is._\n\n## Source\n\n_Where this comes from. Founder note, brand doc, board deck, prior conversation._\n```\n\n### `persona/_template.md`\n\n```markdown\n---\ntitle:\ndescription:\n---\n\n## Role\n\n- Title:\n- Seniority:\n- Function:\n- Reports to:\n\n## KPIs\n\n-\n\n## Pains\n\n-\n\n## Motivations\n\n-\n\n## Day-to-day\n\n_What this person actually does on a Tuesday._\n\n## Preferred channels\n\n_Cross-ref `medium/...`._\n\n-\n\n## Common objections\n\n_Cross-ref `objection/...`._\n\n-\n\n## How we land\n\n_The angle, the pitch, the moment they get it._\n```\n\n### `play/_template.md`\n\n```markdown\n---\ntitle:\ndescription:\n---\n\n## Hypothesis\n\n_Why this play should work. The bet._\n\n## Trigger\n\n_Cross-ref `signal/...`._\n\n-\n\n## Audience\n\n_Cross-ref `icp/...` or `persona/...`._\n\n-\n\n## Channel\n\n_Cross-ref `medium/...`._\n\n-\n\n## Sequence\n\n1.\n2.\n3.\n\n## Proof\n\n_Cross-ref `proof/...`._\n\n-\n\n## Success metric\n\n_What we measure. Target._\n\n## Owner\n\n_Role accountable for running this._\n\n## Variants\n\n-\n```\n\n### `proof/_template.md`\n\n```markdown\n---\ntitle:\ndescription:\n---\n\n## Type\n\n_metric | quote | case | benchmark | screenshot_\n\n## Content\n\n_The actual proof point. Number, quote, fact._\n\n## Source\n\n_Where it comes from. Customer, study, internal data._\n\n## Client\n\n_Optional. Cross-ref `client/...`._\n\n## Context\n\n_What claim this supports. Why we cite it._\n\n## Use cases\n\n_Where this shows up: objections, plays, posts, decks._\n\n-\n```\n\n### `objection/_template.md`\n\nObjections pair a stated buyer concern with the response and the proof that backs it up:\n\n```markdown\n---\ntitle:\ndescription:\n---\n\n## Objection\n\n_The buyer's stated concern, in their own words._\n\n## Response\n\n_Our reframe. Short, calm, specific._\n\n## Proof\n\n_Cross-ref `proof/...`._\n\n-\n\n## Personas\n\n_Cross-ref `persona/...` — who raises this most._\n\n-\n```\n\n## Authoring rules of thumb\n\n- **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.\n- **Title is a label, description is a hook.** `title` shows up in lists; `description` is the one-line that explains why this entry exists.\n- **Cross-refs over duplication.** If a fact already lives in `proof/...`, link to it from the play or objection rather than re-stating it.\n- **Atomic proof.** Each `proof/` entry is one fact / quote / metric. Bundled proof points break filtering in the knowledge graph.\n- **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:\n - Call-rich workspaces (≥ 50 transcripts / quarter): **3 occurrences**.\n - Medium volume: **2 occurrences**.\n - New / call-poor workspaces (\u003c 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).\n 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.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9571,"content_sha256":"ede0dec38e2d5a4f75744e2662f4651612575f2676ab2d7afca1f224b8bda8b3"},{"filename":"references/examples/authoring.md","content":"# Authoring examples\n\nEnd-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.\n\n> **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.\n\n## Discover before writing\n\n```bash\n# 1. What domains exist?\ncargo-ai context runtime browse\n\n# 2. What's already in the target domain? (avoid duplicates)\ncargo-ai context runtime browse --path persona\n\n# 3. What's the shape of an entry in this domain?\ncargo-ai context runtime read --path persona/_template.md\n```\n\n## Add a persona\n\n```bash\ncargo-ai context runtime write \\\n --path persona/head-of-revops.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: Head of RevOps\ndescription: Owns the GTM tech stack, data quality, and pipeline reporting at a 200–2,000-person B2B SaaS.\n---\n\n## Role\n\n- Title: Head of RevOps / Director of RevOps\n- Seniority: Director / VP\n- Function: Revenue Operations\n- Reports to: CRO or COO\n\n## KPIs\n\n- Pipeline velocity, forecast accuracy, data freshness, CRM hygiene, lead-to-opp conversion\n\n## Pains\n\n- Stale enrichment, broken CRM workflows, slow rep ramp because the data model is brittle\n- Stitching together 6 point tools that don't talk to each other\n- Manual segment refreshes for plays\n\n## Motivations\n\n- One source of truth across SDR, AE, CS\n- Replace fragile Zapier chains with durable workflows\n- Get out of the way of the frontline\n\n## Day-to-day\n\nOps standup, reviewing failed syncs, building a new segment for an outbound play, fielding rep requests, and weekly forecast prep with the CRO.\n\n## Preferred channels\n\n_Cross-ref `medium/...`._\n\n- medium/peer-community-slack\n- medium/founder-led-linkedin\n\n## Common objections\n\n_Cross-ref `objection/...`._\n\n- objection/we-already-have-clay\n- objection/we-built-this-in-house\n\n## How we land\n\nLead 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.\nEOF\n)\" \\\n --commit-message \"Add Head of RevOps persona\"\n```\n\n## Add a play with cross-refs\n\n```bash\ncargo-ai context runtime write \\\n --path play/funding-triggered-outbound.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: Funding-triggered outbound\ndescription: Reach out to companies within 14 days of a Series A–C raise with a hiring-and-stack angle.\n---\n\n## Hypothesis\n\nCompanies 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.\n\n## Trigger\n\n_Cross-ref `signal/...`._\n\n- signal/series-a-funding-announcement\n- signal/series-b-funding-announcement\n\n## Audience\n\n_Cross-ref `icp/...` or `persona/...`._\n\n- icp/post-series-a-b2b-saas\n- persona/head-of-revops\n\n## Channel\n\n_Cross-ref `medium/...`._\n\n- medium/founder-led-linkedin\n- medium/cold-email-personalized\n\n## Sequence\n\n1. Day 0: LinkedIn connect + congratulations note (no pitch).\n2. Day 3: Personalized email referencing the raise + a single relevant stack-replacement angle.\n3. Day 7: Follow-up with one proof point (cross-ref `proof/customer-x-replaced-three-tools`).\n4. Day 14: Break-up message.\n\n## Proof\n\n_Cross-ref `proof/...`._\n\n- proof/customer-x-replaced-three-tools\n- proof/14-day-time-to-first-workflow\n\n## Success metric\n\nReply rate ≥ 12% on Day 3 email; meetings booked / 100 contacted ≥ 4.\n\n## Owner\n\nOutbound AE pod lead.\n\n## Variants\n\n- Same play, swap LinkedIn for warm intro when one exists (cross-ref `medium/exec-warm-intro`).\nEOF\n)\" \\\n --commit-message \"Add funding-triggered outbound play\"\n```\n\n## Add a proof point\n\nKeep `proof/` atomic — one metric or quote per file:\n\n```bash\ncargo-ai context runtime write \\\n --path proof/14-day-time-to-first-workflow.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: 14-day time to first workflow\ndescription: New customers ship their first production workflow within 14 days of signing.\n---\n\n## Type\n\nmetric\n\n## Content\n\nAcross the last 24 customers (Q1–Q3), median time from contract signature to first production workflow run was 14 days; P90 was 27 days.\n\n## Source\n\nInternal customer success tracker, pulled 2025-10-15.\n\n## Client\n\n_Aggregate across customers — no single cross-ref._\n\n## Context\n\nUsed to counter the \"another tool we'll never deploy\" objection. Pairs well with `objection/we-already-have-clay`.\n\n## Use cases\n\n- objection/we-already-have-clay\n- play/funding-triggered-outbound\n- Sales decks, slide 9 (\"Time to value\")\nEOF\n)\" \\\n --commit-message \"Add 14-day time-to-first-workflow proof point\"\n```\n\n## Cite a source in an insight / learning doc\n\nWhen 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`).\n\n```bash\ncargo-ai context runtime write \\\n --path insight/agorapulse-expansion-readiness.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: AgoraPulse expansion readiness\ndescription: Why the AgoraPulse account is ready for a multi-thread expansion play.\nreferences:\n - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md\n---\n\n## Summary\n\nAgoraPulse surfaced three net-new buying centers in the last build session — strong signal for a multi-thread expansion.\n\n## Evidence\n\nDrawn 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.\nEOF\n)\" \\\n --commit-message \"Add AgoraPulse expansion readiness insight\"\n```\n\nBoth 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.\n\n## Edit a single line\n\n```bash\ncargo-ai context runtime edit \\\n --path global/positioning.md \\\n --old-string \"We help RevOps automate workflows.\" \\\n --new-string \"We help RevOps run AI-native GTM motions.\" \\\n --commit-message \"Refresh positioning one-liner\"\n```\n\n## Delete a line from a file\n\n```bash\n# Read first to copy the exact line (whitespace must match!)\ncargo-ai context runtime read --path persona/head-of-revops.md --start-line 18 --end-line 22\n\ncargo-ai context runtime edit \\\n --path persona/head-of-revops.md \\\n --old-string

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

- Stitching together 6 point tools that don\\'t talk to each other\\n' \\\n --new-string \"\" \\\n --commit-message \"Drop outdated pain point on Head of RevOps\"\n```\n\n## Rename / move an entry\n\nThere's no `rename` command, but `execute` auto-commits and pushes tracked file changes, so a move or delete run through it lands in git:\n\n```bash\ncargo-ai context runtime execute --command git --args '[\"mv\",\"persona/old-slug.md\",\"persona/new-slug.md\"]' --commit-message \"Rename persona/old-slug to persona/new-slug\"\ncargo-ai context runtime execute --command rm --args '[\"persona/stale-entry.md\"]' --commit-message \"Remove stale persona\"\n```\n\nFor most renames, the cleanest sequence is:\n\n1. Move the file (`execute` + `git mv`, above), or `write` the new file at the new path.\n2. Update every file that cross-refs the old slug — find them with `execute` + `grep`:\n ```bash\n cargo-ai context runtime execute --command grep --args '[\"-r\",\"-l\",\"persona/old-slug\",\".\"]'\n ```\n3. For each match, `edit` the cross-ref `persona/old-slug` → `persona/new-slug`.\n4. If you wrote a new file instead of moving, delete the stale one with `execute` + `rm`. Each call commits straight to the default branch, so if your context repo uses PR review, do the rename in GitHub instead.\n\n## Verify your work\n\n```bash\n# Confirm the file is in place\ncargo-ai context runtime read --path persona/head-of-revops.md\n\n# Confirm it lights up in the graph and its cross-refs resolve\ncargo-ai context graph get | jq '.graph.nodes[] | select(.id == \"persona/head-of-revops.md\")'\ncargo-ai context graph get | jq '.graph.broken[] | select(.source == \"persona/head-of-revops.md\")'\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8763,"content_sha256":"1515cf493c6faa683e2e4e559e50f081b4c6582bcbe5244b786e159aa7768b11"},{"filename":"references/examples/bootstrap-from-domain.md","content":"# Bootstrap workspace context from a domain\n\nThe 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 aiArk + builtwith + enrichCrm + 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.\n\nOutput: 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.\n\n**Trigger phrases:**\n- *\"Set up my workspace context from acme.com.\"*\n- *\"Bootstrap the context repo — my domain is acme.com.\"*\n- *\"Fill in the ICP and personas from our website.\"*\n- *\"My workspace is empty, just use our domain to populate everything.\"*\n\n## What this recipe exercises\n\n- `cargo-ai context runtime browse` / `graph get` for the idempotency check.\n- Domain-keyed enrichments (`aiArk.enrichCompany`, `builtwith.getDomainSummary`, `enrichCrm.getFunding`) for the factual spine.\n- Parallel sub-agents for public-source scraping (website, careers, blog, news, review sites).\n- 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).\n- `cargo-ai context runtime write` to commit one file per concept.\n\n## Required inputs\n\nBefore executing, the agent needs:\n1. **`domain`** (required) — canonical domain (`acme.com`), no protocol, no path.\n2. **`companyName`** (optional) — falls back to whatever `aiArk.enrichCompany` returns for the domain.\n3. **`depth`** (optional, default `standard`) — `minimal` (global + 1 icp + 2 personas), `standard` (full domain coverage), `deep` (also scrapes G2/Capterra/Reddit/HN for objections + alternatives).\n\nIf `domain` is missing, ask **once** and stop. Don't guess from the user's email — workspace domain and user email often diverge.\n\n## Recipe\n\n### Step 1 — Confirm the target workspace\n\nEach Cargo workspace maps to one company. `runtime write` pushes immediately. Wrong workspace = polluted repo for someone else.\n\n```bash\ncargo-ai whoami\n# → user.email, workspace.uuid, workspace.name\n```\n\nRead 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.\n\n**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.\n\n### Step 2 — Idempotency check (the \"if not exists\" part)\n\nInventory what's already in the repo so we only fill gaps, never overwrite:\n\n```bash\ncargo-ai context runtime browse > /tmp/ctx-browse.json\ncargo-ai context graph get > /tmp/ctx-graph.json\n\n# Count entries per domain (the graph already excludes _template.*; browse lists one level only)\njq -r '.graph.nodes[].id | select(test(\"^[^/]+/[^/]+\\\\.mdx?$\")) | split(\"/\")[0]' /tmp/ctx-graph.json \\\n | sort | uniq -c\n```\n\nBuild 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.\n\nFor 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.\n\n### Step 3 — Enrich the seed (factual spine)\n\nRun these in parallel — they give you the factual scaffolding (industry, headcount, tech stack, funding) every downstream synthesis step will cite. All three key on the **domain**, so there is no id-resolution step:\n\n```bash\nDOMAIN=acme.com\n\n# Parallel enrichments — same domain, three different signal families\nfor pair in \"aiArk:enrichCompany\" \"builtwith:getDomainSummary\" \"enrichCrm:getFunding\"; do\n slug=\"${pair%%:*}\"; action=\"${pair##*:}\"\n cargo-ai orchestration action execute \\\n --action \"$(jq -nc --arg i \"$slug\" --arg a \"$action\" \\\n '{kind:\"connector\",integrationSlug:$i,actionSlug:$a}')\" \\\n --data \"{\\\"domain\\\":\\\"$DOMAIN\\\"}\" \\\n --wait-until-finished > /tmp/enrich-$action.json &\ndone\nwait\n```\n\nTotal: ~1.01 credits (`aiArk.enrichCompany` 0.01, `builtwith.getDomainSummary` free, `enrichCrm.getFunding` 1). Drop the funding call and the whole spine costs a hundredth of a credit.\n\nIf every call comes back empty, fall back to website scraping only (Step 4) — note in every written file's `## Source` section that firmographics were unavailable.\n\n### Step 4 — Scrape public sources in parallel sub-agents\n\nSpawn one sub-agent per source. Each returns a **structured digest** (key claims + source URL), never raw HTML. Suggested fan-out:\n\n| Sub-agent | Source URLs | Lands in |\n|---|---|---|\n| Website core | `https://\u003cdomain>`, `/about`, `/product`, `/pricing`, `/customers` | `global/positioning`, `global/narrative`, `global/mission`, `global/pricing`, `client/...` |\n| Careers | `/careers`, `/jobs`, LinkedIn jobs | `persona/...`, `signal/hiring-intent-...` |\n| Blog & launches | `/blog`, `/changelog`, `/news` | `insight/...`, `proof/...` |\n| News & funding | Google News, Crunchbase summary | `signal/funding-...`, `proof/...` |\n| Reviews *(depth=deep only)* | G2, Capterra | `objection/...`, `alternative/...` |\n| Communities *(depth=deep only)* | Reddit, HN search | `objection/...`, `insight/...` |\n\nFor each digest, require a `source_url` per claim. **Skip anything you cannot source** — a thin context beats a fabricated one.\n\n### Step 5 — Synthesize and write per domain\n\nFor each domain you intend to populate, read the template first so frontmatter (`title`, `description`) and section structure are valid. Missing `title` or `description` does not fail the write, but the node indexes poorly (filename as title, first paragraph as summary).\n\n```bash\n# Always read the template first\ncargo-ai context runtime read --path global/_template.md\ncargo-ai context runtime read --path persona/_template.md\ncargo-ai context runtime read --path icp/_template.md\ncargo-ai context runtime read --path client/_template.md\ncargo-ai context runtime read --path proof/_template.md\ncargo-ai context runtime read --path signal/_template.md\n```\n\nThen 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.\n\nFor each domain, the agent should:\n\n1. Read the template (already done above) and the relevant digest from Step 4.\n2. 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`.\n3. 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.\n\nExample for `persona/` (after the agent has drafted `vp-engineering.md` from the careers digest):\n\n```bash\ncargo-ai context runtime write \\\n --path persona/vp-engineering.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: VP of Engineering\ndescription: Senior engineering leader at 50-500 person SaaS companies, owns platform reliability and developer productivity.\n---\n\n## Role\n- Title: VP of Engineering\n- Seniority: Executive\n- Function: Engineering\n- Reports to: CTO or CEO\n\n## KPIs\n- ...\n\n## Source\n- https://acme.com/careers/vp-engineering\nEOF\n)\"\n```\n\n### Step 6 — Verify and report\n\nRe-run the graph to confirm the writes landed and surface any orphan cross-refs:\n\n```bash\ncargo-ai context graph get > /tmp/ctx-graph-after.json\n\n# Node delta\necho \"Before: $(jq '.graph.nodes | length' /tmp/ctx-graph.json)\"\necho \"After: $(jq '.graph.nodes | length' /tmp/ctx-graph-after.json)\"\n\n# Orphans (nodes referenced but not authored)\njq -r '.graph.broken[] | \"\\(.source) → \\(.target)\"' /tmp/ctx-graph-after.json\n```\n\nReport to the user:\n- Files written, grouped by domain.\n- Domains skipped (from Step 2).\n- 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).\n\n## Credit budget\n\n| Step | Cost per call | Calls (depth=standard) | Subtotal |\n|---|---|---|---|\n| aiArk.enrichCompany | 0.01 | 1 | 0.01 |\n| builtwith.getDomainSummary | 0 | 1 | 0 |\n| enrichCrm.getFunding | 1 | 1 | 1 |\n| Public-source scrapes (sub-agents) | 0 (agent LLM tokens, not Cargo credits) | 4–6 | 0 |\n| Synthesis (agent native) | 0 (agent LLM tokens, not Cargo credits) | 6–8 | 0 |\n| context runtime write | 0 | 15–30 files | 0 |\n| **Total (standard)** | | | **~1 Cargo credit** |\n| **Total (deep)** adds review-site + community sub-agents | | | **~1 Cargo credit** |\n\nBootstrap is one-shot per workspace. Re-running is a no-op for already-seeded domains thanks to Step 2's skip-list.\n\n## Action shape\n\n`{\"kind\":\"connector\",\"integrationSlug\":\"\u003cslug>\",\"actionSlug\":\"\u003cslug>\"}`. **No `connectorUuid` in `config`.**\n\n## Output deliverable\n\nA summary the agent presents to the user:\n\n```\nContext repo bootstrapped from acme.com:\n\nWritten (24 files):\n global/ 3 files (positioning, narrative, pricing)\n icp/ 2 files (mid-market-saas, enterprise-fintech)\n persona/ 4 files (vp-eng, head-of-data, cto, vp-product)\n client/ 5 files (3 enterprise, 2 mid-market)\n proof/ 7 files (4 metrics, 3 quotes)\n signal/ 3 files (hiring-intent-data-eng, series-c-funding, snowflake-adoption)\n\nSkipped (already had content):\n alternative/, objection/, insight/\n\nOrphan refs: none.\n\nNext steps:\n - Open a fresh agent session so the seeded files load clean.\n - Refine from real sales calls — see Phase 2 of lifecycle.md.\n```\n\n## What this recipe does NOT do\n\n- **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.\n- **No `runtime edit` on existing files.** Bootstrap is additive only. Edits belong to the refresh phase.\n- **No invention.** If a claim has no `source_url`, drop it. Thin context is recoverable; fabricated context erodes trust in everything downstream.\n- **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.\n\n## When stuck — file a workspace report\n\nIf `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:\n\n```bash\ncargo-ai workspaceManagement report create \\\n --title \"bootstrap-from-domain: \u003cone-line summary>\" \\\n --description \"\u003cexact command(s) tried, errorMessage, domain attempted, workspace.uuid>\"\n```\n\nSee [`../../../cargo-workspace-management/SKILL.md`](../../../cargo-workspace-management/SKILL.md).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12106,"content_sha256":"e495bf791768317cbec1866723848b4858891416781a04fcc093d547b44954a0"},{"filename":"references/examples/graph-queries.md","content":"# Knowledge-graph queries\n\n`cargo-ai context graph get` returns the typed knowledge graph derived from every markdown/MDX/YAML file in the context repo. Pipe it through `jq` to slice it.\n\n> Shape: `{\"graph\": {\"nodes\": [{id, title, summary, cluster}], \"edges\": [{source, target, origin}], \"broken\": [{source, target, origin}], \"computedAt\"}}`. Node `id` is the repo-relative file path **with** its extension (`persona/vp-sales-mid-market.md`), and edge `source`/`target` are node ids. Only frontmatter `references:`, wikilinks, and Markdown links produce edges; a bare `domain/slug` in prose does not. See `../response-shapes.md`.\n\n## List every node\n\n```bash\ncargo-ai context graph get | jq -r '.graph.nodes[].id' | sort\n```\n\n## Count entries per domain\n\n```bash\ncargo-ai context graph get \\\n | jq -r '.graph.nodes[].cluster' \\\n | sort | uniq -c | sort -rn\n```\n\n## Find every persona\n\n```bash\ncargo-ai context graph get \\\n | jq '.graph.nodes[] | select(.cluster == \"persona\") | {id, title}'\n```\n\n## Find personas that link to a specific play\n\n```bash\ncargo-ai context graph get \\\n | jq -r --arg target \"play/funding-triggered-outbound.md\" '\n .graph.edges[]\n | select(.target == $target and (.source | startswith(\"persona/\")))\n | .source'\n```\n\n## Find dangling cross-references\n\nLinks whose target doesn't exist in the repo:\n\n```bash\ncargo-ai context graph get | jq '.graph.broken[] | {from: .source, missing: .target, origin}'\n```\n\n## Find plays with no proof attached\n\n```bash\ncargo-ai context graph get | jq -r '\n .graph as $g\n | $g.nodes[]\n | select(.cluster == \"play\")\n | .id as $id\n | select([$g.edges[] | select(.source == $id and (.target | startswith(\"proof/\")))] | length == 0)\n | $id\n'\n```\n\n## Find objections with no proof point\n\nSame pattern as plays, scoped to objections:\n\n```bash\ncargo-ai context graph get | jq '\n .graph as $g\n | $g.nodes[]\n | select(.cluster == \"objection\")\n | .id as $id\n | select([$g.edges[] | select(.source == $id and (.target | startswith(\"proof/\")))] | length == 0)\n | {id, title}\n'\n```\n\n## Show inbound references to a node\n\nWhich files link to `proof/14-day-time-to-first-workflow.md`?\n\n```bash\ncargo-ai context graph get | jq -r --arg target \"proof/14-day-time-to-first-workflow.md\" '\n .graph.edges[]\n | select(.target == $target)\n | .source\n'\n```\n\n## Audit frontmatter completeness\n\nThe graph does not return raw frontmatter: `title` falls back to the filename and `summary` falls back to `description`, then the first paragraph. Nodes whose `title` equals the bare filename, or that have no `summary`, are the ones likely missing frontmatter:\n\n```bash\ncargo-ai context graph get | jq -r '\n .graph.nodes[]\n | select(.title == (.id | split(\"/\") | last | sub(\"\\\\.(md|mdx|ya?ml)$\"; \"\")) or (.summary // \"\") == \"\")\n | .id\n'\n```\n\n## Snapshot the graph to disk\n\nUseful before a bulk edit so you can diff before/after:\n\n```bash\ncargo-ai context graph get > /tmp/graph.before.json\n# ...make edits via context runtime write/edit...\ncargo-ai context graph get > /tmp/graph.after.json\ndiff \u003c(jq -r '.graph.nodes[].id' /tmp/graph.before.json | sort) \\\n \u003c(jq -r '.graph.nodes[].id' /tmp/graph.after.json | sort)\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3188,"content_sha256":"f3570094062b3e4a619e4701103e5a7bb214d2dcaa11ef58092bb01420bcaa50"},{"filename":"references/examples/lifecycle.md","content":"# Context repo lifecycle\n\nThe 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.\n\nThe 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.\n\n## Before you start — confirm the target workspace\n\nEach 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.\n\n```bash\ncargo-ai whoami\n# → user.email, workspace.uuid, workspace.name\n```\n\nRead 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:\n\n```bash\ncargo-ai login --oauth --workspace-uuid \u003cuuid>\n# or, non-interactive:\ncargo-ai login --token \u003cworkspace-scoped-token>\n```\n\nIf 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.\n\n## Phase 1 — Bootstrap from public sources\n\nFor 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 aiArk + builtwith + enrichCrm, scrapes public sources in parallel sub-agents, and writes one file per atomic concept through `context runtime write`.\n\nOnce 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.\n\n## Phase 2 — Refresh from real calls\n\nGoal: replace assumptions with evidence. Public sources tell you what the company *says*; calls tell you what prospects *do*.\n\n### 1. Pull the last ~3 months of sales calls\n\nExport 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.\n\nWhile you're there, capture a **call volume estimate** (transcripts / quarter). It drives the repetition threshold in step 2b.\n\n### 2. Analyze one call at a time, human in the loop\n\nFor each call:\n\n1. 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.\n2. The agent proposes edits — new `objection/...`, updated `persona/...` pains, additional `proof/...` quotes, etc.\n3. A human approves each edit before it lands via `runtime write` or `runtime edit`.\n\nDo **not** batch this. An agent processing 30 calls in a loop overweights the loudest objection and underweights nuance.\n\n### 2b. Apply a repetition threshold\n\nA single call's claim is anecdote. Before promoting a claim into context, require it to surface across multiple calls:\n\n| Workspace volume | Threshold |\n|---|---|\n| Call-rich (≥ 50 transcripts / quarter) | **3 occurrences** before commit |\n| Medium volume | **2 occurrences** |\n| New / call-poor (\u003c 10 transcripts) | **1 occurrence** — note the source in the file body |\n\nTrack 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).\n\n### 3. Validate by generating sequences\n\nBefore treating the context as production-ready, run permutations through the workspace's sequence-generating play or agent and read the outputs. Useful permutations:\n\n- A persona + a play + an objection\n- Two different personas with the same play\n- A play with and without a specific proof point\n\nIf 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.\n\n### 4. Push to production\n\n`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.\n\n### 5. Repeat every 2–4 weeks\n\nRe-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:\n\n- Snapshot `cargo-ai context graph get` before and after, then diff to see what moved.\n- Retire context not referenced in the last two cycles — staleness is the failure mode, not coverage gaps.\n\n## What not to automate\n\nFull 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.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6120,"content_sha256":"6f24d099d361d8695fadf01cc25a7c0af8f922642ae6b804d5e987ae1c39145c"},{"filename":"references/response-shapes.md","content":"# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-context` skill.\n\n> Shapes below are taken from the `/v1/context` HTTP route schemas. Each command prints the success object on stdout; a failure exits non-zero and prints the error on stderr.\n\n## Error shape (every command)\n\nFailed commands exit non-zero (3 not authenticated, 4 permission denied, 5 not found, 1 otherwise) and, when stderr is not a TTY, print:\n\n```json\n{\n \"error\": \"Not found: ...\",\n \"status\": 404,\n \"body\": { \"reason\": \"fileNotFound\" }\n}\n```\n\n`body.reason` is the machine-readable cause; some reasons also carry `body.errorMessage`. `cargo-ai context runtime edit` fails with `stringNotFound` or `stringNotUnique` (HTTP 409) when `--old-string` matches zero or multiple times in the target file. See `references/troubleshooting.md`.\n\n## cargo-ai context runtime browse\n\nLists one directory level at the sandbox root (or under `--path`). Combine with `cargo-ai context runtime read --path \u003cfile>` to inspect any entry.\n\n```bash\ncargo-ai context runtime browse\ncargo-ai context runtime browse --path persona\n```\n\n```json\n{\n \"path\": \"persona\",\n \"entries\": [\n { \"name\": \"vp-sales-mid-market.md\", \"path\": \"persona/vp-sales-mid-market.md\", \"kind\": \"file\" }\n ]\n}\n```\n\n`kind` is `file` or `folder`. Failure reasons: `repositoryNotFound`, `branchNotFound`, `pathNotFound`, `unknown` (with `errorMessage`).\n\n## cargo-ai context runtime read\n\nReturns the file content at `--path`, optionally restricted to `--start-line`/`--end-line` (1-indexed, inclusive). Use this to read frontmatter + body before editing.\n\n```bash\ncargo-ai context runtime read --path persona/vp-sales-mid-market.md\ncargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40\n```\n\n```json\n{ \"path\": \"play/inbound-trial-to-paid.md\", \"content\": \"---\\ntitle: ...\", \"startLine\": 1, \"endLine\": 40, \"totalLines\": 112 }\n```\n\nThe range is clamped to the file: `endLine` past the end returns up to `totalLines`, and a `startLine` past the end returns empty `content` with `endLine` = `startLine - 1`. Failure reasons: `repositoryNotFound`, `fileNotFound`, `tooLarge` (with `sizeBytes`; reads cap at 10 MB), `unknown`.\n\n## cargo-ai context runtime write\n\nCreates (or overwrites) the file at `--path` and pushes a commit to the default branch. The `--commit-message` flag controls the commit subject (default `context(runtime): write \u003cpath>`).\n\n```bash\ncargo-ai context runtime write \\\n --path persona/vp-sales-mid-market.md \\\n --content \"\u003cfile body with frontmatter>\" \\\n --commit-message \"Add VP of Sales mid-market persona\"\n```\n\n```json\n{ \"commit\": { \"sha\": \"3f2c...\", \"message\": \"Add VP of Sales mid-market persona\" } }\n```\n\nFailure reasons: `repositoryNotFound`, `deniedPath` (writing under `.files/`; update those via Content instead), `failedToWrite` (with `errorMessage`, including a push that did not land), `unknown`. Frontmatter is **not** validated — a file missing `title`/`description` or with malformed frontmatter is written, not rejected.\n\n## cargo-ai context runtime edit\n\nReplaces a single exact substring in the file at `--path` and pushes a commit. `--old-string` must match **exactly once** unless `--replace-all` is passed. Read the file with `runtime read` first and copy the substring verbatim, whitespace included. Pass an empty `--new-string` to delete the match. Returns `{\"commit\": {\"sha\", \"message\"}}` on success, like `write`.\n\n```bash\ncargo-ai context runtime edit \\\n --path global/positioning.md \\\n --old-string \"We help RevOps automate workflows.\" \\\n --new-string \"We help RevOps run AI-native GTM motions.\" \\\n --commit-message \"Refresh positioning one-liner\"\n```\n\nFailure reasons: `stringNotFound`, `stringNotUnique`, `fileNotFound`, `noOp` (new string equals old), `deniedPath`, `failedToEdit` (with `errorMessage`), `repositoryNotFound`, `unknown`. Frontmatter is not validated, so an edit that strips `title`/`description` still applies.\n\n## cargo-ai context runtime execute\n\nRuns a shell command in the sandbox (90-second timeout) and returns its exit code and output. **Tracked working-tree changes the command leaves (additions, edits, deletions, renames) are auto-committed and pushed to the default branch**; gitignored paths are skipped. `--args` is a JSON array of string arguments; omit for a no-arg command. `--commit-message` overrides the auto-commit subject (default `context(runtime): execute \u003ccommand>`).\n\n```bash\ncargo-ai context runtime execute --command grep --args '[\"-r\",\"-l\",\"persona/vp-sales-mid-market\",\".\"]'\ncargo-ai context runtime execute --command ls --args '[\"-1\",\"persona\"]'\ncargo-ai context runtime execute --command pwd\n```\n\n```json\n{ \"exitCode\": 0, \"stdout\": \"...\", \"stderr\": \"\", \"commit\": { \"sha\": \"...\", \"message\": \"...\" } }\n```\n\n`commit` is present only when the command changed tracked files and the push landed. Failure reasons: `repositoryNotFound`, `readOnly`, `failedToExecute` (with `errorMessage`), `unknown`.\n\n## cargo-ai context graph get\n\nReturns the knowledge graph derived from every `.md`, `.mdx`, `.yaml`, and `.yml` file in the context repo (`.git/` and `_template.*` excluded). Shape used throughout `references/examples/graph-queries.md`:\n\n```json\n{\n \"graph\": {\n \"nodes\": [\n {\n \"id\": \"persona/vp-sales-mid-market.md\",\n \"title\": \"VP of Sales, mid-market\",\n \"summary\": \"Owns pipeline, quota, and rep productivity at a 200–2,000-person company.\",\n \"cluster\": \"persona\"\n }\n ],\n \"edges\": [\n { \"source\": \"persona/vp-sales-mid-market.md\", \"target\": \"objection/we-already-have-an-ai-sdr.md\", \"origin\": \"wikilink\" }\n ],\n \"broken\": [\n { \"source\": \"persona/vp-sales-mid-market.md\", \"target\": \"medium/exec-warm-intro\", \"origin\": \"frontmatter\" }\n ],\n \"computedAt\": \"2026-10-16T09:00:00.000Z\"\n }\n}\n```\n\n**Key fields:**\n\n- `graph.nodes[].id`: the repo-relative file path **including** its extension.\n- `graph.nodes[].title`: frontmatter `title`, falling back to the filename. `summary`: frontmatter `summary`, then `description`, then the first body paragraph (280 chars); absent when none exists. `cluster`: the top-level folder (a root file is its own cluster).\n- `graph.edges[]`: resolved links, `origin` one of `frontmatter`, `wikilink`, `mdlink`. Self-links and duplicates are dropped. `target` is a node `id`.\n- `graph.broken[]`: links whose target matched no file; `target` is the raw string as written.\n\nFailure reasons: `repositoryNotFound`, `tooManyFiles` (over 5,000 files; with `fileCount`, `limit`), `fileTooLarge` (a file over 1 MB; with `path`, `sizeBytes`, `limit`), `unknown`.\n\nFor ready-to-run queries (count per domain, dangling references, plays missing proof, inbound references to a node), see `references/examples/graph-queries.md`.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6818,"content_sha256":"634bcb1967cab9c7ba446d7f418b8c87892f4e4fa6b403ab0484d44640c812a7"},{"filename":"references/troubleshooting.md","content":"# Troubleshooting\n\nCommon errors and solutions for `cargo-ai context` commands.\n\n## General\n\n**`{\"error\": \"...\", \"status\": ..., \"body\": {\"reason\": \"...\"}}`**\nAll failed commands exit non-zero and print an error to stderr (this JSON form when stderr is piped). Read `body.reason` (and `body.errorMessage` when present) for the specific issue.\n\n**`Unauthorized` / `403`**\nYour 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).\n\n## Runtime — browse / read\n\n**Path not found**\nThe path does not exist in the runtime sandbox. Use `cargo-ai context runtime browse --path \u003cparent>` 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`).\n\n**Out-of-range lines**\n`--start-line` and `--end-line` are 1-indexed and inclusive on both ends. A range past the end of the file does not fail: it is clamped, and a `--start-line` past the end returns empty `content` (check `totalLines` in the response). `--end-line` lower than `--start-line` is rejected as `invalidBody`. Omit one end (e.g. only `--start-line`) to read to EOF.\n\n## Runtime — write\n\n**Push fails / commit not appearing**\n`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.\n\n**No `_template.md` for the domain**\nSome workspaces customize their context repo. If a domain doesn't ship a template, browse the domain (`cargo-ai context runtime browse --path \u003cdomain>`) and model the new file after an existing entry.\n\n**Missing / empty / malformed frontmatter (not an error)**\nFrontmatter 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`.\n\n**Other `notWritten` reasons**\n`write` can fail with `repositoryNotFound`, `failedToWrite` (including a push that did not land), or `deniedPath` (writing under `.files/` — update those via Content instead). `failedToWrite` / `deniedPath` carry an `errorMessage`. See `references/response-shapes.md`.\n\n## Runtime — edit\n\n**`--old-string` not found**\n`--old-string` did not match any substring in the file. Whitespace must match exactly, and the string is taken literally: `\\n` inside ordinary double quotes is a backslash and an `n`, so pass real newlines (bash `

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

...'` quoting) and watch for trailing spaces. Read the file first and copy the substring verbatim.\n\n**`--old-string` matches more than once**\n`edit` requires the match to be unique (`stringNotUnique`). Add enough surrounding context to make the match unique (extend with the line before or after), do multiple targeted edits in sequence, or pass `--replace-all` to replace every occurrence.\n\n**Other `notEdited` reasons**\nBesides the `--old-string` cases above, `edit` can return `fileNotFound`, `noOp` (the new string equals the old), `failedToEdit` (including a push race that did not land), 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.\n\n**Edits not appearing in GitHub**\n`write`, `edit`, and `execute` all commit and push. A shell command that modified tracked files (e.g. `sed -i`, redirecting into a file) is auto-committed; check the `commit` field in the response. If it is absent, the command changed no tracked files (gitignored paths are skipped) or the push did not land.\n\n## Runtime — execute\n\n**Command output is empty / unexpected**\nEach call runs with a 90-second timeout. Chain dependent operations in a single `--command` (e.g. via `sh -c`) rather than relying on state carried across `execute` runs.\n\n**Unexpected commits**\n`execute` auto-commits and pushes any tracked file changes the command leaves behind. Keep inspection commands (`grep`, `ls`, `find`, counting, validation) read-only, and prefer `write`/`edit` for deliberate changes.\n\n**Argument escaping**\n`--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:\n\n```bash\n# Correct\ncargo-ai context runtime execute --command grep --args '[\"-r\",\"vp-sales\",\".\"]'\n\n# Wrong — shell will eat the inner double quotes\ncargo-ai context runtime execute --command grep --args [\"-r\",\"vp-sales\",\".\"]\n```\n\n## Graph\n\n**Stale results after writes**\n`graph get` is cached against the sandbox snapshot, and a write that advances the snapshot invalidates it. If a result still looks stale after writes, re-run after a few seconds.\n\n**Broken cross-references**\nIf 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 \u003cdomain>` to verify the target exists before writing the reference, or read `graph.broken` from `graph get` to enumerate dangling refs (see `references/examples/graph-queries.md`).\n\n## When to escalate\n\nIf 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).\n\n```bash\ncargo-ai workspaceManagement report create \\\n --title \"context \u003csubcommand> fails with \u003cerrorMessage>\" \\\n --description \"Ran: cargo-ai context ... Got: {...errorMessage...} Expected: ...\"\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6178,"content_sha256":"15eb6fa86b5bfcb157d4646386694f657d626d989eb2bddbea4dd1f5d759d3f7"},{"filename":"skill-metadata.json","content":"{\n \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n \"name\": \"cargo-context\",\n \"version\": \"1.4.2\",\n \"documents\": [\n {\n \"path\": \"SKILL.md\",\n \"kind\": \"entrypoint\",\n \"title\": \"Cargo CLI — Context\"\n },\n {\n \"path\": \"references/conventions.md\",\n \"kind\": \"reference\",\n \"title\": \"Context repo conventions\"\n },\n {\n \"path\": \"references/examples/authoring.md\",\n \"kind\": \"example\",\n \"title\": \"Authoring examples\"\n },\n {\n \"path\": \"references/examples/bootstrap-from-domain.md\",\n \"kind\": \"example\",\n \"title\": \"Bootstrap workspace context from a domain\"\n },\n {\n \"path\": \"references/examples/graph-queries.md\",\n \"kind\": \"example\",\n \"title\": \"Knowledge-graph queries\"\n },\n {\n \"path\": \"references/examples/lifecycle.md\",\n \"kind\": \"example\",\n \"title\": \"Context repo lifecycle\"\n },\n {\n \"path\": \"references/response-shapes.md\",\n \"kind\": \"reference\",\n \"title\": \"Response shapes\"\n },\n {\n \"path\": \"references/troubleshooting.md\",\n \"kind\": \"reference\",\n \"title\": \"Troubleshooting\"\n }\n ],\n \"contentHash\": \"ff3f2ae29fa3efdd5c8ee0f6f6b7e6c0ebbf0fc1a1891475d8abad82dc43108a\"\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":1329,"content_sha256":"7dfeb42961acc2c5ec568dab2e5b4b8307e091c3bd3cc0169d2f441d5f0bd0ae"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Cargo CLI — Context","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"context","type":"text","marks":[{"type":"strong"}]},{"text":" 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 ","type":"text"},{"text":"cargo-ai context","type":"text","marks":[{"type":"code_inline"}]},{"text":" domain has two subdomains you'll use:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"runtime","type":"text","marks":[{"type":"strong"}]},{"text":" — browse, read, write, edit, and execute against the workspace's runtime sandbox (a checked-out copy of the context repo). ","type":"text"},{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" are pushed to the default branch, and ","type":"text"},{"text":"execute","type":"text","marks":[{"type":"code_inline"}]},{"text":" auto-commits and pushes any tracked working-tree changes its command leaves behind.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"graph","type":"text","marks":[{"type":"strong"}]},{"text":" — build/load the knowledge graph derived from every markdown/MDX file in the context repo.","type":"text"}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"The canonical example of a context repository is ","type":"text"},{"text":"getcargohq/cargo-workspaces","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/getcargohq/cargo-workspaces","title":null}},{"type":"code_inline"}]},{"text":". Read its ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" to understand the domain layout and file conventions before writing new entries. For uploading runtime-independent files (CSVs, PDFs) used in batch runs, use ","type":"text"},{"text":"cargo-workspace-management","type":"text","marks":[{"type":"link","attrs":{"href":"../cargo-workspace-management/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"cargo-ai workspaceManagement file upload","type":"text","marks":[{"type":"code_inline"}]},{"text":") instead. For RAG file attachments to agents, use ","type":"text"},{"text":"cargo-ai","type":"text","marks":[{"type":"link","attrs":{"href":"../cargo-ai/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"cargo-ai content file upload","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full context repo structure and per-domain templates. See ","type":"text"},{"text":"references/response-shapes.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the JSON shapes returned by each ","type":"text"},{"text":"cargo-ai context","type":"text","marks":[{"type":"code_inline"}]},{"text":" command. See ","type":"text"},{"text":"references/troubleshooting.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for common errors and how to fix them. See ","type":"text"},{"text":"references/examples/authoring.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for end-to-end add / edit / delete recipes. See ","type":"text"},{"text":"references/examples/lifecycle.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the bootstrap + refresh-from-calls playbook. See ","type":"text"},{"text":"references/examples/graph-queries.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for inspecting the knowledge graph.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Bootstrap","type":"text"}]},{"type":"paragraph","content":[{"text":"Already signed in (","type":"text"},{"text":"cargo-ai whoami","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns a workspace)? Skip to the next section.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email [email protected] # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token \u003capi-token> (CI)\ncargo-ai whoami # confirm the active workspace before any write","type":"text"}]},{"type":"paragraph","content":[{"text":"Every command prints JSON to stdout; failures exit non-zero and print the error to stderr (piped: ","type":"text"},{"text":"{\"error\": \"...\", \"status\": \u003chttp>, \"body\": {\"reason\": \"...\"}}","type":"text","marks":[{"type":"code_inline"}]},{"text":", where ","type":"text"},{"text":"body.reason","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the machine-readable cause). Anything that creates a run or a batch is async — pass ","type":"text"},{"text":"--wait-until-finished","type":"text","marks":[{"type":"code_inline"}]},{"text":" or poll the matching ","type":"text"},{"text":"get","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"runtime write","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"runtime edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" commit and push to the workspace's context repo, so confirming ","type":"text"},{"text":"workspace.name","type":"text","marks":[{"type":"code_inline"}]},{"text":" first is non-negotiable. When the full skill bundle is installed, ","type":"text"},{"text":"../cargo/references/prerequisites.md","type":"text","marks":[{"type":"link","attrs":{"href":"../cargo/references/prerequisites.md","title":null}},{"type":"code_inline"}]},{"text":" adds the CLI version pin, token scopes, and the admin-only surface.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Discover the context first","type":"text"}]},{"type":"paragraph","content":[{"text":"Before editing anything, see what's in the context repo:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context runtime browse # list entries at the runtime sandbox root\ncargo-ai context graph get # full knowledge graph derived from the repo's md/mdx files","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick reference","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Runtime sandbox (checked-out copy of the context repo)\ncargo-ai context runtime browse [--path \u003cpath>]\ncargo-ai context runtime read --path \u003cpath> [--start-line \u003cn>] [--end-line \u003cn>]\ncargo-ai context runtime write --path \u003cpath> --content \u003ccontent> [--commit-message \u003cmessage>]\ncargo-ai context runtime edit --path \u003cpath> --old-string \u003cold> --new-string \u003cnew> [--replace-all] [--commit-message \u003cmessage>]\ncargo-ai context runtime execute --command \u003ccommand> [--args \u003cjson>] [--commit-message \u003cmessage>]\n\n# Knowledge graph\ncargo-ai context graph get","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Runtime sandbox","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"runtime sandbox","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Two important behaviors to remember:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"write","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" and ","type":"text","marks":[{"type":"strong"}]},{"text":"edit","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" push to the default branch","type":"text","marks":[{"type":"strong"}]},{"text":" of the context repo. They are not local-only.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"execute","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" pushes too.","type":"text","marks":[{"type":"strong"}]},{"text":" When the command leaves tracked files added, changed, deleted, or renamed, those changes are auto-committed (subject ","type":"text"},{"text":"context(runtime): execute \u003ccommand>","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"--commit-message","type":"text","marks":[{"type":"code_inline"}]},{"text":") and pushed to the default branch. Gitignored paths are skipped. A ","type":"text"},{"text":"sed -i","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"rm","type":"text","marks":[{"type":"code_inline"}]},{"text":" run through ","type":"text"},{"text":"execute","type":"text","marks":[{"type":"code_inline"}]},{"text":" lands in git.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Mirrored content files live read-only under ","type":"text","marks":[{"type":"strong"}]},{"text":".files/","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" A content file stored with ","type":"text"},{"text":"mirrorToContext: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the default for ","type":"text"},{"text":"content file upload","type":"text","marks":[{"type":"code_inline"}]},{"text":", web-app uploads and ","type":"text"},{"text":"defineFile","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see ","type":"text"},{"text":"cargo-content","type":"text","marks":[{"type":"link","attrs":{"href":"../cargo-content/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":") — is ","type":"text"},{"text":"committed and pushed to the context repo","type":"text","marks":[{"type":"strong"}]},{"text":" at ","type":"text"},{"text":".files/\u003cfolder path>/\u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (commits titled ","type":"text"},{"text":"content(mirror): upsert \u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"… move …","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"… remove …","type":"text","marks":[{"type":"code_inline"}]},{"text":"; a file over 10 MB lands as a JSON metadata sidecar instead of its bytes). A command run via ","type":"text"},{"text":"execute","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"read","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"browse","type":"text","marks":[{"type":"code_inline"}]},{"text":") can consume them — e.g. ","type":"text"},{"text":"cargo-ai context runtime execute --command ls --args '[\"-1\",\".files\"]'","type":"text","marks":[{"type":"code_inline"}]},{"text":". Files written by path (","type":"text"},{"text":"content file put","type":"text","marks":[{"type":"code_inline"}]},{"text":", the objects API, workers, the ","type":"text"},{"text":"writeFile","type":"text","marks":[{"type":"code_inline"}]},{"text":" node, agent writes) default to ","type":"text"},{"text":"mirrorToContext: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" and are ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" there. You can't add or change anything under ","type":"text"},{"text":".files/","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the runtime (","type":"text"},{"text":"deniedPath","type":"text","marks":[{"type":"code_inline"}]},{"text":") — use ","type":"text"},{"text":"cargo-ai content file …","type":"text","marks":[{"type":"code_inline"}]},{"text":". Anyone who can read the context repo can read every mirrored file.","type":"text"}]},{"type":"paragraph","content":[{"text":"Because writes push immediately, ","type":"text"},{"text":"confirm the target workspace before the first ","type":"text","marks":[{"type":"strong"}]},{"text":"write","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"/","type":"text","marks":[{"type":"strong"}]},{"text":"edit","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai whoami # → workspace.uuid, workspace.name","type":"text"}]},{"type":"paragraph","content":[{"text":"Read the workspace name back to the user. If the session is for a specific client, make sure ","type":"text"},{"text":"workspace.name","type":"text","marks":[{"type":"code_inline"}]},{"text":" matches before authoring anything — there is no dry-run mode. If ","type":"text"},{"text":"workspace.name","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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 (","type":"text"},{"text":"example.com","type":"text","marks":[{"type":"code_inline"}]},{"text":") and confirm both before the first write. If you logged in without pinning a workspace, re-run ","type":"text"},{"text":"cargo-ai login --oauth --workspace-uuid \u003cuuid>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"--token \u003cworkspace-scoped-token>","type":"text","marks":[{"type":"code_inline"}]},{"text":" for non-interactive use).","type":"text"}]},{"type":"paragraph","content":[{"text":"Edits derived from sales-call analysis should be applied ","type":"text"},{"text":"one at a time with human review","type":"text","marks":[{"type":"strong"}]},{"text":", not batched. Looping an agent over many calls tends to overweight the loudest signal and miss nuance — see ","type":"text"},{"text":"references/examples/lifecycle.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the call-refresh playbook.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Browse and read","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# List entries at the root of the runtime sandbox\ncargo-ai context runtime browse\n\n# List entries under a subpath (e.g. a domain folder like persona/ or play/)\ncargo-ai context runtime browse --path persona\n\n# Read a full file\ncargo-ai context runtime read --path persona/vp-sales-mid-market.md\n\n# Read only a line range (1-indexed, inclusive on both ends)\ncargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Write a new file","type":"text"}]},{"type":"paragraph","content":[{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":" creates (or overwrites) a file and pushes a commit to the default branch.","type":"text"}]},{"type":"paragraph","content":[{"text":"Begin every ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":".mdx","type":"text","marks":[{"type":"code_inline"}]},{"text":" file with a YAML frontmatter block setting ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":". Frontmatter is ","type":"text"},{"text":"not validated","type":"text","marks":[{"type":"strong"}]},{"text":" by ","type":"text"},{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":" (a project's ","type":"text"},{"text":"defineContext","type":"text","marks":[{"type":"code_inline"}]},{"text":" is — see ","type":"text"},{"text":"File conventions","type":"text","marks":[{"type":"link","attrs":{"href":"#file-conventions","title":null}}]},{"text":") — a file with missing, empty, or malformed frontmatter is still written and committed; it just indexes poorly in the graph (a missing ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":" falls back to the filename, the node summary to the first paragraph). ","type":"text"},{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":" can still fail for other reasons — ","type":"text"},{"text":"repositoryNotFound","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"failedToWrite","type":"text","marks":[{"type":"code_inline"}]},{"text":" (including a push that did not land), or ","type":"text"},{"text":"deniedPath","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g. writing under ","type":"text"},{"text":".files/","type":"text","marks":[{"type":"code_inline"}]},{"text":"); see ","type":"text"},{"text":"references/response-shapes.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context runtime write \\\n --path persona/vp-sales-mid-market.md \\\n --content \"$(cat \u003c\u003c'EOF'\n---\ntitle: VP of Sales, mid-market\ndescription: Owns pipeline, quota, and rep productivity at a 200–2,000-person company.\n---\n\n## Role\n- Title: VP of Sales\n- Seniority: Executive\n- Function: Revenue\n- Reports to: CRO or CEO\n\n## KPIs\n- New ARR, win rate, pipeline coverage, rep ramp time\n\n## Pains\n- Pipeline gaps, slow ramp, low rep activity, forecasting drift\n\n## Motivations\n- Hit the number, build a repeatable motion, get visibility\n\n## Day-to-day\nForecast calls, deal reviews, pipeline reviews, 1:1s with frontline managers.\n\n## Preferred channels\n- medium/linkedin-outbound\n- medium/exec-warm-intro\n\n## Common objections\n- objection/we-already-have-an-ai-sdr\n\n## How we land\nLead with pipeline-coverage math, not features.\nEOF\n)\" \\\n --commit-message \"Add VP of Sales mid-market persona\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Edit an existing file","type":"text"}]},{"type":"paragraph","content":[{"text":"edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" replaces a single exact substring. ","type":"text"},{"text":"--old-string","type":"text","marks":[{"type":"code_inline"}]},{"text":" must occur ","type":"text"},{"text":"exactly once","type":"text","marks":[{"type":"strong"}]},{"text":" in the file (unless ","type":"text"},{"text":"--replace-all","type":"text","marks":[{"type":"code_inline"}]},{"text":" is passed); pass an empty ","type":"text"},{"text":"--new-string","type":"text","marks":[{"type":"code_inline"}]},{"text":" to delete the match. The strings are taken literally: ","type":"text"},{"text":"\\n","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside ordinary double quotes is a backslash and an ","type":"text"},{"text":"n","type":"text","marks":[{"type":"code_inline"}]},{"text":", not a newline, so use bash ","type":"text"},{"text":"

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

...'","type":"text","marks":[{"type":"code_inline"}]},{"text":" quoting for multi-line matches.","type":"text"}]},{"type":"paragraph","content":[{"text":"edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" does not validate frontmatter — an edit that strips or empties ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" still applies, so keep the block intact to keep the node discoverable. ","type":"text"},{"text":"edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" can fail for other reasons, though: ","type":"text"},{"text":"stringNotFound","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"stringNotUnique","type":"text","marks":[{"type":"code_inline"}]},{"text":" (the ","type":"text"},{"text":"--old-string","type":"text","marks":[{"type":"code_inline"}]},{"text":" match), ","type":"text"},{"text":"fileNotFound","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"noOp","type":"text","marks":[{"type":"code_inline"}]},{"text":" (new string equals old), ","type":"text"},{"text":"failedToEdit","type":"text","marks":[{"type":"code_inline"}]},{"text":" (including a push that did not land), or ","type":"text"},{"text":"deniedPath","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Replace one specific sentence\ncargo-ai context runtime edit \\\n --path global/positioning.md \\\n --old-string \"We help RevOps automate workflows.\" \\\n --new-string \"We help RevOps run AI-native GTM motions.\" \\\n --commit-message \"Refresh positioning one-liner\"\n\n# Delete a line (pass empty --new-string)\ncargo-ai context runtime edit \\\n --path persona/vp-sales-mid-market.md \\\n --old-string

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\\n- Outdated stat: 4.2x pipeline\\n' \\\n --new-string \"\"","type":"text"}]},{"type":"paragraph","content":[{"text":"For larger restructures, prefer ","type":"text"},{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":" (full-file overwrite) over many sequential ","type":"text"},{"text":"edit","type":"text","marks":[{"type":"code_inline"}]},{"text":" calls.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Execute a command in the sandbox","type":"text"}]},{"type":"paragraph","content":[{"text":"execute","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs a shell command in the sandbox (90-second timeout). Useful for inspecting structure or running checks; ","type":"text"},{"text":"tracked file changes it leaves are committed and pushed","type":"text","marks":[{"type":"strong"}]},{"text":", so keep inspection commands read-only.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Find every file that cross-references a specific slug\ncargo-ai context runtime execute \\\n --command grep \\\n --args '[\"-r\",\"-l\",\"persona/vp-sales-mid-market\",\".\"]'\n\n# Count entries per domain\ncargo-ai context runtime execute --command ls --args '[\"-1\",\"persona\"]'\n\n# Run a one-shot script (no quotes/escaping needed inside --command beyond JSON for args)\ncargo-ai context runtime execute --command pwd","type":"text"}]},{"type":"paragraph","content":[{"text":"--args","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a JSON array of string arguments. Omit it for a no-arg command.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Context repository structure and conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"The Cargo context repo is a typed knowledge base. The canonical example — and the source of the conventions below — is ","type":"text"},{"text":"getcargohq/cargo-workspaces","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/getcargohq/cargo-workspaces","title":null}},{"type":"code_inline"}]},{"text":"; read its ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"_template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files in each domain before writing new entries. For the full domain reference, see ","type":"text"},{"text":"references/conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Domains","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Domain","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"global/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Company-level context: mission, voice, positioning, narrative, pricing","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"icp/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ideal Customer Profile segments","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"persona/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Buyer personas (roles inside an ICP)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"jtbd/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Jobs-to-be-done framings","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"alternative/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Competitors, substitutes, status quo","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"client/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Customer profiles, case studies, reference accounts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"insight/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Market insights and observations","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"medium/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Channel playbooks (email, LinkedIn, cold call, etc.)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"objection/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Objections + responses + proof","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"play/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GTM plays (signal → audience → channel → sequence → outcome)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"proof/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Atomic proof points (metrics, quotes, case data)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"signal/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Buying signals and intent triggers","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File conventions","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Filename:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"kebab-case.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g. ","type":"text"},{"text":"vp-sales-mid-market.md","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Frontmatter:","type":"text","marks":[{"type":"strong"}]},{"text":" start every ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":".mdx","type":"text","marks":[{"type":"code_inline"}]},{"text":" file with YAML frontmatter setting ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":". This is a ","type":"text"},{"text":"strong convention, not enforced","type":"text","marks":[{"type":"strong"}]},{"text":" — a write with missing, empty, or malformed frontmatter is still created and committed; it just indexes poorly. The graph reads ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":" (fallback: filename) and ","type":"text"},{"text":"summary","type":"text","marks":[{"type":"code_inline"}]},{"text":" (fallback: ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":", then the file's first paragraph), so add a ","type":"text"},{"text":"summary:","type":"text","marks":[{"type":"code_inline"}]},{"text":" only if you want the node summary to differ from ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"Source references and graph edges","type":"text","marks":[{"type":"link","attrs":{"href":"#source-references-and-graph-edges","title":null}}]},{"text":". The exception is context declared in a project (","type":"text"},{"text":"defineContext","type":"text","marks":[{"type":"code_inline"}]},{"text":", see ","type":"text"},{"text":"../cargo-project/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"): there ","type":"text"},{"text":"project check","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"plan","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"deploy","type":"text","marks":[{"type":"code_inline"}]},{"text":" fail on frontmatter that doesn't parse and on a ","type":"text"},{"text":"references:","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry, ","type":"text"},{"text":"[[wikilink]]","type":"text","marks":[{"type":"code_inline"}]},{"text":" or relative ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" link that matches no file declared under ","type":"text"},{"text":"files","type":"text","marks":[{"type":"code_inline"}]},{"text":" — including one that exists in the workspace repo but not in code. A missing ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" still passes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-references:","type":"text","marks":[{"type":"strong"}]},{"text":" use the ","type":"text"},{"text":"domain/slug","type":"text","marks":[{"type":"code_inline"}]},{"text":" form, ","type":"text"},{"text":"no ","type":"text","marks":[{"type":"strong"}]},{"text":".md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" extension","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g. ","type":"text"},{"text":"persona/vp-sales-mid-market","type":"text","marks":[{"type":"code_inline"}]},{"text":"). To register as a graph ","type":"text"},{"text":"edge","type":"text","marks":[{"type":"strong"}]},{"text":" a reference must use one of the three link forms below — a bare ","type":"text"},{"text":"domain/slug","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or file path) in plain prose creates no edge.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Templates:","type":"text","marks":[{"type":"strong"}]},{"text":" each domain ships an ","type":"text"},{"text":"_template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Read it (","type":"text"},{"text":"cargo-ai context runtime read --path persona/_template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":") before authoring a new entry. ","type":"text"},{"text":"_template.*","type":"text","marks":[{"type":"code_inline"}]},{"text":" files are excluded from the graph — never reference them.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Source references and graph edges","type":"text"}]},{"type":"paragraph","content":[{"text":"The knowledge graph is built from every ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".mdx","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":".yml","type":"text","marks":[{"type":"code_inline"}]},{"text":" file in the repo (any folder; only ","type":"text"},{"text":".git/","type":"text","marks":[{"type":"code_inline"}]},{"text":" is excluded). Each file is a node, but ","type":"text"},{"text":"edges are created only from three forms","type":"text","marks":[{"type":"strong"}]},{"text":" — anything else is invisible to the graph:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Frontmatter ","type":"text","marks":[{"type":"strong"}]},{"text":"references:","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" list","type":"text","marks":[{"type":"strong"}]},{"text":" (preferred for source citations — keeps prose clean):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\ntitle: AgoraPulse expansion thesis\ndescription: Why AgoraPulse is ready for a multi-thread expansion play.\nreferences:\n - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md\n---","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A Markdown link","type":"text","marks":[{"type":"strong"}]},{"text":" in the body — standard ","type":"text"},{"text":"[label]","type":"text","marks":[{"type":"code_inline"}]},{"text":" followed immediately by ","type":"text"},{"text":"(path)","type":"text","marks":[{"type":"code_inline"}]},{"text":" syntax, where the target is the file path, e.g. an anchor linking to ","type":"text"},{"text":"outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Wikilinks","type":"text","marks":[{"type":"strong"}]},{"text":" in the body (extension optional): ","type":"text"},{"text":"[[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Key constraints:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Never cite a source as a bare path in prose","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g. a ","type":"text"},{"text":"Source:","type":"text","marks":[{"type":"code_inline"}]},{"text":" line that just mentions ","type":"text"},{"text":"outputs/sales-notes/foo.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as text) — it is not parsed and creates ","type":"text"},{"text":"no","type":"text","marks":[{"type":"strong"}]},{"text":" edge.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer root-relative paths","type":"text","marks":[{"type":"strong"}]},{"text":" (resolved from the repo root first, then relative to the citing file) so links work regardless of where the document lives.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extensions are optional for wikilinks and frontmatter ","type":"text","marks":[{"type":"strong"}]},{"text":"references:","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": the resolver auto-tries ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".mdx","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".yml","type":"text","marks":[{"type":"code_inline"}]},{"text":" in that order. A ","type":"text"},{"text":"Markdown link","type":"text","marks":[{"type":"strong"}]},{"text":" only counts as an edge when its target ends in ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".mdx","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":".yml","type":"text","marks":[{"type":"code_inline"}]},{"text":", so keep the extension there.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The target must exist","type":"text","marks":[{"type":"strong"}]},{"text":" or the edge is ","type":"text"},{"text":"broken","type":"text","marks":[{"type":"strong"}]},{"text":" (a dead link in the graph UI). Verify with ","type":"text"},{"text":"runtime browse","type":"text","marks":[{"type":"code_inline"}]},{"text":" before citing.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For docs with a ","type":"text"},{"text":"Source","type":"text","marks":[{"type":"strong"}]},{"text":"/","type":"text"},{"text":"Evidence","type":"text","marks":[{"type":"strong"}]},{"text":" section, cite the files in frontmatter ","type":"text"},{"text":"references:","type":"text","marks":[{"type":"code_inline"}]},{"text":"; use inline markdown links when the citation needs surrounding prose. Full rules: ","type":"text"},{"text":"references/conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workflow: add a new entry","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm the target domain and copy its template:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context runtime read --path persona/_template.md","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"write","type":"text","marks":[{"type":"code_inline"}]},{"text":" a new file at ","type":"text"},{"text":"\u003cdomain>/\u003cslug>.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the body sections filled in.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add cross-refs (","type":"text"},{"text":"domain/slug","type":"text","marks":[{"type":"code_inline"}]},{"text":") where useful — keep them bidirectional when it makes sense.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rebuild the knowledge graph to verify the new entry and its links:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context graph get","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For full per-domain templates and worked examples, see ","type":"text"},{"text":"references/conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"references/examples/authoring.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workflow: bootstrap and refresh","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"references/examples/lifecycle.md","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bootstrap (one-time):","type":"text","marks":[{"type":"strong"}]},{"text":" seed ","type":"text"},{"text":"global/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"persona/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"client/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"proof/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"objection/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"signal/","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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 ","type":"text"},{"text":"references/examples/bootstrap-from-domain.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Refresh (every 2–4 weeks):","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The repetition threshold (how many calls a claim must appear in before it lands in context) is documented in ","type":"text"},{"text":"references/conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Knowledge graph","type":"text"}]},{"type":"paragraph","content":[{"text":"context graph get","type":"text","marks":[{"type":"code_inline"}]},{"text":" builds (or loads from cache) the knowledge graph over every markdown/MDX file in the context repo. Use it to:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Audit cross-references between domains (e.g. find personas that link to plays with no proof attached).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discover what already exists before writing a new entry (avoid duplicates).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Power downstream agents that need the typed structure of the workspace's context.","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context graph get","type":"text"}]},{"type":"paragraph","content":[{"text":"The response is ","type":"text"},{"text":"{\"graph\": {\"nodes\", \"edges\", \"broken\", \"computedAt\"}}","type":"text","marks":[{"type":"code_inline"}]},{"text":": each node carries ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code_inline"}]},{"text":" (the file path, extension included), ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"summary","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"cluster","type":"text","marks":[{"type":"code_inline"}]},{"text":" (top-level folder); each edge carries ","type":"text"},{"text":"source","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"target","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"origin","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"frontmatter","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"wikilink","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"mdlink","type":"text","marks":[{"type":"code_inline"}]},{"text":"); ","type":"text"},{"text":"broken","type":"text","marks":[{"type":"code_inline"}]},{"text":" lists edges whose target does not exist. Pipe it through ","type":"text"},{"text":"jq","type":"text","marks":[{"type":"code_inline"}]},{"text":" to slice it. See ","type":"text"},{"text":"references/examples/graph-queries.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for ready-to-run queries.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Help","type":"text"}]},{"type":"paragraph","content":[{"text":"Every command supports ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cargo-ai context --help\ncargo-ai context runtime browse --help\ncargo-ai context runtime read --help\ncargo-ai context runtime write --help\ncargo-ai context runtime edit --help\ncargo-ai context runtime execute --help\ncargo-ai context graph get --help","type":"text"}]}]},"metadata":{"date":"2026-11-02","name":"cargo-context","author":"@skillopedia","source":{"stars":21,"repo_name":"cargo-skills","origin_url":"https://github.com/getcargohq/cargo-skills/blob/HEAD/cargo-context/SKILL.md","repo_owner":"getcargohq","body_sha256":"9f1f24169d5a292fdf7ed285518f89806aaf38d8e52f3d2b9d56e1a3e849b702","cluster_key":"e9bb475105ec24b56d89f600e21a5ea9b3e29d30d9032f141a1fc084284cda52","clean_bundle":{"format":"clean-skill-bundle-v1","source":"getcargohq/cargo-skills/cargo-context/SKILL.md","text_bytes":54073,"source_commit":"9cbff158c25c49bf3ec3f1424383bd0ef93e9448","skills_sh_rank":2339,"attachment_count":8,"text_attachments":8,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"cargo-context/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"1.4.2","category":"business-sales-marketing","category_label":"Business"},"exact_dupes_collapsed_into_this":0},"version":"1.4.2","category":"business-sales-marketing","homepage":"https://github.com/getcargohq/cargo-skills","metadata":{"author":"getcargo","openclaw":{"install":[{"bins":["cargo-ai"],"kind":"node","package":"@cargo-ai/cli@latest"}],"homepage":"https://github.com/getcargohq/cargo-skills","requires":{"bins":["cargo-ai"]}}},"import_tag":"skills-sh-top20k-2026-11","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 \u003csegment>\", \"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.","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"}},"renderedAt":1793661435372}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.