@withgauge/cli 0.10.2 → 0.11.0

package/README.md

@@ -27,6 +27,12 @@ gauge stats rankings -o json      # brand rankings (share of voice) as JSON
 gauge query -d ecosystem -m installs,install_rate -o json   # a flexible report
 ```
 
+`gauge instructions` prints the CLI's own agent instructions to stdout: one
+skill file covering every command group. `gauge instructions <topic>` reprints
+one group alone. `gauge --help` points agents at it, or write the file into the
+repo with `gauge instructions --install`. The text ships inside the CLI, so it
+never drifts from the commands it describes.
+
 Run `gauge --help` (or `gauge <command> --help`) for the full command set:
 evals, preference, models, personas, skills, mcp, repos, runs, optimizations,
 experiments,
@@ -93,6 +99,52 @@ immediate launches. They use the stored configuration and ask before spending
 `gauge preference run <id> --scenario <scenarioId>` (repeatable) runs a subset;
 omit it and every scenario runs. Neither launch touches the cadence clock.
 
+## Optimizations: Gauge measures, you author
+
+`gauge optimizations` improves one surface you own — a docs page or a skill —
+against an eval or a preference prompt. Gauge measures a baseline, runs the
+trials you author, judges them, and tells you which change won. It never writes
+the change itself, and it never touches your repository. You edit on disk and
+send the text; Gauge serves it to the sandboxed agent in place of the live page
+or skill version.
+
+A scripted or agent-driven loop:
+
+```sh
+gauge optimizations diagnose --eval es_1            # where the sessions fail
+gauge optimizations estimate --eval es_1 --target claude-code:claude-opus-4-8
+gauge optimizations start --eval es_1 --target claude-code:claude-opus-4-8 --yes
+gauge optimizations watch cl_1                      # exit 4 = your turn
+
+gauge optimizations page cl_1 --url https://docs.acme.dev/start > start.md
+$EDITOR start.md
+gauge optimizations trials add cl_1 \
+  --title "Lead with the env var" --page https://docs.acme.dev/start \
+  --body-file start.md --launch --idempotency-key start-env-var --yes
+
+gauge optimizations watch cl_1
+gauge optimizations trial cl_1 R1                   # score, verdict, sessions
+gauge optimizations change cl_1 R1 --body           # the winning text, to paste
+gauge optimizations adopt cl_1 R1 --yes             # the new moving baseline
+gauge optimizations complete cl_1 --yes
+```
+
+`page` and `skill-files` print the exact frozen content a trial starts from.
+Edit a skill with `--edit-skill <versionId> --skill-dir <path>`: the directory
+holds the complete bundle, `SKILL.md` included. `trials template --kind <kind>`
+prints a skeleton for the `--file` form.
+
+Every detail carries `nextAction` — `START`, `WAIT`, `AUTHOR_TRIAL`,
+`LAUNCH_ROUND`, `ADOPT`, `RESUME`, or `NONE`. Read it (`get -o json`) instead of
+inferring whose turn it is from round and trial statuses. `watch` exits `4` when
+the answer is you.
+
+`--idempotency-key` makes `trials add` safe to retry: the same key returns the
+trial the first call created, and never buys a second set of sessions.
+
+Adoption moves Gauge's measured baseline. It does not open a pull request, so
+take the winning text from `change --body` and apply it to your own source.
+
 ## Models, reports, and scripting
 
 Use `gauge models list` before pinning models. It reads the organization's live
@@ -107,7 +159,7 @@ and effective capabilities. Open harnesses use `--agent pi:<model>` and
 
 Every read supports `-o json` for scripting. `GAUGE_API_TOKEN` overrides
 stored credentials (useful in CI). Exit codes: `0` ok · `1` error ·
-`2` usage · `3` billing-blocked.
+`2` usage · `3` billing-blocked · `4` needs your input (`optimizations watch`).
 
 ## Support