@caveman-ai/cloud 0.1.0-rc.28 → 0.1.0-rc.29

package/dist/skills/caveman-cloud/references/caveman-cloud-dashboards.md

@@ -9,47 +9,47 @@ description: >
 
 # Build dashboards from what the data shows
 
-A chart is a JSON spec, not SQL: a `source` (requests, spans, tools or evals),
-1 to 6 `measures` (`{field, agg}` or an `expr` such as `count_if(error) / count()`),
+A chart is a JSON spec, not SQL: a `type` (`timeseries`, `toplist` or
+`bignumber`), a `source` (`requests`, `spans`, `tools` or `evals`), 1 to 6
+`measures` (`{field, agg}` or an `expr` such as `count_if(error) / count()`),
 optional `filters.row` / `filters.trace` expressions, and a `group_by` field.
-The server compiles it over a fixed field catalog. Use `cvm`, or the Caveman
-Cloud MCP (`caveman_describe`, `caveman_read`, `caveman_write`).
+The server compiles it over a fixed field catalog.
 
 ## 1. Read what exists
 
-Run `cvm context show` (or call `caveman_context`) and confirm the project. List dashboards with
-`dashboards.list`; the `builtin:*` ones are read-only, so clone one through
-`dashboards.create` with `source_dashboard_id` instead of rebuilding it.
-
 ```sh
-cvm dashboards list
-cvm charts catalog
+cvm dashboards list | jq '.data.dashboards[] | {id, name, builtin}'
+cvm charts catalog --range 7d | jq '.data.suggestions'
 ```
 
-`charts.catalog` returns every source's fields (kind, unit, permission),
-the aggregations, ready presets, and up to eight suggestions with a reason
-read off the project's traffic. Start from a suggestion or preset when one
-fits; `charts.values` without a field returns ready filter expressions.
+`builtin:*` dashboards are read-only: clone one with `dashboards.create` and
+`source_dashboard_id` instead of rebuilding it. `charts.catalog` returns every
+source's fields (kind, unit, permission), the aggregations, ready presets and
+up to eight suggestions read off the project's traffic, each with a reason.
+Start from a suggestion or preset when one fits. `cvm charts values` without
+`--field` returns ready filter expressions; with `--field model` the top
+values.
 
 ## 2. Draft and verify each chart
 
-Write the spec, then run it before saving:
-
 ```sh
-cvm charts query --file chart.json
+cvm charts query --file chart.json | jq '.data | {overall, groups_total, warnings, notices}'
 ```
 
-Input is `{"chart": {...}, "range": {"preset": "7d"}}`. A 422
-`cave_chart_invalid` names the `target` and `position` to fix. Keep a chart
-only when its series hold data; read `notices` (unpriced requests are excluded
-from cost, never counted as zero) and `warnings` (slow shapes) and act on them.
+`chart.json` is `{"chart": {...}, "range": {"preset": "7d"}}` (presets `1h` to
+`90d`, or `from`/`to`). A 422 `cave_chart_invalid` names the `target` and
+`position` to fix. Keep a chart only when its series hold data. Read
+`notices` (unpriced requests are left out of cost, never counted as zero) and
+`warnings` (slow shapes). `cvm charts samples --file chart.json` lists the
+traces behind a chart or a point.
+
 Fields `member` and `api_key` need billing:read; `tags.*` and `attributes.*`
-need payload:read (request tags also billing:read); a 403 `cave_chart_forbidden`
-means pick another field, not a broader credential.
+need payload:read (request tags also billing:read). A 403
+`cave_chart_forbidden` means pick another field, not a broader credential.
 
 Filter grammar: `model = 'x'`, `latency > 2`, `status_code in (500, 502)`,
-`tags.branch is not null`, `model contains 'claude'`, joined with and/or/not.
-Text is single-quoted. Duration is seconds, cost is USD, percent is 0 to 1.
+`tags.branch is not null`, `model contains 'claude'`, joined with and, or,
+not. Text is single-quoted. Duration is seconds, cost USD, percent 0 to 1.
 
 ## 3. Save
 
@@ -61,12 +61,18 @@ cvm dashboards add_chart --file add.json
 `dashboards.add_chart` takes `{"dashboard_id": ..., "chart": {...}}` and
 appends atomically. `dashboards.update` needs the `version` you read; a 409
 `cave_dashboard_conflict` means re-read and reapply. Name charts for the
-question they answer. Do not save a chart you did not run.
+question they answer. Never save a chart you did not run.
+
+## 4. Alerts
+
+`alerts.create` watches one `bignumber` query over `window_minutes` against a
+`threshold` with a `comparator`. When it fires or resolves, the
+organization's owners and admins get an Inbox item and an email;
+`webhook_id` also posts to an existing webhook. Run the same query with
+`charts.query` over that window first to pick a threshold that would not fire
+today, and tell the user who it notifies. `cvm alerts list` shows what exists.
 
-## 4. Alerts (optional)
+Good output: the dashboard id and its console link, each chart's title with
+the `overall` figure it returned, and any alert with its threshold and recipients.
 
-`alerts.create` watches one bignumber measure over `window_minutes` against a
-`threshold`. When it fires or resolves, the organization's owners and admins
-get an Inbox item and an email; `webhook_id` (optional) also posts it to an
-existing webhook. Confirm the threshold with `charts.query` over the same
-window first, and say who it notifies.
+Next: **caveman-sql** when the catalog cannot express the question.

package/dist/skills/caveman-cloud/references/caveman-cloud-evals.md

@@ -2,21 +2,19 @@
 name: caveman-cloud-evals
 description: >
   Write a Caveman Cloud eval as one file, check it, run it, and gate a change
-  on it in CI. Use for eval setup, regression tests, criteria, baselines,
-  comparisons between two runs, or an eval that must run on every pull request.
+  on it in CI. Use for eval setup, regression tests, baselines, comparing two
+  runs, or an eval that must run on every pull request.
 ---
 
 # An eval is one file: write it, check it, run it
 
-Five nouns carry everything. A **Dataset** holds the cases. A **Criterion** is
-one thing the output must do or avoid. A **Run** is the task's outputs on those
-cases, graded. A **Judgment** is one Criterion answered on one case. A
-**Verdict** is what a comparison of two Runs says about the change: passed,
-failed, or need more data. An **Experiment** is the named series of Runs; the
-eval file's `name` is the Experiment.
-
-A saved file is not a result. The work is done when a Run has a Verdict, or an
-honest statement of why it has none.
+A **Dataset** holds the cases. A **Criterion** is one thing the output must do
+or avoid. A **Run** is the task's outputs on those cases, graded. A
+**Judgment** is one Criterion on one case. A **Verdict** is what comparing two
+Runs says: passed, failed, or need more data. An **Experiment** is the named
+series of Runs; the file's `name` is the Experiment. A saved file is not a
+result: the work is done when a Run has a Verdict, or an honest reason it has
+none.
 
 ## 1. Write the file
 
@@ -24,98 +22,50 @@ honest statement of why it has none.
 cvm evals init evals/support.eval.json
 ```
 
-This writes three cases, a task, two criteria, a strict gate and a budget. Replace each part
-from the workload's own contract, tests and entry point:
-
-- **`name`**: the Experiment. Keep it stable: the same name is the same
-  Experiment and the same Dataset every time, so Runs line up.
-- **`dataset`**: `cases` written in the file, each with an `id`, an `input`
-  and, when there is a known right answer, an `expected`; or
-  `{"name": "...", "version": N}` for a Dataset of the project. Take cases from
-  repository fixtures, operator data or authorized traces, and keep their source
-  ids. A case made up to cover an edge is fine when it is marked as such; it is
-  not production coverage. An output seen in a trace is an observation, not a
-  known right answer.
-- **`task`**: `{"command": [...]}` runs the customer's own code here, once per
-  case and trial. The case input arrives as JSON on stdin and the output is
-  read from stdout. This is the default: it exercises the real code.
-  `{"recorded": "column"}` grades outputs already in the Dataset and exercises
-  nothing.
-- **`criteria`**: in order of preference,
-  1. a criterion of the project's library, by name (`cvm criteria list`), so
-     the eval and live monitoring answer the same question;
-  2. a fixed check, `{"type": "contains", ...}`: exact, free, and the same
-     answer every time. `cvm criteria catalog` lists the types, each with its
-     options, what it reads (`inputs`: a check that reads `expected` needs
-     cases that carry one) and what an answer costs (`cost`);
-  3. a judge question, `{"judge": {"question", "pass", "fail"}}`, when no check
-     can decide it. Say what passes and what fails in concrete terms.
-- **`gate`**: present, a full Run is compared with the Experiment's saved
-  baseline. `{"policy": "strict"}` fails when any criterion got worse on any
-  case and decides on a handful of cases. `statistical` reads a pass only on
-  about 30 cases and more; under that it says need more data, which is exit 6
-  and fails a CI job. Use strict until the Dataset is that large. A Run
-  stores the policy on the Experiment, and a gate that names none is read by
-  the stored one (`statistical` until one is stored), so name it rather than
-  rely on a default: an earlier file's `strict` still decides. Leave the gate
-  out and the Run is reported and never compared.
-- **`trials`** when an output varies from one call to the next. The case, not
-  the trial, is what the statistics count.
+This writes three cases, a task, two criteria, a strict gate and a budget.
+Replace each part from the workload's own contract, tests and entry point:
+
+- **`name`**: keep it stable; the same name is the same Experiment and
+  Dataset every time, so Runs line up.
+- **`dataset`**: `cases` in the file (`id`, `input`, and `expected` when a
+  right answer is known), or `{"name": "...", "version": N}` for a project
+  Dataset. Take cases from fixtures, operator data or authorized traces and
+  keep their source ids. A made-up edge case is fine when marked; it is not
+  production coverage. An output seen in a trace is an observation, not a
+  right answer.
+- **`task`**: `{"command": [...]}` runs the customer's code once per case and
+  trial (input as JSON on stdin, output from stdout). This is the default: it
+  exercises the real code. `{"recorded": "column"}` grades outputs already in
+  the Dataset.
+- **`criteria`**, best first: a library criterion by name
+  (`cvm criteria list`), so evals and monitors ask the same question; a fixed
+  check (`{"type": "contains", ...}`, types and options from
+  `cvm criteria catalog`); a judge question
+  (`{"judge": {"question", "pass", "fail"}}`) when no check can decide.
+  Judges, trust and RAG templates: **caveman-cloud-criteria**.
+- **`gate`**: a full Run is compared with the Experiment's saved baseline.
+  `{"policy": "strict"}` fails when any criterion got worse on any case and
+  decides on a handful of cases. `statistical` reads a pass only on about 30
+  cases or more, else need more data (exit 6, which fails CI). Use strict
+  until the Dataset is that large. A Run stores the policy on the
+  Experiment, and a gate that names none is read by the stored one
+  (`statistical` until one is stored): name it. No gate: reported, never
+  compared.
+- **`trials`** when outputs vary; the case, not the trial, is what counts.
 - **`budget_usd`**: the most the Run may spend. Required over one trial and
-  whenever a project key runs the file, which is how CI runs it.
+  whenever a project key runs the file, as in CI.
 
 Keep secrets and captured content out of the file: it is committed.
 
-### Answers built on retrieved context (RAG)
-
-`cvm criteria catalog` returns four ready-made judge questions under
-`templates`, each with its rubric (`statement`, `pass_def`, `fail_def`,
-`na_def`), what the judge must be shown (`inputs`) and one worked example:
-
-| Template | Passes when | The judge must see |
-| --- | --- | --- |
-| `faithfulness` | every claim in the answer is supported by the retrieved context | output, context |
-| `context_relevance` | the retrieved context holds what the question asks for | question, context |
-| `answer_relevance` | the answer addresses the question that was asked | question, output |
-| `cites_sources` | every claim cites a retrieved passage that supports it | output, context |
-
-In a Run a judge is shown the task's output and nothing else. So the task
-prints what it retrieved beside what it answered, and repeats the question:
-
-```json
-{"question": "How long do I have to ask for a refund?", "context": ["Annual plans can be refunded within 30 days of purchase."], "answer": "Within 30 days of purchase."}
-```
-
-and the criterion is a judge question whose text is the template's:
-
-```json
-{"name": "Faithful to the context", "judge": {"question": "<statement>", "pass": "<pass_def>", "fail": "<fail_def>"}}
-```
-
-An output that carries no context cannot be judged on it: fix the task, do
-not reword the question. On live traffic a judge reads the retrieval steps a
-trace recorded, so the same template made a library criterion
-(`cvm criteria create`, kind `question`) needs nothing added.
-
-A template is wording, not trust. A criterion made from one is a judge
-question like any other: its judge is unproven for it until it has qualified,
-and until then its answers are reported and decide nothing.
-
 ## 2. Check it
 
 ```sh
-cvm evals validate evals/support.eval.json
+cvm evals validate evals/support.eval.json      # exit 2 names each error by JSON path
+cvm evals run evals/support.eval.json --dry-run # runs the task, sends nothing
 ```
 
-Exit 2 names every error by its JSON path. `--offline` checks the shape alone
-and needs no sign-in; without it the Dataset and library criterion names are
-resolved in the project. Then run the task with nothing sent:
-
-```sh
-cvm evals run evals/support.eval.json --dry-run
-```
-
-Fix a task that errors before spending on grading.
+`--offline` checks the shape alone without sign-in. Fix a task that errors
+before paying for grading.
 
 ## 3. Run it
 
@@ -123,30 +73,21 @@ Fix a task that errors before spending on grading.
 cvm evals run evals/support.eval.json --set-baseline-on-pass
 ```
 
-The first Run of an Experiment has nothing to be compared with: it exits 0 and
-this flag saves it as the baseline. Every later Run is compared with that
-baseline on the server, and the same comparison is what the console shows.
-
-Read the result before reporting it:
-
-- **Exit 0**: passed, or nothing to gate (no gate, no baseline yet, a partial
-  or dry run). Say which.
-- **Exit 5**: the gate failed. Report the regressed cases and the judge's
-  reason on each.
-- **Exit 6**: no Verdict. More data is needed (the sentence says about how
-  many cases would settle it), the two Runs are not comparable (a case or a
-  criterion changed since the baseline; the sentence says which and prints
-  the `cvm evals set_baseline` command that saves this Run as the new one),
-  or an output could not be graded. None of these is a pass and none is a
-  failure. Save a new baseline only when the change was meant.
-- **Exit 2** an invalid file. **Exit 1** the Run crashed.
+The first Run has nothing to compare with: it exits 0 and becomes the
+baseline. Later Runs are compared with it on the server, as the console shows.
 
-`--first N` or `--sample N --seed S` grade some of the cases for a quick look.
-Such a Run is never compared and never becomes a baseline.
+- **0**: passed, or nothing to gate (no gate, no baseline, partial or dry
+  run). Say which.
+- **5**: the gate failed. Report the regressed cases and the judge's reason.
+- **6**: no Verdict: more data needed (the sentence says how much), the Runs
+  are not comparable (a case or criterion changed; the sentence prints the
+  `cvm evals set_baseline` command), or an output could not be graded. Not a
+  pass, not a failure. Save a new baseline only when the change was meant.
+- **2** an invalid file, **1** the Run crashed.
 
-A failed or unsure Judgment carries the judge's reason. Quote it; do not
-write one for it. A judge's answer decides only when that judge is trusted for
-the criterion; an unproven one is reported as unproven.
+`--first N` or `--sample N --seed S` grade a few cases for a quick look; such
+a Run is never compared or saved as a baseline. Quote a judge's reason, never
+write one; an unproven judge's answer decides nothing.
 
 ## 4. Gate changes in CI
 
@@ -154,49 +95,30 @@ the criterion; an unproven one is reported as unproven.
 cvm evals ci evals/*.eval.json --junit-out caveman-evals.xml
 ```
 
-The same Run, with the commit, branch and pull request on the result and one
-JUnit test case per case and criterion. It needs no GitHub. Set `CAVE_TOKEN`
-to a project key made for this (in the console, New key with "Runs evals from
-CI" on and a spend limit per day), plus `CAVE_PROJECT_ID`. That key reaches
-only its own project's evals, reads no captured content, and stops at its
-daily limit. `--advisory` reports the Verdict without failing the job. On
-GitHub Actions the Caveman action's `files:` input runs this command.
-
-What follows from that key reading no captured content:
-
-- The file names `budget_usd`. Each Run's budget is held against the key's
-  limit for the day, so keep it near what the Run costs.
-- The file writes its `cases` in the file, or uses a task Caveman runs. A
-  command task on a named Dataset needs the rows, which the key cannot read.
-- The key's read of a Run holds no judge reason and no error text. The
-  result names the failing cases and criteria and says the reasons were
-  withheld: report that, and point to the Run in the console for them.
-
-Do not create the key, raise its limit or change what gates a merge unless the
-task asks for exactly that.
-
-## 5. Criteria that outlive the file
-
-A criterion worth keeping belongs in the library, where one version serves
-Runs and Monitors alike. Read what exists with `cvm criteria list` and
-`cvm criteria get`. Rehearse a new or edited one on recent traffic, a Dataset
-or one typed example with `cvm criteria test` before relying on it, and read
-what it received beside what it answered. `cvm criteria create` and
-`cvm criteria edit` write a version; `cvm criteria trust` says whether its
-judge is trusted. Turning a criterion on for live traffic spends on the
-customer's keys: stop and ask.
-
-Through the Cloud MCP the same operations are reached by id (`criteria.list`,
-`criteria.catalog`, `datasets.create`, `evals.create`, `evals.run`,
-`evals.compare`): describe one with
-`caveman_describe`, read with `caveman_read`, write with `caveman_write`.
-
-## 6. Report
-
-Give the file path, the Experiment and Run ids, the Verdict with the server's
-sentence and the baseline it was read against, counts of passed, failed and
-errored Judgments per criterion, the failing case ids with the judge's reason
-(or that it was withheld from a project key's read), cost when it is known,
-and what remains. Keep these apart: a file that
-validates, a dry run, a graded Run, a Run compared with a baseline, a gate in
-CI. Unknown cost stays unknown.
+The same Run, with commit, branch and pull request, and one JUnit case per
+case and criterion. No GitHub needed. `CAVE_TOKEN` is a project key made for
+this (console: New key, "Runs evals from CI", a daily spend limit) and
+`CAVE_PROJECT_ID` its project. `--advisory` reports without failing. On GitHub
+Actions the Caveman action's `files:` input runs this command. That key reads
+no captured content, so:
+
+- the file names `budget_usd`, held against the key's daily limit;
+- cases are written in the file, or the task is one Caveman runs (a command
+  task on a named Dataset needs rows the key cannot read);
+- its Run holds no judge reasons or error text: report the failing cases and
+  point to the Run in the console.
+
+Do not create the key, raise its limit or change what gates a merge unless
+asked for exactly that.
+
+## 5. Report
+
+The file path, Experiment and Run ids, the Verdict with the server's sentence
+and its baseline, passed, failed and errored Judgments per criterion, failing
+case ids with the judge's reason (or that it was withheld), known cost, and
+what remains. Keep apart: a valid file, a dry run, a graded Run, a compared
+Run, a CI gate. Unknown cost stays unknown.
+
+MCP: the same ids (`evals.create`, `evals.run`, `evals.compare`,
+`datasets.create`) through `caveman_describe`, `caveman_read`, `caveman_write`.
+Next: **caveman-cloud-compare** to read two Runs side by side.

package/dist/skills/caveman-cloud/references/caveman-cloud-project.md

@@ -61,7 +61,16 @@ state transitions; use **caveman-cloud-compare** for compatible paired runs.
 
 ## 4. Draft monitors for the same failures
 
-For each requested monitor, choose the workflow/filter, grader, threshold,
+```sh
+cvm monitors list | jq '.data.data[] | {id, name, status, sample_rate}'
+cvm quality_setup proposals              # criteria, judge and budget drafted per workload
+cvm monitors estimate --file draft.json  # last 7 days: matching units, judge cost
+cvm monitors results MONITOR_ID --window 7d
+```
+
+A new check is `cvm criteria propose` (proposed until a person turns it on).
+Approving a workload's criteria and budget, and setting a monitor `active`,
+are a person's. For each requested monitor, choose the workflow/filter, grader, threshold,
 required metadata or payload, sampling rate, and collection destination. Explain
 why the check detects a real failure and estimate judge cost from known traffic
 volume; label missing volume or prices unknown. Use the discovered schema's
@@ -94,4 +103,5 @@ Stop before promotion, monitor activation, live policy changes, or deployment.
 Do not create a first experiment, invite teammates, or change budgets merely to
 finish setup. Strict rollout evidence and independent holdout authority remain
 separate from ordinary self-authored evals. Continue work already authorized;
-ask only for a missing decision that blocks the next dependent step.
+ask only for a missing decision that blocks the next dependent step. Criteria
+and judges: **caveman-cloud-criteria**.

package/dist/skills/caveman-cloud/references/caveman-cloud-scenarios.md

@@ -25,17 +25,9 @@ Authoring/export is not execution. Report the backend's passed, failed, or incom
 
 ## HTTP simulation suites
 
-For conversation testing against a configured sandbox endpoint, use the separate
-`scenario-suites` and `scenario-runs` families. Discover their exact schemas;
-do not send an agent-task manifest to the HTTP simulation API.
-
-```sh
-cvm scenario-connections list
-cvm tools describe scenario-suites.create
-cvm scenario-suites create --file suite.json
-cvm scenario-suites run --file run.json --wait
-cvm scenario-runs wait RUN_UUID
-```
+HTTP simulation suites (conversation tests against a sandbox endpoint) have no
+`cvm` operation yet: `cvm tools list` won't show them. Tell the user they run
+from the console's Scenarios page, and do not send an agent-task manifest there.
 
 Use an existing sandbox connection with reset support. Connection creation,
 egress credentials and rollout-gate changes are human-only. Suites freeze cases,

package/dist/skills/caveman-cloud/references/caveman-cloud-setup-inventory.md

@@ -0,0 +1,51 @@
+---
+name: caveman-cloud-setup-inventory
+description: >
+  What a Caveman Cloud setup inventory holds: the item kinds, how names, paths
+  and eval cases must look to verify, and which files never to cite. Read from
+  caveman-cloud-setup step 2.
+---
+
+# The setup inventory
+
+Read **caveman-cloud-setup** first: its rules bind every item here. Then build
+the items for `cvm setup assert` (`cvm tools describe setup.assert` has the
+exact schema).
+
+Read the default branch's tracked files. Record one item per finding:
+
+| kind | what | name | extra fields |
+|---|---|---|---|
+| workload | a place the app calls a model for one business job | slug: `support-agent` | path of its entrypoint |
+| prompt | a system or task prompt file or string | short token | `workload` |
+| tool | a tool or function schema the model can call | the tool's name exactly | `workload` |
+| model | a model id the code sends | the id exactly, e.g. `claude-sonnet-4-6` | `workload` |
+| eval_case | one case in a test fixture, golden file or documented example | short token | `workload`, `input`, `expected` |
+| gateway_config | a LiteLLM proxy config (`model_list`) or a Kong decK file (`_format_version`) | short token | `vendor`: litellm or kong |
+| telemetry | an OpenTelemetry exporter, Langfuse or Helicone in the code | short token | `vendor`: otel, langfuse or helicone |
+| ci | a CI workflow that runs the app's tests | short token | |
+
+- `path` is repository-relative; add `line` when one line carries the item.
+- Names are single tokens of at least 3 characters without spaces. Workload
+  names are lowercase slugs. A name verifies only as a whole identifier.
+- Model and tool names shorter than 6 characters (`gpt-5`, `o3`, `fetch`)
+  are never checked (`name_too_short`): leave them out; the workload may then
+  stay unverified. At most 20 model and tool names per file.
+- Copy each eval case's `input` and `expected` (each at least 8 characters)
+  exactly as the fixture or documented example holds them: whole values of
+  one record (one JSON object, or one block of lines where each value sits on
+  one line, quoted or alone on its line; a value spread over several lines
+  does not match). Never invent a case,
+  never write an expected answer yourself, never use a model's output as one.
+  At most 100 cases; prefer the ones that cover distinct behaviors.
+- Skip vendored code, generated files and other people's examples.
+- Never cite a file that holds secrets (keys, certificates, service-account
+  files, token stores, Terraform state or variables, `.aws`, `.ssh`, `.kube`,
+  `.docker`): the server refuses the whole assertion. Any path segment
+  starting with `secret`, `credentials` or `.env` is refused, so
+  `credentials_check.py` and `.envoy/` are too, as are env files by name
+  (`env`, `env.local`, `env.production` and other stages, `env.json`,
+  `env.yaml`, `env.sh`, `env.toml`, `env.ini`); code such as `env.ts` or
+  `env.py` is fine. Cite another file.
+
+Next: assert all items in one call, **caveman-cloud-setup** step 3.

package/dist/skills/caveman-cloud/references/caveman-cloud-setup-wiring.md

@@ -0,0 +1,45 @@
+---
+name: caveman-cloud-setup-wiring
+description: >
+  How to prepare each action a Caveman Cloud setup detection names: the held
+  wiring change, each workload's slug in its traffic, and history imports the
+  person uploads. Read from caveman-cloud-setup step 4.
+---
+
+# The action per detection
+
+Read **caveman-cloud-setup** first: its rules bind every action here.
+
+The answer's `detections` name one action each:
+
+- `keep_litellm`, `keep_kong`, `add_otel_exporter`, or no gateway at all
+  (`route_through_caveman`): prepare the wiring following **caveman-setup**
+  and **caveman-setup-recipes**, plus caveman-cloud-setup's rules 3 and 4
+  (record mode, one revert variable). Create the branch `caveman/setup`
+  locally, commit the change there, and send the same edits with
+  `cvm setup hold`: `purpose`, `branch`, `revert_variable` `CAVEMAN_SETUP` and
+  `files` (a new file as `create`; an edit as exact
+  `old` and `new` text with `before_sha256`, the SHA-256 of the file as the
+  default branch holds it). The server refuses CI files, secrets, lockfiles,
+  manifests, tests and agent instruction or config files; leave those to the
+  person. Once published, the draft is a branch of their repository, so their
+  CI runs on it; say so in the report.
+- **Name each workload in its traffic.** Caveman files a finding under the
+  agent its traffic names, and offers to fix it only for a workload the server
+  registered from your inventory. So the wiring sends each workload's slug,
+  exactly as you asserted it: direct wiring uses `GATEWAY/w/<workload>` as the
+  base URL (caveman-setup's app slug is the workload slug here), or the
+  header `x-cave-agent: <workload>` on each call where workloads share one
+  client. A LiteLLM or Kong path sends `x-cave-agent: <workload>` on its
+  export or forwarded requests only when one workload is behind it; when
+  several are, leave it out and report that path's traffic as not yet tied
+  to a workload.
+- `import_langfuse_history`, `import_helicone_history`: tell the person to
+  export their history and upload it with their gateway key to the gateway's
+  `POST /v1/imports/history?format=langfuse` (or `helicone`). Imported
+  history counts toward the proving budget as a catalog estimate; it is never
+  measured spend, so it does not count as saved requests for Caveman's first
+  test, which needs live traffic. LiteLLM history is an OpenTelemetry export
+  for the gateway's `/v1/traces`. Uploading is the person's call.
+
+Next: report, **caveman-cloud-setup** step 5.