skills/getcargohq__cargo-skills
1
0
Fork 0
mirror of https://github.com/getcargohq/cargo-skills.git synced 2026-09-14 19:17:15 +08:00
Code Issues Packages Projects Releases Wiki Activity
167 Commits 109 Branches 0 Tags
docs/script-require-allowlist
Commit Graph

18 Commits

Author SHA1 Message Date
Auree Aubert bf23619313 Stop documenting the first-party enrichment provider (#122) 
* Stop documenting the first-party enrichment provider

Its playbook, its 21 priced actions, and every recipe step that led with it
are removed. Each one now leads with the rung the pack already named as its
fallback, so nothing here is invented — the replacements were sitting in
stage-action-map.md and alternatives.md the whole time.

The substitutions:

    firmographics   aiArk.enrichCompany (0.01) -> companyEnrich (0.25) -> waterfall (1)
    person          aiArk.enrichPerson (0.1) -> waterfall.enrichContact (2)
    funding         enrichCrm.getFunding (1), now the catalog's only one
    technographics  builtwith.getDomainSummary (free) -> enrichDomain (1)
    dedupe          free storage query against the workspace's own models

That last line is the one worth reading twice. The match actions existed to
mint an id the other actions required; every replacement keys on the domain
or a LinkedIn URL, so a step that cost 0.5/record now costs nothing.

The event feed has no replacement and the recipes say so. fetchBusinessEvents
took a timestamp_from and nothing else in the catalog does, so funding-watch,
re-engagement and lost-deal-revival are rewritten as a diff: re-pull, compare
against the stored round date, keep what moved. Cadence becomes the only cost
dial, which is why funding-watch's default drops from daily to weekly.

Every credit budget was recomputed rather than relabelled:

    build-tam        2,955 -> 2,210   (500 companies + 1,500 contacts)
    prospecting P2     821 ->   107   (200 verified prospects)
    icp-discovery      602 ->   204   (200 deals)
    context bootstrap    3 ->     1

Catalog counts now follow the generated data file rather than the older
hand-kept figure: 136 integrations, 176 credits-based actions of 513.

Also bumps the CLI pin 1.0.66 -> 1.0.78.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

* Fix the three generated artifacts the removal invalidated

CI caught what the local lint could not: skills-lint.mjs is only one of five
checks, and the other four all had something to say.

llms.txt was stale — it is generated from the skill descriptions, and
cargo-gtm's dropped a provider from its roster.

The codex package build enforces override version == upstream version, so
bumping only .github/package-overrides/cargo-quickstart.SKILL.md to 1.0.3 broke
it. The guard exists to stop the override silently shipping last month's demo,
so the fix is to bump both, not to revert the override.

That build also patches literal source strings at package time, and one anchor
ran through a line this branch rewrote:

    snitcher.searchSessions (0 cred) -> cargo.matchProspect
    snitcher.searchSessions (0 cred) -> aiArk.reverseLookup (0.05)

The edit strips the visitor-de-anonymisation path from the packaged skill, so a
silent miss would have shipped it. Re-anchored, and every other PACKAGE_EDITS
find string verified against the tree — 1 broken, now 0.

Also drops the packaged cargo-connection description from 138 integrations to
136, matching the repo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

* Say where revenue went, and that employee ratings went nowhere

Removing the provider took two data points off the map without replacing the
map entry, which is the failure mode this recipe's own feasibility gate exists
to prevent: an attribute that quietly stops being answerable reads the same as
one nobody asked for.

They are not the same case, so they get different rows.

Revenue and NAICS survive. companyEnrich.enrichByDomain (0.25) returns them in
the same call as firmographics, employees, funding and socials — so it fills
several rows at once and the row says that, because the per-account arithmetic
in step 4 gets it wrong otherwise.

Employee ratings have no successor at any price. Nothing credits-based in the
catalog returns Glassdoor-style employer reputation. The row says none, and
says to report it as a research note rather than substituting a scrape that
reads like the real thing — which is the recipe's stated position on valuable
attributes with no obtainable source, applied to itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

* Fix the data-flow breaks the provider swap left behind

Bugbot found eight, all real, and verifying them turned up five more. The
pattern in every case is the same: I replaced an action but left the code that
consumed its output reading the old response shape, so the step still runs,
still bills, and quietly returns nothing.

Response-shape breaks:

  funding-watch      Pattern A still filtered funding_rounds[].announced_date
                     while Pattern B read lastFundingDate. The 90-day select
                     matched nothing, so the primary path returned an empty
                     list after a paid pull.
  re-engagement      Step 5 read .results[] and .events[] from a file step 3
                     now writes as a bare array. Funding branch always empty.
  lost-deal-revival  Step 4 read .events[0] and expected a deal_id that
                     getFunding does not return. Step 3b now carries deal_id
                     through, which is the only place it exists.

Wrong-source breaks:

  re-engagement      The diff read last_funding_round_at off the Contacts
                     segment. It is a Companies column, so the stored date was
                     always empty and every account re-flagged every week. Now
                     queries the Companies model, and fans the company-level
                     signal back out to contacts, since step 5 unions on email.
  build-tam          Step 4 keyed searchLeads on .linkedinId from the
                     aiArk.enrichCompany output. No enrichment action returns a
                     Sales Navigator accountId. Now carried from the sourcing
                     step, with an explicit gate for rows that have none.
  guide              snitcher.searchSessions identifies a COMPANY; I had
                     chained it into aiArk.reverseLookup, which needs an email
                     or phone. Its own playbook says to route identified
                     domains through the enrich chain.

Budget break:

  prospecting        P2 step 5 ran FullEnrich over every lead while the budget
                     quoted the residue. 200 credits against 60. P1 had the
                     gate; P2 did not.

Pre-existing, fixed because the fixes above sit inside them:

  icp-discovery      [.[] | {domain}] over storage query execute output, which
                     is {rows: [...]}. Enriched one null domain, not 200.
  jq inputs[N]       `inputs` is a generator, not an array, so the union
                     expressions in re-engagement and lost-deal-revival errored
                     out. Slurped to [inputs] as $in.

Every rewritten jq expression was run against fixtures rather than eyeballed.

Also five provider mentions the sweep missed, because they wrote it as bare
`cargo` with a price rather than cargo.actionName: societeInfo, snitcher,
enrichCrm, linkedin, oceanio, apolloio, rocketreach.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

* Make funding-watch Pattern B stand on its own

It re-pulled two hardcoded example domains and then diffed them against
/tmp/targets.json, a Pattern A artifact. Run Pattern B alone and the slurp
fails; run both and it compares a fresh pull of one set against stored dates
for a different set, so the "new round" filter cannot fire correctly either way.

Both sides of a diff have to come from the same query. Now they do: one storage
read supplies the domains to pull *and* the stored dates to compare against, so
the sets align by construction and the pattern has no cross-dependency.

Also states what a missing stored date means — it compares against "" and always
passes, which is right on a first run and is exactly why the write-back step is
not optional. Without it every run is a first run and the watch re-flags the
whole segment forever.

Verified against fixtures: an account whose round moved is kept, one whose
stored date already matches is dropped, one with no stored date passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

* Route the questions people ask but the map never answered (#124)

Measured instead of guessed. Of the 176 credits-based actions, 148 were
reachable from a routing surface — the stage map, the phase guides,
alternatives.md, a recipe. The other 28 were reachable only from their own
provider playbook, which is findable if you already know which provider to
open. That is the wrong way round.

The worst of it: headcount had no section at all. It is the most-asked company
attribute and the first row of the custom-datapoints feasibility gate, and not
one of the four salesNavigator.find* actions appeared anywhere in the stage map.
New section carries all four, plus the only historical series
(companyEnrich.getWorkforce), plus linkedin.findCustomHeadcount for the roles
the fixed buckets don't have, plus the companyId prerequisite that quietly
turns a 0.25 action into 0.30 on a list that arrived without one.

"Who works at this domain" was not a documented question either. It is not the
same as searching a population by title, and it has two answers at very
different prices. New section, with the trap stated: looping hunter.searchDomain
to build a list is the pitfall its own playbook warns about.

Also adds rocketreach, mixrank and societeInfo to Enrich/Sourcing —
societeInfo reaches French registry data (NAF code, collective agreement,
filed accounts) that nothing else in the catalog does — and gives Hiring intent
a second index at the same price.

154/176 now. The remaining 22 stay unrouted on purpose, and the CHANGELOG says
why for each: the four LinkedIn engagement actions would undercut the
acceptable-use refusal to batch-blast them, three natives belong to other
skills, searchLeadsLegacy costs 300x its replacement, and the rest are finer
grain on an already-routed surface rather than separate questions.

One thing the build caught: adding aiArk.analyzePersonality re-introduced a
term the codex package deliberately strips, since the directory rejected
person-level inference. Kept for the channels that carry it, with matching
PACKAGE_EDITS so the package still removes it. Dropped the forager rung rather
than add machinery for a last-resort action priced 20x above its own chain.
All 67 anchors verified.


Claude-Session: https://claude.ai/code/session_019wkwbhrEoE5KW9A1CKBmcA

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-02 16:40:18 -07:00
Auree Aubert aead4ddc20 Search for actions, and config stopped shouting (#115) 
* Cargo has a first-party MCP, and `config` stopped shouting

Tracks the platform-MCP branch in the CLI repo: a first-party MCP server at
`/mcp`, a new `orchestration action list`, and `config` split off the top-level
action type. Two of those three contradict sentences this bundle stated as fact.

- The router, `cargo-ai`, and the glossary all said there is no first-party
  Cargo MCP server. There is one now, at `mcp.getcargo.io/mcp`, with a fixed
  operate-the-workspace toolset. Both surfaces — platform and curated — are
  documented, and the routing rule they exist for is unchanged.
- `cargo-ai mcp` with no `--server` now bridges the platform MCP rather than
  resolving "the workspace's only MCP server". Same command, different server
  by CLI version, so it is in the gotchas table.
- New `orchestration action list <keywords>`: free, searches connector, native,
  tool, and agent actions in one call, and returns a ready `action` object with
  `connectorUuid` resolved plus the action's credit costs.
- `config` is optional on execute/execute-batch and still required on nodes,
  alerts, play health actions, and get-output-schema. The dangerous half is the
  deleted guard: misplaced inputs are now dropped silently and the action runs
  with none.
- Nine documents were telling agents to do exactly that. The four LLM playbooks,
  the prompt-library index, and three GTM recipes put `model`/`advancedSettings`/
  `output` (or `customerId`, `spreadsheetId`) in the action's `config`; all now
  put inputs in `--data`/`--records`. The ads recipe also loses two
  `execute-batch --model-uuid --filter` calls against flags that do not exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

Co-authored-by: Auree Aubert <aureeaubert@users.noreply.github.com>

* Drop `config` from every top-level action, and lead with action search

The platform-MCP work shipped while this PR was open — CLI 1.0.66 is on npm and
the platform MCP answers at mcp.getcargo.io/mcp — so the hedging this branch was
written with ("newer backends accept…", "stays valid on any version") is now
just the rule.

- `config` is gone from 272 execute / execute-batch examples across 79 files.
  That is the shape `action list` returns, so a search result pastes straight
  into a run. Nodes, alert `--actions`, play `healthAlertActions`, and agent /
  MCP-server `--actions` keep theirs; the strip was scoped around them.
- `get-output-schema` is the exception and still requires `config` — verified
  live: the action object from `action list` fails 400 at `action.config`. The
  CLI's own help examples for that command omit it and therefore all 400. It is
  now a gotcha row, and those examples keep `"config": {}` on purpose.
- `connection action search` shipped in 1.0.36 and no skill had ever mentioned
  it. cargo-connection now opens with both searches and a table for choosing:
  `action list` by default, `action search` for `--credits-only` and
  `--category`. `integration list` / `integration get` drop to what they are
  good at — the integration, and the schema of an action already picked.
- Removed a phantom command: `connection integration list-actions` has never
  existed, and cost-discipline.md was recommending it as a free lookup.
- cargo-mcp gains the one config rule that surface needs: pass the action object
  as-is, never with a config — `get_action_schema` supplies the empty one, which
  makes MCP safer here than the CLI.

Verified against the live workspace at 1.0.66: a config-less `action execute`
returns status success at 0 credits, and `get-output-schema` without `config`
returns 400.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

* Fix the strip's leftovers, and bump the router so it actually ships

An audit of the 272-example strip turned up one real defect and a set of
phrasings the strip left behind, plus a packaging bug that would have made the
router's half of this PR a no-op.

- `cargo/SKILL.md` was still at 1.22.0, the version main already publishes, so
  its 14 changed lines — including both new critical rules and both new gotcha
  rows — would have been skipped at publish. Bumped to 1.23.0, plugin manifests
  follow.
- `guides/writing-outreach.md` still declared the action shape as
  `integrationSlug + actionSlug + config: {}` directly above an example whose
  config had been stripped. Every sibling "Action shape" line had been rewritten;
  this one was missed.
- Seven places said the action's config "is empty" or "stays empty" where the
  rule is now that there is no config key at all. Normalised, including the
  deliberate contrast in cargo-observability, where alert actions do require one.
- The report template in cargo-workspace-management modelled the old shape in a
  copyable `action execute` string, and cited `config.portalId required` as the
  symptom. Both corrected.
- perplexity's `searchContextSize` is an input, not a "config cost lever" — the
  same rewrite had moved it into `advancedSettings` in `--records`.

Verified clean afterwards: no execute example retains a config, no
get-output-schema example lost one, no node/alert/agent/mcp-server action lost
one, and every JSON block still parses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

---------

Co-authored-by: Auree Aubert <aureeaubert@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-27 16:42:39 -07:00
Auree Aubert 3708f8c955 Agent discoverability: trigger-shaped descriptions, routing evals, standalone bootstrap (#77) 
* Agent discoverability: trigger-shaped descriptions, routing evals, standalone bootstrap

The `description` field is the only text an agent weighs before deciding
whether to load a skill. Everything else in the bundle is invisible until
that decision is already made — and twelve of the seventeen descriptions
read as "Manage <CLI nouns> using the Cargo CLI", which matches a user who
is already thinking in Cargo's object model rather than one stating a job.

This rebuilds that layer and, for the first time, tests it.

Routing
- Every description rewritten to a four-part template: job in the user's
  words -> literal quoted trigger phrases -> proper nouns -> an explicit
  `Skip when:` pointing at the sibling skill that owns the adjacent case.
- Integration and provider names are generated, not hand-maintained.
  sync-trigger-slugs.ts fills cargo-gtm's `Providers:` list from the
  playbook tree and cargo-connection's `Integrations:` list from a
  committed catalog snapshot (138 integrations, 50 credits-based).
  `--refresh` re-pulls from a logged-in CLI; `--check` gates CI.
- evals/routing.jsonl (92 prompts) + routing-eval.ts, wired into CI.
  Structural tier asserts the template and that each skill keeps >=5 terms
  unique to it; lexical tier requires the expected skill to rank first;
  an opt-in --llm tier asks a real model to route from descriptions alone.
  Deep paraphrases are tagged "hard" and reported rather than gated — a
  lexical proxy cannot judge them fairly.

Standalone installs
- `skills add --skill <one>` is a supported path and the registry lists
  each skill separately, but thirteen skills' only install instructions
  were a relative link to ../cargo/references/prerequisites.md, which does
  not exist in a single-skill install. Every SKILL.md now has a
  self-contained Bootstrap section, enforced by the linter.

Coverage
- New capability skill cargo-segmentation — the segmentation CLI domain,
  previously uncovered while segments were load-bearing in most recipes.
  Verified against the live CLI, including the flag traps.
- Three cargo-gtm recipes: source-planning (probe and cost candidate
  sources per *hit* before any fan-out), ads-audience-activation (Google
  Customer Match / LinkedIn Matched Audiences), review-and-iterate (human
  review of judgment output, kept as an eval set).
- Router gains a "these skills vs a workspace MCP server" section: Cargo
  has no first-party MCP server — a workspace builds one and serves it
  over `cargo-ai mcp` — so the routing rule is scale and reproducibility.

Index and hygiene
- llms.txt now lists every recipe and provider playbook with a generated
  summary: 17 entries -> ~80 job-named addressable URLs.
- Router trimmed ~80 lines of per-skill summaries that restated each
  skill's own description; critical rules kept in full.
- Linter: bootstrap check, skill-count claims validated against the tree,
  `doctor` and `mcp` added to the known CLI domains.
- CONTRIBUTING.md, keyword-dense README opening, updated repo metadata.

Also carries the aiArk/apolloio priority-stack promotion authored in a
parallel session on this branch (cargo-gtm 1.12.0) — the two touch the
same SKILL.md files and could not be split cleanly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Surface the 100-credit free tier where an agent meets it

There is no purchase gate between installing Cargo and producing a real
deliverable — a new account starts with 100 free credits and no card — and
nothing in the bundle said so. An agent that doesn't know the budget can't
tell a first-time user whether the demo is a look around or a commitment,
and defaults to hedging.

Now stated at every point an agent encounters the question:

- README opening and the generated llms.txt install block: an agent can
  install, sign the user up, and hand back a list in one turn.
- Router install section and prerequisites.md, with anchors for what 100
  credits buys (~5,000 sourced leads, ~1,000 verified-email enrichments,
  ~50 fully enriched contacts).
- cargo-quickstart: the demo spends ~0.5 of the 100, and the skill now
  says so before the first paid call — that reframes the moment from a
  purchase decision into a look around, which is the job of a quickstart.
- cargo-billing: a "what 100 credits buys" table, plus two new trigger
  phrases so free-tier questions route here at all.
- cost-discipline.md: on a new account, receipts and next-step proposals
  must be framed against the free tier. "87.6 of your 100 free credits
  left" is a number the user can act on; "87.6 remaining" is not. Also
  warns that phone lookups (6-7/call) are the fastest way to burn a tier
  a first session should end with something left to try.

Two routing eval cases added for free-tier questions (79/79 core).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Run the routing evals against a real model in CI

The lexical tier passes 79/79, but it is a deterministic proxy written
alongside the descriptions it grades — it cannot fail in a way that
surprises us, which is what makes it weak evidence. The only honest
scoreboard for the description rewrite is whether a real model, shown
nothing but the 17 descriptions, routes the eval prompts correctly.

That tier existed but had never run. Now it does, in its own workflow.

- New .github/workflows/routing-evals-llm.yml, using the repo's
  ANTHROPIC_API_KEY. Deliberately not part of skills-lint: it costs money
  and is non-deterministic, so it must never stand between a typo fix and
  a merge. Triggers on PRs and pushes that touch a SKILL.md, the eval
  cases, or the runner; weekly on a schedule so model drift surfaces even
  when nobody edits a description; and on demand with a model override.
- runLlm reworked for CI: 6-way concurrency (92 sequential calls is a slow
  job), retry with backoff on 429/5xx, tolerant answer parsing, and a
  core/hard/overall breakdown instead of one number.
- Results are written to GITHUB_STEP_SUMMARY as a table, including every
  misroute with what the model picked instead — so a regression is
  readable on the run page without opening logs.
- Optional --llm-min=<percent> floor, wired to the exit code. Left unset
  until the first runs establish a baseline; a floor guessed before the
  data would either never fire or block on noise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Act on the first real-model routing run: 92/94, two fixes

Baseline from the model tier (claude-haiku-4-5, judging from the 17
descriptions alone): 92/94 overall — core 79/79, hard 13/15. The lexical
proxy's 3/15 on the hard tier was noise about the proxy, not the
descriptions, which is what that tier existed to establish.

Both misroutes were worth having:

- "Our outbound is going to the wrong people — help me figure out who
  actually buys from us" routed to cargo-context instead of cargo-gtm.
  A real collision: cargo-context's triggers include "who do we sell to",
  which reads as ICP ownership. It owns *writing the conclusion down*;
  deriving it from won/lost data is cargo-gtm. Added that boundary to
  cargo-context's Skip when, and the two phrasings to cargo-gtm.

- "Give the assistant access to our sales collateral so it stops making
  things up" routed to cargo-content instead of cargo-ai — and the model
  was right. As written the first step is getting the collateral into the
  workspace. Corrected the expectation and added the other side of the
  boundary as its own case ("attach the library we already uploaded to
  the agent"), which the lexical tier then failed, correctly: cargo-ai
  never said "library" or "release resources". Added both, so the
  content/ai split is now legible to a ranker and a model.

Set --llm-min=93 now that a baseline exists. Deliberately below the
observed 98%, not at it: a model tier that fails on one non-deterministic
flip trains people to ignore it.

Lexical 80/80 core.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Document cargo-ai mcp — the bridge that was written down nowhere

Cargo reaches coding agents through two doors. Skills reach agents that
implement skills.sh; a workspace MCP server reaches everything else —
Claude Desktop, ChatGPT, and whatever ships next. The second door was
fully built and documented in exactly one place: `cargo-ai mcp --help`.

Worse, cargo-ai/SKILL.md taught `ai mcp-server create` (building a server)
without ever mentioning the command that serves it, so an agent could
construct one and have no idea how to connect it — and the section
conflated publishing a server with consuming someone else's, which are
unrelated surfaces.

- MCP section rewritten around the two directions, with a table: publish
  (`ai mcp-server`, called by any MCP client, wired via `cargo-ai mcp`)
  vs consume (`ai mcp-client`, called by your agents, wired via
  `release update-draft --mcp-clients`). States plainly that there is no
  first-party Cargo MCP server — a workspace builds its own.
- Documents `cargo-ai mcp` with the registration one-liner, the
  CARGO_MCP_SERVER_UUID fallback, and the stdout-is-protocol constraint.
- Details verified against the live API rather than --help: actions take
  kind "tool" *or* "agent" (an agent is exposable as a callable MCP
  tool), resources take model or file, and `update` replaces the arrays
  wholesale instead of merging — a real footgun.
- Routing rule for which door to use, pointing at the router section.
- Two trigger phrases ("expose our tools as an MCP server", "use Cargo
  from Claude Desktop or ChatGPT") and two eval cases, so the publish
  direction is reachable from a description at all. It previously wasn't.

Lexical 81/81 core.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-12 10:18:32 -07:00
replicas-connector[bot] e28aabd521 Point the skills at browserless login, and unpin agents from a CLI that lacks it (#73) 
* Point the skills at browserless login, and unpin agents from a CLI that lacks it

cargo-ai 1.0.47 (2026-08-10) added `login --email`: it mails a one-time code,
creates the account on first use, and needs no browser at any point. All 16
skills still described sign-in as "browser sign-in via --oauth, or an API
token".

The load-bearing change is `cargo/cli-version`. The router tells every agent to
run `npm install -g @cargo-ai/cli@$(cat cli-version)` at session start, and that
pin was 1.0.29 (2026-07-09). Its `login` command exposes only --oauth, --token
and --workspace-uuid, so documenting --email without moving the pin would ship a
flag the installed binary does not have.

- cargo/cli-version: 1.0.29 -> 1.0.47
- 16 compatibility lines rewritten
- router + README install blocks lead with --email, and name the agent-shell
  behaviour (no terminal: first call sends the code and exits, re-run with
  --code) and the stdin form
- patch version bump on each changed SKILL.md so clawhub republishes them

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

* Regenerate skill-metadata.json for the changed skills

The bundle linter tracks a version and a contentHash per skill and failed with
19 stale entries. Regenerated with the documented command, so the diff is only
the bumped versions and their matching hashes.

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

* Mirror the router version bump into the three plugin manifests

The linter requires .claude-plugin, .codex-plugin and .cursor-plugin to carry
the router's version. 1.17.0 -> 1.17.1.

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

---------

Co-authored-by: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>
Co-authored-by: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
 2026-08-11 14:42:02 -07:00
Auree Aubert 286aaaf981 feat: prompt library + generated skill metadata (#55) 
Rebased onto main (post #53/#54 squash): 38 named parameterized LLM prompts in
six sharded files with a grep-first index (temperature guidance scoped to the
bulk tier; judgment-tier models that reject non-default sampling get no
override), plus a generated skill-metadata.json per skill — typed doc catalog
+ deterministic content hash (code-unit ordering, locale-independent),
produced by .github/scripts/skills-metadata.mjs (--write) and verified by
skills-lint.mjs so stale metadata fails CI. Metadata regenerated over main's
tree, which is why lint was failing before: the catalogs predated main's
email_status recipe fix. cargo-gtm -> 1.4.0.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
 2026-07-10 00:26:04 -07:00
Auree Aubert f87eeebe34 Document graph edges, frontmatter validation, and source citations (#39) 
* docs(cargo-context): document graph linking rules and server-side frontmatter enforcement

Linking guidelines (how context-graph edges actually form):
- Add "Source references and graph edges" sections to cargo-context
  SKILL.md and references/conventions.md covering the three edge-creating
  forms (frontmatter references:, markdown links, wikilinks), the
  no-bare-paths rule, root-relative resolution, optional extensions,
  broken-target behavior, _template.* exclusion, and YAML/title/summary
  parsing.
- Update cross-reference and template bullets to note edges only form via
  the three link forms.
- Add a source-citation example to references/examples/authoring.md and
  point the repetition-threshold guidance at frontmatter references:.

Frontmatter enforcement (422 / invalidContent):
- Update the File conventions frontmatter bullet plus the write and edit
  sections in SKILL.md to describe server-side rejection and recovery.
- Add invalidContent troubleshooting entries (missing fields, malformed
  YAML, edit-strips-meta) and write/edit error reasons in
  references/response-shapes.md.
- Refresh the cargo-context recap in the top-level overview.

* fix(cargo-context): correct frontmatter rules to match backend (soft-fail, no 422)

The earlier frontmatter-enforcement docs described a write/edit validation
gate (HTTP 422, reason "invalidContent") and a description->graph-summary
fallback that the backend does not implement. The runtime write/edit
services have no frontmatter validation, and the graph builder fails soft:
a missing title falls back to the filename and the node summary to the
first paragraph (the graph reads `summary`, never `description`).

Align the skill with the actual capability behavior:
- Reframe frontmatter as a strong convention, not enforced — missing/empty/
  malformed frontmatter is still committed, it just indexes poorly.
- Replace the invalidContent/422 notes in SKILL.md (write + edit), the File
  conventions bullet, conventions.md, authoring.md, and the overview recap.
- List the real write/edit failure reasons in response-shapes.md and
  troubleshooting.md (repositoryNotFound, syncConflict/syncFailed,
  failedToWrite/failedToEdit, stringNotFound/stringNotUnique, fileNotFound,
  noOp, deniedPath).
- Fix the node-summary source: `summary` (fallback first paragraph), not
  `description`.

The linking rules (edge origins, resolution order, _template/.git
exclusion) were already accurate and are unchanged.

* fix(cargo-context): stop skills-lint flagging illustrative source-link examples

The internal-link checker regex-scans whole files (code fences and inline
code included) and resolves every `[text](target)` against the skills repo.
The example source paths (`outputs/sales-notes/...`) point into a workspace
context repo, so they never exist here and were reported as broken links.

Keep the examples but avoid literal `](fake-path)` for the markdown-link
form: describe the `[label]`+`(path)` syntax with the path in inline code,
and switch the authoring example's body citation to an aliased wikilink
(which forms a real edge and isn't matched by the link checker). The
frontmatter `references:` and wikilink illustrations are unchanged.

skills-lint now passes: 0 errors, 0 warnings.

* docs(cargo-context): trim verbose error-reason lists from response-shapes

The write/edit "Error reasons" lines enumerated internal failure codes
(repositoryNotFound, syncConflict, syncFailed, failedToWrite, etc.) that
are accurate but generic infra detail — redundant with the generic error
shape documented at the top of the file, and not actionable for context
authoring. Keep only the load-bearing points (frontmatter is not validated;
the .files/ denied-write case) and point to troubleshooting.md, which
already holds the full reason enumeration.

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-06-11 23:19:01 -07:00
Auree Aubert 4c933393dd Extract content domain into dedicated cargo-content skill (#35) 
* Migrate file/library docs to the new content domain + register new CLI surfaces

The CLI moved workspace files and knowledge libraries out of the `ai` domain
into a new top-level `content` domain (`content file`, `content library`), and
added inline `ai document`. The old `cargo-ai ai file ...` commands no longer
exist.

- cargo-ai (2.0.0): migrate every `ai file` reference to `content file`;
  document `content library` (native vs connector-backed) and `ai document`;
  rename the Files section and add a command-surface-change callout.
- cargo (1.2.0): register the content domain in the recap/table, add a
  "CLI domains without a dedicated skill yet" table (segmentation, expression,
  system-of-record, revenue-organization, hosting, user-management), add
  glossary entries for the content domain and libraries.
- cargo-context (1.0.2), cargo-orchestration: fix cross-skill RAG examples.
- skills-lint: add the new CLI domains to the known-domain allowlist.

* cargo-context/cargo-ai: document content files exposed read-only under .files/

Uploaded `content file` knowledge surfaces in the context runtime sandbox under
a read-only `.files/` directory that sits outside the committed context tree, so
sandbox commands can consume content uploads without round-tripping them back
into the context repo.

* Split the content domain into a dedicated cargo-content skill

The content CLI domain (files + libraries) was documented inside cargo-ai.
Per the repo's one-skill-per-CLI-domain convention, extract it into its own
cargo-content capability skill:

- New cargo-content/ skill: files + libraries command docs, the moved
  examples/files.md walkthrough, response shapes, and troubleshooting.
- cargo-ai keeps inline documents (ai document) and the attach-to-agent
  wiring; cross-links cargo-content for files/libraries.
- Register cargo-content across the router overview (cargo/SKILL.md table,
  recap, dependency diagram/rules, counts), glossary, README, and AGENTS.md.
- cargo-context documents content files mounted read-only under .files/.
- Version bumps: cargo 1.3.0, cargo-ai 2.1.0, cargo-content 1.0.0,
  cargo-context 1.1.0; CHANGELOG updated.

* Drop ai document from cargo-ai; correct content file response shape

- Remove the low-value ai document (inline documents) commands from cargo-ai
  and scrub document references from the router overview, README, glossary,
  and the cargo-content files.md walkthrough.
- Reframe cargo-ai's knowledge section around files & libraries only.
- Update the content file list response shape to match the workspace File
  type: libraryUuid, userUuid, isIndexedInOpenAiVectorStore, externalId,
  deletedAt, and the native/connector kind union (connectorUuid).

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-06-08 00:42:38 -07:00
Auree Aubert c7bec7d8c4 Share prerequisites, lint SKILL.md, deep-link the router (#33) 
- Extract the duplicated install/login/output-conventions block from every
  capability skill into cargo/references/prerequisites.md. Each capability
  skill now links to it instead of redefining ~16 lines of boilerplate.
- Add CHANGELOG.md so per-skill version bumps are tracked alongside the
  reason for each bump, and capture the current version snapshot as the
  historical baseline.
- Add a CI skill-lint job (.github/workflows/skills-lint.yml +
  .github/scripts/skills-lint.mjs) that validates SKILL.md frontmatter
  shape, internal markdown links, fenced JSON snippets, and that bash
  examples reference real cargo-ai domains. Catches drift before users do.
- Reorder cargo-connection so the integration/connector key concepts sit
  above Prerequisites (where they're needed before reading commands), and
  tighten the integration get vs native-integration get table with ✓/✗
  markers to make mis-routing harder.
- Deep-link the skill graph in cargo/SKILL.md so each row in the
  capability table jumps straight to the target SKILL.md, with the
  in-page recap available as a secondary link.
- Bump versions on each touched skill.

Co-authored-by: Claude <noreply@anthropic.com>
 2026-05-28 15:11:38 -07:00
Auree Aubert 5f0add1460 Pin @cargo-ai/cli to latest and add Claude Code session hook (#29) 
* Add SessionStart hook and document staying current

Adds a Claude Code SessionStart hook that auto-updates @cargo-ai/cli
and the cargo-skills bundle at the start of every remote session, pins
@latest in every openclaw install block, and adds a "Staying current"
section to the README covering Claude Code, OpenClaw, and skills.sh
agents. Ignores .claude/skills/ since the hook materializes it on each
run.

* Promote refresh-to-latest to first step in router SKILL.md

Moves the update commands from a buried "if the user asks" conditional
to a top-of-skill default that any agent loading the cargo router sees
first. Fixes the broken `skills add ...@latest` syntax (the skills CLI
parses @latest as a skill name filter and fails). Slims the lower
section to cover only mid-session re-refresh triggers.

* Remove Claude-Code-specific hook from repo root

The SKILL.md "First step every session" guidance now covers refresh
cross-agent via prompt-level instruction, so the .claude/ hook only
served maintainers of this repo (not end users — skills add never
propagated it). Removing it keeps cargo-skills agent-neutral.

Users who want enforced (not prompt-level) refresh in Claude Code get
the full hook + settings.json recipe inlined in the README's
"Staying current > Claude Code" subsection.

* Instruct Claude Code agents to offer scaffolding the SessionStart hook

Adds a tightly-gated prompt-level instruction in cargo/SKILL.md: in
Claude Code sessions where no SessionStart hook exists yet, the agent
offers once to scaffold the auto-refresh hook using the recipe from
the README. No-op for Cursor/Windsurf/OpenClaw/etc.

* Drop bogus "report reply" mid-session refresh trigger

The CLI exposes report create but no way to read replies, so the
"workspaceManagement report reply confirms the issue is fixed" bullet
described a feedback loop that doesn't exist. Removed — the remaining
two triggers (shape mismatch, explicit user ask) are concrete.

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-05-28 12:53:17 -07:00
Auree Aubert 1b62ca6f0f Normalise reference layout across skills (#28) 
Move per-command examples in cargo-orchestration from
references/*.md into references/examples/*.md to match the
established standard used by cargo-ai, cargo-analytics,
cargo-billing, cargo-connection, cargo-storage, and
cargo-workspace-management. Concept references (filter-syntax,
nodes, polling, response-shapes, troubleshooting) stay at the
references/ root.

Add a cargo-context/references/response-shapes.md stub so context
also matches the standard layout. conventions.md keeps its
top-level slot as a concept reference (the same pattern that
filter-syntax/nodes/polling occupy in orchestration).

Rewrites all inbound cross-references in cargo-analytics,
cargo-gtm (SKILL, agent, guides, recipes), cargo-orchestration,
and cargo-workspace-management.

Co-authored-by: Claude <noreply@anthropic.com>
 2026-05-28 12:26:49 -07:00
Auree Aubert e169f58b9e Extract bootstrap automation into dedicated recipe (#27) 
* Add bootstrap-context-from-domain recipe to cargo-gtm

Promotes Phase 1 of cargo-context/.../bootstrap-and-update.md into a
first-class, automatable cargo-gtm recipe. Takes a domain as input,
inventories existing context via runtime browse + graph get to skip
already-seeded domains, enriches via cargo native, scrapes public
sources in parallel sub-agents, and writes one file per atomic concept
through context runtime write. Refresh-from-calls (Phase 2) is
deliberately out of scope and pointed back at cargo-context.

* Trim Phase 1 of bootstrap-and-update to point at the cargo-gtm recipe

The mechanics of public-source seeding now live in
cargo-gtm/recipes/bootstrap-context-from-domain.md. Collapse the
duplicated steps here to a pointer, and let this doc focus on what
only cargo-context owns: workspace-identity guardrails, Phase 2
call-driven refinement, validation by sequence permutation, the
2-4 week cadence, and the "what not to automate" stance.

* Move bootstrap-from-domain recipe to cargo-context

Bootstrapping the workspace's own self-knowledge is a cargo-context
lifecycle event, not an ad-hoc GTM execution recipe. Every other
cargo-gtm recipe targets external prospects or accounts; this one
targets the workspace itself, which is what cargo-context owns.

Move the file alongside its sibling bootstrap-and-update.md, fix the
in-file relative paths, drop the cargo-gtm recipes-table row, and
replace it with a one-line pointer so the front-door router still
surfaces it. Add a forward link from cargo-context/SKILL.md's
"bootstrap and refresh" workflow section.

* Drop the anthropic.instruct double-hop from bootstrap-from-domain synthesis

The recipe is executed by an agent that is already an LLM (Claude in
Claude Code, or whatever drives the session). Bouncing through
cargo-ai orchestration action execute --integrationSlug anthropic to
synthesize markdown is a double-hop that burns Cargo credits for work
the driving agent does natively. Have the agent draft the file body
directly and pipe it into context runtime write.

Keep the action-execute pattern documented as the right approach
for batch synthesis inside a workflow node graph (Play/Tool), where
no agent is in the loop. Adjust the credit budget accordingly
(~3 Cargo credits total, with agent LLM tokens counted separately).

* Move bootstrap pointer from cargo-gtm to cargo/SKILL.md

Cross-skill routing belongs in the root umbrella, not in cargo-gtm.
cargo-gtm's job is to route within GTM execution; a "this is really
cargo-context" pointer is a cross-skill decision and lives in cargo.

Drop the pointer from cargo-gtm and add a Lifecycle subsection under
cargo-context in cargo/SKILL.md that surfaces both bootstrap-from-domain
(prescriptive seed) and bootstrap-and-update (full lifecycle playbook).

* Fix drift in lifecycle doc after splitting Phase 1 into its own recipe

Rename bootstrap-and-update.md to lifecycle.md. The "bootstrap" half is
now three lines pointing at bootstrap-from-domain.md; the file is really
about the refresh lifecycle, and the old name and title overpromised.

Renumber Phase 2 steps to start at 1. They were inherited as 4-8 from
when steps 1-3 were the Phase 1 scrape/seed/fresh-session steps -
which moved out with the recipe. Step references in the intro
("Step 5") and "What not to automate" ("steps 5 / 5b") follow.

Drop the upfront "capture three things" list. The domain and workspace
UUID belong to the recipe (and it captures them in its own Step 1).
The call-volume estimate is Phase 2-specific - moved into step 1 of
Phase 2 where the repetition threshold actually consumes it.

Update the stale "now packaged as a cargo-gtm recipe" framing - it
lives in cargo-context now. Update all nine inbound cross-references
(cargo-context/SKILL.md x3, conventions.md, cargo/SKILL.md, and the
recipe's own three back-references).

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-05-28 12:01:13 -07:00
Auree Aubert f607681791 Restructure skill metadata for OpenClaw compatibility (#25) 
* Make cargo skills installable on OpenClaw via ClawHub

Promote `version` to top-level frontmatter and add `metadata.openclaw`
(requires.bins + install spec for @cargo-ai/cli) to every SKILL.md so
the bundle resolves through ClawHub without a separate manifest. Adds a
README install snippet for the `clawhub install` command.

* Add GitHub Actions workflow to publish skills to ClawHub on release

Triggers on `release: published` (and supports manual workflow_dispatch
with optional dry_run). Iterates the ten skill directories, reads
`version:` from each SKILL.md, and calls `clawhub skill publish` with
the release notes as the changelog. Treats "version already published"
as a skip so unchanged skills don't fail the run, and surfaces any
other publish error.

Auth uses the `CLAWHUB_AUTH` env var (avoids writing the token to disk)
sourced from a `CLAWHUB_TOKEN` repo secret. README documents the
one-time secret setup.

* Fix ClawHub publish workflow against the real CLI surface

The previous workflow was built from hallucinated WebFetch summaries.
After reading openclaw/clawhub's docs/cli.md and docs/auth.md directly:

- Auth uses `clawhub login --token <token>`, not a `CLAWHUB_AUTH` env
  var, so the workflow now runs a login step. Tokens are generated
  from the clawhub.ai web UI after GitHub sign-in (the previous
  `clawhub.openclaw.ai/settings/tokens` URL doesn't resolve).
- `clawhub skill publish` only accepts `--version`, `--owner`,
  `--migrate-owner`, and `--clawscan-note`. The previous workflow's
  `--slug`, `--name`, and `--changelog` flags don't exist; slug is
  derived from folder name. Workflow now passes only `--version` plus
  `--owner getcargohq` so the bundle lives under the org publisher.
- ClawHub requires semver three-part versions; bumped each SKILL.md
  `version:` from `1.0`/`1.1`/`1.4` to the matching `x.y.0` form so
  the CLI's semver check passes.
- README updated with the corrected token URL (clawhub.ai) and a
  reminder to run `clawhub publisher create getcargohq` once before
  publishing under the org.

* Drop redundant `license: MIT` from each SKILL.md frontmatter

ClawHub publishes every skill under MIT-0 and its skill-format spec
says: "Do not add conflicting license terms in SKILL.md; ClawHub does
not support per-skill license overrides." The repo LICENSE at the root
still applies to the source files; the per-skill frontmatter only
needs to drop the field so the published bundle doesn't trip the
metadata-conflict check.

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-05-28 11:17:40 -07:00
Claude 5ca6626286 Fall back to company domain when workspace name is ambiguous 
workspace.name is user-set and often generic ("Main", "Test", a
person's name), so confirming it back to the user is not always enough
to identify the client. Instruct the agent to ask for the canonical
company domain as a disambiguator before the first runtime write.
 2026-05-12 23:15:00 +00:00
Claude c71639cca8 Anchor context edits to a confirmed target workspace 
runtime write/edit push immediately to the workspace's context repo, so
agents and consultants managing multiple client workspaces need to
verify workspace.name from whoami before authoring. Adds a "Before you
start" section to the bootstrap playbook covering workspace selection,
domain capture, and call-volume estimation for the repetition threshold.
 2026-05-12 23:11:03 +00:00
Claude 8fdd8ba624 Add bootstrap-and-update playbook for context repos 
Codify the two-phase workflow for hardening a workspace's context: a
one-time public-source bootstrap, then a sales-call-driven refresh loop
on a 2-4 week cadence. Adds a repetition-threshold authoring rule for
call-derived claims and an explicit human-in-the-loop note so agents
don't batch call analysis into context edits.
 2026-05-12 22:50:37 +00:00
Auree Aubert 774db2062f Add references for cargo-context skill 
Adds references/conventions.md, references/troubleshooting.md, and
references/examples/{authoring,graph-queries}.md, mirroring the layout of
cargo-ai and cargo-workspace-management. Links them from the skill's intro
blockquotes.
 2026-05-11 22:44:40 -07:00
Auree Aubert 344a60bb76 Drop repository subcommand from cargo-context skill 
Removes documentation for `cargo-ai context repository get` and `... update`.
The skill now covers only `runtime` and `graph`.
 2026-05-11 22:29:22 -07:00
Auree Aubert 967eb8eb95 Add cargo-context skill documenting the CLI 
Documents `cargo-ai context` commands (repository, runtime, graph) and how
they map onto the git-backed context repo structure (the 13 GTM domains and
file conventions from cargo-workspaces).
 2026-05-11 22:19:22 -07:00