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; execute runs are not pushed. graph — build/load the knowledge graph derived from every markdown/MDX file in the context repo. The canonical example of a context repository is [ getcargohq/cargo workspaces ](https://github.com/getcargohq/cargo workspaces). Read its README.md to understand the domain layout and file conventions before writing new entries. For uploading runtime independent files (CSVs, PDFs) used in batch runs, use [ cargo workspace management ](../cargo workspace management/SKILL.md) ( cargo ai workspaceManagement file upload ) instead. For RAG file attachments to agents, use [ cargo ai ](../cargo ai/SKILL.md) ( cargo ai content file upload ). See references/conventions.md for the full context repo structure and per domain templates. See references/response shapes.md for the JSON shapes returned by each cargo ai context command. See references/troubleshooting.md for common errors and how to fix them. See references/examples/authoring.md for end to end add / edit / delete recipes. See references/examples/lifecycle.md for the bootstrap + refresh from calls playbook. See references/examples/graph queries.md for inspecting the knowledge graph. Bootstrap Already signed in ( cargo ai whoami returns a workspace)? Skip to the next section. Every command prints JSON to stdout; failures exit non zero with {"errorMessage": "..."} . Anything that creates a run or a batch is async — pass wait until finished or poll the matching get . runtime write and runtime edit commit and push to the workspace's context repo, so confirming workspace.name first is non negotiable. When the full skill bundle is installed, [ ../cargo/references/prerequisites.md ](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin only surface. Discover the context first Before editing anything, see what's in the context repo: 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 does not push. Changes made to files by a shell command run via execute stay in the sandbox and are discarded — use execute for builds, tests, or inspection, not for committing edits. Uploaded content files are available read only under .files/ . The workspace's content file uploads (PDFs, CSVs, text — see [ cargo content ](../cargo content/SKILL.md)) appear in the sandbox under a .files/ directory, so a command run via execute (or read / browse ) can consume them — e.g. cargo ai context runtime execute command ls args '[" 1",".files"]' . It sits outside the committed context tree : the sandbox's auto commit skips it, so nothing under .files/ is ever pushed to the context repo, and you can't add or change content files from here (use cargo ai content file … instead). Because writes push immediately, confirm the target workspace before the first write / edit : 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 — a file with missing, empty, or malformed frontmatter is still written and committed; it just indexes poorly in the graph (a missing title falls back to the filename, the node summary to the first paragraph). write can still fail for other reasons — repositoryNotFound , syncConflict , syncFailed , failedToWrite , or deniedPath (e.g. writing under .files/ ); see references/response shapes.md . Edit an existing file edit replaces a single exact substring. old string must occur exactly once in the file; pass an empty new string to delete the match. edit does not validate frontmatter — an edit that strips or empties title / description still applies, so keep the block intact to keep the node discoverable. edit can fail for other reasons, though: stringNotFound / stringNotUnique (the old string match), fileNotFound , noOp (new string equals old), syncConflict / syncFailed , failedToEdit , or deniedPath . For larger restructures, prefer write (full file overwrite) over many sequential edit calls. Execute a command in the sandbox execute runs a shell command in the sandbox. Useful for inspecting structure or running checks; changes are not pushed . args is a JSON array of string arguments. Omit it for a no arg command. Context repository structure and conventions The Cargo context repo is a typed knowledge base. The canonical example — and the source of the conventions below — is [ getcargohq/cargo workspaces ](https://github.com/getcargohq/cargo workspaces); read its README.md and template.md files in each domain before writing new entries. For the full domain reference, see references/conventions.md . Domains Domain Purpose global/ Company level context: mission, voice, positioning, narrative, pricing icp/ Ideal Customer Profile segments persona/ Buyer personas (roles inside an ICP) jtbd/ Jobs to be done framings alternative/ Competitors, substitutes, status quo client/ Customer profiles, case studies, reference accounts insight/ Market insights and observations medium/ Channel playbooks (email, LinkedIn, cold call, etc.) objection/ Objections + responses + proof play/ GTM plays (signal → audience → channel → sequence → outcome) proof/ Atomic proof points (metrics, quotes, case data) signal/ Buying signals and intent triggers File conventions Filename: kebab case.md (e.g. vp sales mid market.md ). Frontmatter: start every .md / .mdx file with YAML frontmatter setting title and description . This is a strong convention, not enforced — a write with missing, empty, or malformed frontmatter is still created and committed; it just indexes poorly. The graph reads title (fallback: filename) and summary (fallback: the file's first paragraph); it does not read description , so add a summary: if you want to control the node summary. See [Source references and graph edges]( source references and graph edges). Cross references: use the domain/slug form, no .md extension (e.g. persona/vp sales mid market ). To register as a graph edge a reference must use one of the three link forms below — a bare domain/slug (or file path) in plain prose creates no edge. Templates: each domain ships an template.md . Read it ( cargo ai context runtime read path persona/ template.md ) before authoring a new entry. template. files are excluded from the graph — never reference them. Source references and graph edges The knowledge graph is built from every .md , .mdx , .yaml , and .yml file in the repo (any folder; only .git/ is excluded). Each file is a node, but edges are created only from three forms — anything else is invisible to the graph: 1. Frontmatter references: list (preferred for source citations — keeps prose clean): 2. A Markdown link in the body — standard [label] followed immediately by (path) syntax, where the target is the file path, e.g. an anchor linking to outputs/sales notes/2026 06 05 agorapulse build session 1 outcomes.md . 3. Wikilinks in the body (extension optional): [[outputs/sales notes/2026 06 05 agorapulse build session 1 outcomes]] . Key constraints: Never cite a source as a bare path in prose (e.g. a Source: line that just mentions outputs/sales notes/foo.md as text) — it is not parsed and creates no edge. Prefer root relative paths (resolved from the repo root first, then relative to the citing file) so links work regardless of where the document lives. Extensions are optional — the resolver auto tries .md , .mdx , .yaml , .yml in that order. Including the extension is fine. The target must exist or the edge is broken (a dead link in the graph UI). Verify with runtime browse before citing. For docs with a Source / Evidence section, cite the files in frontmatter references: ; use inline markdown links when the citation needs surrounding prose. Full rules: references/conventions.md . Workflow: add a new entry 1. Confirm the target domain and copy its template: 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 context repo from scratch, or to refresh an existing one on a cadence, follow the two phase lifecycle in references/examples/lifecycle.md : 1. Bootstrap (one time): seed global/ , persona/ , client/ , proof/ , objection/ , signal/ from public sources, then open a fresh agent session against the seeded repo. For the prescriptive, automatable version (domain in → files out, idempotent, with credit budget), use references/examples/bootstrap from domain.md . 2. Refresh (every 2–4 weeks): pull the last ~3 months of sales call transcripts → analyze one at a time, human in the loop → apply a repetition threshold before promoting any claim to context → validate by generating sequence permutations → diff the graph before/after and retire stale entries. The repetition threshold (how many calls a claim must appear in before it lands in context) is documented in references/conventions.md . Knowledge graph context graph get builds (or loads from cache) the knowledge graph over every markdown/MDX file in the context repo. Use it to: Audit cross references between domains (e.g. find personas that link to plays with no proof attached). Discover what already exists before writing a new entry (avoid duplicates). Power downstream agents that need the typed structure of the workspace's context. The response includes the parsed frontmatter and outbound domain/slug references for each node — pipe it through jq to slice it. See references/examples/graph queries.md for ready to run queries. Help Every command supports help :

cargo-context