humanish 0.141.0 → 0.142.0

package/docs/contracts/study-analysis.md

@@ -5,7 +5,8 @@ It is separate from the participant's account, recorded outcome, and the run's
 deterministic review verdict. Opening an Observer never starts a provider request.
 Supported live runs request analysis on completion by default. A study that declares no analyst
 gets the Codex account analyst when its participant is a Codex `local-agent`, and the OpenAI
-analyst with a separate $10 cap on its expected cost otherwise. Set `review.analysis: false` to
+analyst with a separate $10 cap on its expected cost otherwise. A study can also select the
+[Gemini API analyst](#gemini-api-analysis). Set `review.analysis: false` to
 disable that request; see [automatic analysis](../product/automatic-analysis.md).
 
 ## Invocation
@@ -117,6 +118,49 @@ the current merge instructions, billed $1.92, most of its input served from the
 provider's prompt cache, and each of its 466 citations resolved. Two runs do not
 calibrate the merge request's estimate.
 
+## Gemini API analysis
+
+`review.analysis.provider: gemini`, or `analyze --provider gemini`, sends the same request to
+Google's Gemini API:
+
+```bash
+humanish keys set gemini
+humanish analyze --run latest --provider gemini --max-cost 2 --dry-run --json
+humanish analyze --run latest --provider gemini --model gemini-3.8-flash --max-cost 2 --json
+```
+
+The request goes to `generativelanguage.googleapis.com/v1beta/models/<model>:generateContent`
+with the key in the `x-goog-api-key` header. It carries the same instructions, packet and
+captures, with each capture at `MEDIA_RESOLUTION_HIGH`, thinking level `HIGH`, one candidate,
+the standard service tier, no tools and `store: false`. The key is `GEMINI_API_KEY` when set,
+else `GOOGLE_API_KEY`. Google's client libraries prefer `GOOGLE_API_KEY`; humanish does not, so a
+`GOOGLE_API_KEY` exported for another Google API never replaces the stored Gemini key. Key
+discovery fills neither name while the other is already in the environment. Without either, the attempt ends with
+`ANALYSIS_API_KEY_MISSING` and nothing is sent; the OpenAI key is never used.
+
+The supported model is `gemini-3.8-flash`, the one with a completed live analysis. The other
+Gemini models whose pages list image input and structured output join once a live analysis on
+each completes. `--max-cost` is required, and admission, the cost cap, `--max-output-tokens`
+(at most 32,768) and the partial result for a bill above the worst case work as on OpenAI.
+Admission prices each capture at 1,120 tokens, the media-resolution guide's figure for a
+high-resolution image, and expects twice the output it expects from OpenAI: one
+`gemini-3.8-flash` analysis of one participant wrote 24,246 output tokens. Usage maps
+`promptTokenCount` to input, `candidatesTokenCount` plus `thoughtsTokenCount` to output, and
+`cachedContentTokenCount` to cached input; a usage record whose `totalTokenCount` disagrees
+with those parts is kept as unknown. Rates are Google's paid standard tier. `gemini-3.8-flash`
+has a published price change on 2027-01-01, and each request is priced at the rates of the day
+it is sent. A free-tier key bills nothing, and Google's terms
+let it use free-tier content to improve its products.
+
+Gemini refuses the analysis schemas while they carry `maxItems`, so the request leaves those
+array limits out of the schema and states them, by field path, at the end of the system
+instruction. The response is still checked against the full schema. A `STOP` candidate
+whose only non-thought part is the JSON answer completes. `MAX_TOKENS` and `CONTINUATION` end
+as `output_incomplete`. A blocked prompt and the `SAFETY`, `RECITATION`, `LANGUAGE`,
+`BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `ESCALATION` and image-safety finish reasons end as
+`refusal`. Any other finish reason or answer shape ends as `invalid_response`. An HTTP error
+keeps only its status code, which the attempt's warnings name.
+
 ## Codex account analysis
 
 A study whose participant is a Codex `local-agent` uses this analyst unless it declares another,
@@ -492,11 +536,15 @@ The states without findings:
   `analyze --max-cost 10`, which runs an analysis anyway. For a skip without `OPENAI_API_KEY`
   on a machine where Codex is signed in with a ChatGPT account (read when the view is built),
   `next` is `analyze --provider codex` and the message names `review.analysis.provider: codex`
-  in the run's study file; otherwise the message says to set the key. For an analysis refused for its
+  in the run's study file; otherwise the message says to set the key. A study analyzed on Gemini
+  is skipped with `AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING`; its message names `keys set gemini`,
+  and `next` is `analyze --provider gemini --model <model> --max-cost 10`.
+  For an analysis refused for its
   cost, the message gives the expected cost, the worst case and the cap, and `next` sets
   `--max-cost` to the worst case rounded up.
 - `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`
-  reruns it with the same analyst, `--provider codex` for the Codex account analyst.
+  reruns it with the same analyst: `--provider codex` for the Codex account analyst, and
+  `--provider gemini --model <model>` for a Gemini one.
 - `none`: no analysis ran for this live run and nothing records why, for example a run that
   started from a library call, or one whose study file has moved or changed id.
 - `dry_run`: a dry run has no participant evidence to analyze. `next` is `run` with the run's own

package/docs/product/automatic-analysis.md

@@ -50,7 +50,8 @@ allowance before deliberately choosing a larger budget. Explicit
 `maxOutputTokens` and `--max-output-tokens` limits are honored exactly. The output allowance
 includes reasoning as well as the report; exhausting it does not produce a usable
 report and never starts an automatic retry. Analysis
-sends selected retained text and captures to OpenAI using `OPENAI_API_KEY`.
+sends selected retained text and captures to OpenAI using `OPENAI_API_KEY`, or to Google with
+`provider: gemini`.
 Analysis runs in the humanish runner using its credentials. This setting adds no
 credential channel to the target application; each participant's route keeps
 its existing authentication boundary. Review the separate analysis budget before running a manifest live; an actor's
@@ -78,6 +79,27 @@ remain untested until a request. An omitted provider means this analyst for a Co
 `local-agent` participant on any target, and OpenAI for every other participant. This setting
 does not enable managed local desktops.
 
+To use Google's Gemini API for the separate analyst:
+
+```yaml
+review:
+  analysis:
+    provider: gemini
+    model: gemini-3.8-flash
+    maxCostUsd: 2
+```
+
+Gemini analysis sends the same evidence packet and captures to Google, at high thinking level,
+with each capture at high media resolution. It reads `GEMINI_API_KEY`, which `humanish keys set
+gemini` stores, and `GOOGLE_API_KEY` only when `GEMINI_API_KEY` is unset. Key discovery treats
+the two names as one key: a project's `.humanish/local/provider.env` or the user store never adds
+one while the other is already in the environment. A missing Gemini key skips the analysis
+(`AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING`); the OpenAI key is never used in its place. Admission,
+`maxCostUsd`, `maxOutputTokens` and priced usage work as they do on OpenAI, at the paid-tier
+rates in `src/run/pricing.ts`; requests made with a free-tier key bill nothing, and Google's
+terms let it use free-tier content to improve its products. The supported model is
+`gemini-3.8-flash`, the one with a completed live analysis.
+
 The same configuration works through `humanish run <study>`,
 `watch <study>`, and TUI live starts. Direct library calls to the five recording
 producers honor it too. Supported routes are computer-use, scripted-browser,
@@ -147,7 +169,8 @@ run's own result is ok, the first line of the human output reads
 command: with Codex signed in with a ChatGPT account it is `humanish analyze --run <id>
 --provider codex`, and the message names `review.analysis.provider: codex` as the setting that
 makes that analyst the study's; otherwise it says to set the key and names `humanish analyze
---run <id> --max-cost 10`. So does a
+--run <id> --max-cost 10`. A study analyzed on Gemini names `humanish keys set gemini` and
+`humanish analyze --run <id> --provider gemini --model <model> --max-cost 10`. So does a
 default analysis whose expected cost, plus the margin, is over the default $10 cap:
 it is skipped with `AUTOMATIC_ANALYSIS_ADMISSION_REFUSED` and the run exits 0. For
 any analysis refused for its cost, the job records the expected cost, the worst
@@ -197,6 +220,7 @@ JSON also has `findings`:
 | `AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE`       | `skipped`                 | This invocation published no run to analyze, or the run id is invalid |
 | `AUTOMATIC_ANALYSIS_SOURCE_CHANGED`           | `failed`                  | The run directory changed after the run published its bundle          |
 | `AUTOMATIC_ANALYSIS_KEY_MISSING`              | `skipped`                 | No OpenAI API key                                                     |
+| `AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING`       | `skipped`                 | No Gemini API key for a study analyzed on Gemini                      |
 | `AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE`  | `skipped`                 | A default analysis found no participant evidence                      |
 | `AUTOMATIC_ANALYSIS_ACTOR_CANCELLED`          | `skipped`                 | The harness cancelled the participants, or a signal stopped the run   |
 | `AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED`      | `skipped`                 | A local VM study could not confirm its cleanup; the command exits 2   |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.141.0",
+  "version": "0.142.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -96,7 +96,7 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=411",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=410",
     "knip": "knip",
     "prose:check": "node scripts/check-code-prose.mjs",
     "vocabulary:check": "tsx scripts/check-retired-words.ts",

package/skills/humanish/SKILL.md

@@ -108,6 +108,16 @@ not local inference or the participant's existing conversation. See
 [the analysis contract](../../docs/contracts/study-analysis.md) for the current
 CLI/model qualification and setup limits.
 
+To analyze on Gemini, the user stores a key with `npx humanish keys set gemini`
+(`GEMINI_API_KEY`; `GOOGLE_API_KEY` is read only when `GEMINI_API_KEY` is
+unset), then sets `review.analysis: {provider: gemini, maxCostUsd: <n>}` or
+passes `analyze --provider gemini --max-cost <n>`. The supported model is
+`gemini-3.8-flash`. This sends the evidence packet and
+captures to Google. Admission, the cost cap and priced usage work as on OpenAI,
+and a missing Gemini key never falls back to OpenAI. On a free-tier key, Google
+may use the content to improve its products; tell the user before a study with
+private evidence runs on one.
+
 When post-run analysis is refused for its cost, the run output and `humanish
 review` give its expected cost, its worst case and the command that runs it,
 `humanish analyze --run <id> --max-cost <n>`. Show the user those costs and run