Name: cargo-context
Author: getcargohq

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 posit

Cargo CLI — Context The context is a git backed repository of typed markdown/MDX files that captures a workspace's GTM knowledge (company narrative, ICPs, personas, plays, proof, objections, etc.) and is read/written by both humans and agents. The cargo ai context domain has two subdomains you'll use: runtime — browse, read, write, edit, and execute against the workspace's runtime sandbox (a checked out copy of the context repo). write / edit are pushed to the default branch, and execute auto commits and pushes any tracked working tree changes its command leaves behind. graph — build/load the knowledge graph derived from every markdown/MDX file in the context repo. The canonical example of a context repository is [ getcargohq/cargo workspaces ](https://github.com/getcargohq/cargo workspaces). Read its README.md to understand the domain layout and file conventions before writing new entries. For uploading runtime independent files (CSVs, PDFs) used in batch runs, use [ cargo workspace management ](../cargo workspace management/SKILL.md) ( cargo ai workspaceManagement file upload ) instead. For RAG file attachments to agents, use [ cargo ai ](../cargo ai/SKILL.md) ( cargo ai content file upload ). See references/conventions.md for the full context repo structure and per domain templates. See references/response shapes.md for the JSON shapes returned by each cargo ai context command. See references/troubleshooting.md for common errors and how to fix them. See references/examples/authoring.md for end to end add / edit / delete recipes. See references/examples/lifecycle.md for the bootstrap + refresh from calls playbook. See references/examples/graph queries.md for inspecting the knowledge graph. Bootstrap Already signed in ( cargo ai whoami returns a workspace)? Skip to the next section. Every command prints JSON to stdout; failures exit non zero and print the error to stderr (piped: {"error": "...", "status": <http , "body": {"reason": "..."}} , where body.reason is the machine readable cause). Anything that creates a run or a batch is async — pass wait until finished or poll the matching get . runtime write and runtime edit commit and push to the workspace's context repo, so confirming workspace.name first is non negotiable. When the full skill bundle is installed, [ ../cargo/references/prerequisites.md ](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin only surface. Discover the context first Before editing anything, see what's in the context repo: Quick reference Runtime sandbox The runtime sandbox is a checked out, executable copy of the context repository. It's the surface you use to read and modify context files, and to run commands against them. Two important behaviors to remember: write and edit push to the default branch of the context repo. They are not local only. execute pushes too. When the command leaves tracked files added, changed, deleted, or renamed, those changes are auto committed (subject context(runtime): execute <command , or commit message ) and pushed to the default branch. Gitignored paths are skipped. A sed i or rm run through execute lands in git. Mirrored content files live read only under .files/ . A content file stored with mirrorToContext: true — the default for content file upload , web app uploads and defineFile (see [ cargo content ](../cargo content/SKILL.md)) — is committed and pushed to the context repo at .files/<folder path /<name (commits titled content(mirror): upsert <name , … move … , … remove … ; a file over 10 MB lands as a JSON metadata sidecar instead of its bytes). A command run via execute (or read / browse ) can consume them — e.g. cargo ai context runtime execute command ls args '[" 1",".files"]' . Files written by path ( content file put , the objects API, workers, the writeFile node, agent writes) default to mirrorToContext: false and are not there. You can't add or change anything under .files/ from the runtime ( deniedPath ) — use cargo ai content file … . Anyone who can read the context repo can read every mirrored file. Because writes push immediately, confirm the target workspace before the first write / edit : Read the workspace name back to the user. If the session is for a specific client, make sure workspace.name matches before authoring anything — there is no dry run mode. If workspace.name is generic or ambiguous (e.g. "Main", "Test", a person's name, an internal codename), don't guess — ask the user for the company name and canonical domain ( example.com ) and confirm both before the first write. If you logged in without pinning a workspace, re run cargo ai login oauth workspace uuid <uuid (or token <workspace scoped token for non interactive use). Edits derived from sales call analysis should be applied one at a time with human review , not batched. Looping an agent over many calls tends to overweight the loudest signal and miss nuance — see references/examples/lifecycle.md for the call refresh playbook. Browse and read Write a new file write creates (or overwrites) a file and pushes a commit to the default branch. Begin every .md / .mdx file with a YAML frontmatter block setting title and description . Frontmatter is not validated by write (a project's defineContext is — see [File conventions]( file conventions)) — a file with missing, empty, or malformed frontmatter is still written and committed; it just indexes poorly in the graph (a missing title falls back to the filename, the node summary to the first paragraph). write can still fail for other reasons — repositoryNotFound , failedToWrite (including a push that did not land), or deniedPath (e.g. writing under .files/ ); see references/response shapes.md . Edit an existing file edit replaces a single exact substring. old string must occur exactly once in the file (unless replace all is passed); pass an empty new string to delete the match. The strings are taken literally: \n inside ordinary double quotes is a backslash and an n , not a newline, so use bash $'...' quoting for multi line matches. 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 . For larger restructures, prefer write (full file overwrite) over many sequential edit calls. Execute a command in the sandbox execute runs a shell command in the sandbox (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. args is a JSON array of string arguments. Omit it for a no arg command. Context repository structure and conventions The Cargo context repo is a typed knowledge base. The canonical example — and the source of the conventions below — is [ getcargohq/cargo workspaces ](https://github.com/getcargohq/cargo workspaces); read its README.md and template.md files in each domain before writing new entries. For the full domain reference, see references/conventions.md . Domains Domain Purpose global/ Company level context: mission, voice, positioning, narrative, pricing icp/ Ideal Customer Profile segments persona/ Buyer personas (roles inside an ICP) jtbd/ Jobs to be done framings alternative/ Competitors, substitutes, status quo client/ Customer profiles, case studies, reference accounts insight/ Market insights and observations medium/ Channel playbooks (email, LinkedIn, cold call, etc.) objection/ Objections + responses + proof play/ GTM plays (signal → audience → channel → sequence → outcome) proof/ Atomic proof points (metrics, quotes, case data) signal/ Buying signals and intent triggers File conventions Filename: kebab case.md (e.g. vp sales mid market.md ). Frontmatter: start every .md / .mdx file with YAML frontmatter setting title and description . This is a strong convention, not enforced — a write with missing, empty, or malformed frontmatter is still created and committed; it just indexes poorly. The graph reads title (fallback: filename) and summary (fallback: 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. Cross references: use the domain/slug form, no .md extension (e.g. persona/vp sales mid market ). To register as a graph edge a reference must use one of the three link forms below — a bare domain/slug (or file path) in plain prose creates no edge. Templates: each domain ships an template.md . Read it ( cargo ai context runtime read path persona/ template.md ) before authoring a new entry. template. files are excluded from the graph — never reference them. Source references and graph edges The knowledge graph is built from every .md , .mdx , .yaml , and .yml file in the repo (any folder; only .git/ is excluded). Each file is a node, but edges are created only from three forms — anything else is invisible to the graph: 1. Frontmatter references: list (preferred for source citations — keeps prose clean): 2. A Markdown link in the body — standard [label] followed immediately by (path) syntax, where the target is the file path, e.g. an anchor linking to outputs/sales notes/2026 06 05 agorapulse build session 1 outcomes.md . 3. Wikilinks in the body (extension optional): [[outputs/sales notes/2026 06 05 agorapulse build session 1 outcomes]] . Key constraints: Never cite a source as a bare path in prose (e.g. a Source: line that just mentions outputs/sales notes/foo.md as text) — it is not parsed and creates no edge. Prefer root relative paths (resolved from the repo root first, then relative to the citing file) so links work regardless of where the document lives. Extensions are optional 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. The target must exist or the edge is broken (a dead link in the graph UI). Verify with runtime browse before citing. For docs with a Source / Evidence section, cite the files in frontmatter references: ; use inline markdown links when the citation needs surrounding prose. Full rules: references/conventions.md . Workflow: add a new entry 1. Confirm the target domain and copy its template: 2. write a new file at <domain /<slug .md with title + description and the body sections filled in. 3. Add cross refs ( domain/slug ) where useful — keep them bidirectional when it makes sense. 4. Rebuild the knowledge graph to verify the new entry and its links: For full per domain templates and worked examples, see references/conventions.md and references/examples/authoring.md . Workflow: bootstrap and refresh To stand up a new workspace's con