humanish 0.107.0 → 0.109.0

package/README.md

@@ -1,60 +1,32 @@
 # humanish
 
 Synthetic user research for apps, CLIs, and agent-facing product flows.
-Open-source and public-safe.
-
-humanish runs studies. Realistic synthetic participants, each with its own
-goals, patience, and skill, actually use your product on isolated desktops while
-you watch. A study leaves verifiable evidence: screenshots, action traces,
-per-task completion funnels, participant outcomes with the denominator
-attached, and estimated cost lines. A fail-closed share-safety gate decides what
-goes into feedback drafts, export bundles and a `serve --safe` library, and the
-end of the pipeline is a public-safe feedback draft you can turn into a real
-issue. Committed lab source lives under `humanish/`; run evidence lands under
-gitignored `.humanish/`.
 
 [![The Observer grid of a saved eight-participant study: eight desktops in one multiplayer lobby, each tile a participant's live screen](https://humanish.dev/runs/lobby-0927/poster.jpg)](https://humanish.dev/demo)
 
-**[Watch a saved run](https://humanish.dev/demo).** Eight synthetic participants
-joined one lobby of a multiplayer game on its live deployment, each on its own
-hosted desktop, and played five rounds. Six reached the final standings, two were
-blocked, and `humanish analyze` turned the 13-minute recording into seven
-findings, each linked to the capture behind it. The page replays the real
-Observer; nothing runs from it.
-
-**Numbers so far, every one with its run ids.** Recall on five planted defects
-in a small task app: 15 of 15 across three live runs
-([benchmark](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-2026-09-04-0.76.0.md)). Precision on apps the
-maintainer did not write: TodoMVC 5 of 6 findings confirmed against the source,
-drawDB 11 of 12, none invented
-([TodoMVC](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-TODOMVC-2026-09-01.md), [drawDB](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-DRAWDB-2026-09-01.md)).
-Cold install to a live study: 9 of 9 fresh directories reached the goal in 108 to 200 seconds;
-the five on the API route cost $0.16 to $0.35 each, and the four on Codex or Claude Code are
-unpriced ([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/cold-install-try-live-2026-09-01.md)).
-Same mission, different personas: keyboard-first participants reported drawDB's
-database modal 5 of 5 times and TodoMVC's mouse-only rename 6 of 6; mouse newcomers
-reported them 0 of 5 and 0 of 6 ([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/persona-axis-phone-2026-09-03.md)).
-Planted defects are more legible than real ones and the largest cell is six runs;
-read these as what the machinery found, not as rates for your users.
-
-![humanish Observer grid of a live four-persona drawDB study: four completed participants, each showing its final full-desktop screenshot and outcome](https://unpkg.com/humanish@0.16.0/docs/assets/humanish-drawdb-hero.png)
-
-An earlier study, kept here because the image ships in the npm package: four
-personas on [drawDB](https://github.com/drawdb-io/drawdb), a public open-source
-database diagram editor, driven against a commit-pinned local checkout. Every participant
-ran a real computer-use session on a hosted desktop; the captions are each persona's
-own final report. drawDB is the application studied; it is not a humanish adopter or endorser.
+**[Watch a saved run](https://humanish.dev/demo).** Eight synthetic participants joined one
+lobby of a multiplayer game on its live deployment, each on its own hosted desktop. The page
+replays the real Observer; nothing runs from it.
 
-[Quickstart](https://humanish.dev/docs) · [Study your app](https://humanish.dev/docs/your-app) · [What a study costs](https://humanish.dev/docs/what-a-study-costs) · [Trust boundaries](https://humanish.dev/docs/trust-boundaries) · [CLI reference](https://humanish.dev/docs/cli) · [Limits and evidence](https://humanish.dev/failure-modes)
-
-## Install
+## Try it without keys
 
-Use **Node.js 22.19 or newer**, in a project directory:
+In a project directory, with Node.js 22.19 or newer:
 
 ```bash
 npm install --save-dev humanish
+npx humanish init --yes
+npx humanish run first-run
+npx humanish observe --run latest --open
 ```
 
+This writes a preview study with no model calls and no spend, so you can read the evidence format
+before you add keys. To run participants against your own app, follow the
+[own-app guide](https://humanish.dev/docs/your-app).
+
+[Quickstart](https://humanish.dev/docs) · [Study your app](https://humanish.dev/docs/your-app) · [What a study costs](https://humanish.dev/docs/what-a-study-costs) · [Trust boundaries](https://humanish.dev/docs/trust-boundaries) · [CLI reference](https://humanish.dev/docs/cli) · [Limits and evidence](https://humanish.dev/failure-modes)
+
+## Run a live study
+
 `@e2b/desktop` is the optional peer for live hosted desktops. Install it alongside
 humanish when choosing that route (`npm install --save-dev @e2b/desktop`) so the
 CLI can resolve it; a one-shot `npx humanish@latest` can miss the peer. The keyless
@@ -62,44 +34,46 @@ preview and local-browser setup need only `humanish`.
 
 Choose how the participant runs:
 
-| Setup                                                             | Participant authentication            | Desktop                                              | Automatic findings                               |
-| ----------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
-| `first-run` preview                                               | None; synthetic evidence only         | None                                                 | No model analysis                                |
-| [Local browser study](docs/architecture/local-browser-runtime.md) | Codex ChatGPT login; remote inference | Linux x64 + Docker/KVM or M3+ Mac + Lima; no E2B key | Separate Codex account analyst by default        |
-| `openai-computer-use`                                             | `OPENAI_API_KEY`                      | `E2B_API_KEY` + desktop SDK                          | Separate OpenAI request                          |
-| [`local-agent`](https://humanish.dev/docs/local-agents)           | Codex or Claude Code's own login      | `E2B_API_KEY` + desktop SDK                          | Still needs `OPENAI_API_KEY`; skipped without it |
+| Setup                                                          | Participant authentication            | Desktop                                              | Automatic findings                               |
+| -------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
+| `first-run` preview                                            | None; synthetic evidence only         | None                                                 | No model analysis                                |
+| [Local browser study](https://humanish.dev/docs/local-browser) | Codex ChatGPT login; remote inference | Linux x64 + Docker/KVM or M3+ Mac + Lima; no E2B key | Separate Codex account analyst by default        |
+| `openai-computer-use`                                          | `OPENAI_API_KEY`                      | `E2B_API_KEY` + desktop SDK                          | Separate OpenAI request                          |
+| [`local-agent`](https://humanish.dev/docs/local-agents)        | Codex or Claude Code's own login      | `E2B_API_KEY` + desktop SDK                          | Still needs `OPENAI_API_KEY`; skipped without it |
 
 A Codex ChatGPT login can power a `local-agent` participant. It does not
 authenticate humanish's OpenAI API requests. Choose the actor explicitly in
-your lab; installing Codex does not change an `openai-computer-use` lab.
+your study; installing Codex does not change an `openai-computer-use` study.
+
+### Study your app in a local browser
 
 For local browsers, install only `humanish` and follow the
-[local study setup](docs/architecture/local-browser-runtime.md). The first live
+[local study setup](https://humanish.dev/docs/local-browser). The first live
 run downloads a verified runtime image; `npx humanish runtime setup` prepares it
 ahead of time. Supported Macs use Lima instead of Docker Desktop.
-[Optional camera and spoken conversation](docs/architecture/participant-media.md)
-use a separate media runtime. [Optional desktop video/audio](docs/architecture/desktop-recording.md)
-adds continuous Observer playback; screenshots remain the default. [Local captured inboxes](docs/architecture/comms-inbox.md#local-browser-studies) support email verification without mailbox-provider credentials.
+[Optional camera and spoken conversation](https://humanish.dev/docs/participant-media)
+use a separate media runtime. [Optional desktop video/audio](https://humanish.dev/docs/desktop-recording)
+adds continuous Observer playback; screenshots remain the default. [Local captured inboxes](https://humanish.dev/docs/comms-inbox#local-browser-studies) support email verification without mailbox-provider credentials.
 
-For a new local lab, initialize with your app URL and task:
+For a new local study, initialize with your app URL and task:
 
 ```bash
 npx humanish init --yes \
   --local-browser http://127.0.0.1:3000 \
   --local-mission "Complete the primary flow and explain anything confusing"
-npx humanish doctor --lab local-browser
+npx humanish doctor --study local-browser
 npx humanish run local-browser
 npx humanish verify
 ```
 
 Start your app before running the study. `verify` checks the saved run bundle, and its
 share-safety line says whether the evidence can be shared as-is. If you already initialized this
-project, edit `humanish/labs/local-browser.yaml` to change its URL or mission; `init`
+project, edit `humanish/studies/local-browser.yaml` to change its URL or mission; `init`
 preserves existing files and warns when supplied settings cannot be applied.
 
 `init` also adds `humanish:*` scripts to `package.json`. `npm run humanish:doctor` and
 `npm run humanish:verify` run those commands, and `humanish:watch` runs a study and keeps the
-Observer attached. `humanish:run` is `humanish run --dry-run`: a contract-proof dry run with no
+Observer attached. `humanish:run` is `humanish run --dry-run`: a dry run with no
 browser or model, not the live study above.
 
 `doctor` only inspects setup. It does not install or start the runtime, open a
@@ -107,63 +81,75 @@ browser, or use Codex account quota. The local study needs a supported Codex CLI
 version and ChatGPT login. Linux x64 also needs local rootful Docker, KVM and
 TUN; M3-or-newer Apple Silicon Macs need native ARM64 Node and Lima 2.2+.
 
-**Run a live study with the API route.** Set the desktop and model keys with hidden prompts, then
-send one synthetic participant into the included drawDB study:
+### Study drawDB through the API route
+
+Set the desktop and model keys with hidden prompts, then send one synthetic participant into the
+included drawDB study:
 
 ```bash
 npx humanish keys set e2b
 npx humanish keys set openai
 npx humanish init --yes
-npx humanish doctor --lab try-live
-npx humanish lab preflight try-live
+npx humanish doctor --study try-live
+npx humanish study check try-live
 npx humanish run try-live
 npx humanish observe --run latest --open
 ```
 
 Existing `E2B_API_KEY` and `OPENAI_API_KEY` environment variables also work.
-`doctor --lab` checks the selected route's local setup without launching a
+`doctor --study` checks the selected route's local setup without launching a
 desktop or making a model request. It reports key presence, not remote key
-validity, model access, or quota. `lab preflight` checks manifest metadata by default.
+validity, model access, or quota. `study check` checks manifest metadata by default.
 `try-live` clones and studies drawDB, not your project. Set the keys before `init`:
 `init` writes `try-live` for the participant this machine can run, and it never
-overwrites an existing lab file. With an OpenAI key, from the environment or the
+overwrites an existing study file. With an OpenAI key, from the environment or the
 `keys set` store, the participant is `openai-computer-use` and its **$2 cap covers
 estimated participant model spend**. With no OpenAI key and a signed-in Codex or
 Claude Code, it is `local-agent`, bounded by a ten-minute session limit with no
-dollar cap. Post-run analysis defaults to a separate
-**$3 admission estimate limit**; set `review.analysis: false` to disable it.
+dollar cap. Automatic analysis after the run is a separate request;
+[Read the results](#read-the-results) gives its limit and how to turn it off.
 Hosted desktop time is additional. Participant caps are checked
 between turns and are not provider billing ceilings. Allow a few minutes for
 the app to build and the participant to work. See [budgets and privacy](https://humanish.dev/docs/budgets-and-privacy).
 
-**Preview without keys.** To see the evidence format before connecting providers:
+## See what studies have found
 
-```bash
-npx humanish init --yes
-npx humanish run first-run
-npx humanish observe --run latest --open
-```
-
-This generates an evidence preview with no provider spend. It does not open
-your app, run an actor, or validate product behavior. To study your own product,
-follow the complete [own-app lab](https://humanish.dev/docs/your-app).
-
-For coding agents, install the companion skill:
-
-```bash
-npx skills add danielgwilson/humanish --skill humanish
-```
+humanish runs studies. Realistic synthetic participants, each with its own
+goals, patience, and skill, actually use your product on isolated desktops while
+you watch. A study leaves verifiable evidence: screenshots, action traces,
+per-task completion funnels, participant outcomes with the denominator
+attached, and estimated cost lines. A fail-closed share-safety gate decides what
+goes into feedback drafts, export bundles and an `observe --all --safe` library, and the
+end of the pipeline is a public-safe feedback draft you can turn into a real
+issue. Committed study source lives under `humanish/`; run evidence lands under
+gitignored `.humanish/`. [ARCHITECTURE.md](ARCHITECTURE.md) traces `humanish run <study>` through
+the code.
 
-Source: [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md).
+The researcher declares the study, the participant tries the product, and the
+stakeholder reads what happened. [Three roles](docs/principles/three-roles.md)
+explains the design; the [email-gated signup study records](https://github.com/danielgwilson/humanish/tree/main/docs/evidence/email-signup/)
+show a completed two-participant study and a reported keyboard-accessibility finding.
 
-## How It Works
+In the [saved run](https://humanish.dev/demo), eight participants played five rounds. Six
+reached the final standings, two were blocked, and `humanish analyze` turned the 13-minute
+recording into seven findings, each linked to the capture behind it.
 
-```text
-humanish/     committed labs, personas, scenarios, coverage notes
-.humanish/   ignored run evidence, Observer output, reviews, local state
-```
+**Numbers so far, every one with its run ids.** Recall on five planted defects
+in a small task app: 15 of 15 across three live runs
+([benchmark](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-2026-09-04-0.76.0.md)). Precision on apps the
+maintainer did not write: TodoMVC 5 of 6 findings confirmed against the source,
+drawDB 11 of 12, none invented
+([TodoMVC](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-TODOMVC-2026-09-01.md), [drawDB](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-DRAWDB-2026-09-01.md)).
+Cold install to a live study: 9 of 9 fresh directories reached the goal in 108 to 200 seconds;
+the five on the API route cost $0.16 to $0.35 each, and the four on Codex or Claude Code are
+unpriced ([study record](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/cold-install-try-live-2026-09-01.md)).
+Same mission, different personas: keyboard-first participants reported drawDB's
+database modal 5 of 5 times and TodoMVC's mouse-only rename 6 of 6; mouse newcomers
+reported them 0 of 5 and 0 of 6 ([study record](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/persona-axis-phone-2026-09-03.md)).
+Planted defects are more legible than real ones and the largest cell is six runs;
+read these as what the machinery found, not as rates for your users.
 
-[ARCHITECTURE.md](ARCHITECTURE.md) traces `humanish run <lab>` through the code.
+## Read the results
 
 After a run, read its findings and verification grade:
 
@@ -202,7 +188,7 @@ review:
   analysis: false
 ```
 
-`humanish run <lab>`, `humanish lab run <lab>`, `humanish watch <lab>`, and live
+`humanish run <study>`, `humanish watch <study>`, and live
 starts in the TUI share this default. Dry runs and unsupported routes dispatch
 nothing. Without `OPENAI_API_KEY`, default analysis is skipped and a successful
 recording stays successful. A default analysis whose admission estimate is over
@@ -211,10 +197,9 @@ command that runs it. Opening the TUI or Observer never starts a request.
 See [automatic analysis](docs/product/automatic-analysis.md) for configuration,
 cancellation, and failure behavior.
 
-## Public-Safety Boundary
+## Share evidence safely
 
-humanish is designed for public repositories and public issue queues. The
-boundary is three planks, each enforced where it actually holds:
+humanish is designed for public repositories and public issue queues.
 
 **1. This repo and the published package are kept public-safe by CI.** Every
 push runs a public-surface scan (secret/key/path shapes, a sha256 binary-asset
@@ -235,11 +220,11 @@ bundle, and review the actual text and pixels before sharing.
 evidence over the network when you pass `--expose`, and humanish has no auth of
 its own behind either one:
 
-- `humanish watch <lab> --expose` streams a live run, which is never
+- `humanish watch <study> --expose` streams a live run, which is never
   `share_ready`, to whoever your edge admits. It requires edge auth:
   `--tunnel ngrok --oauth google`, or `--public-url` for an edge you run. Without
   `--allow-email` or `--allow-domain`, the OAuth edge admits any Google account.
-- `humanish serve --expose` serves your run library. With edge auth and no
+- `humanish observe --all --expose` serves your run library. With edge auth and no
   `--safe`, everyone the edge admits sees every run, raw screenshots included.
   With `--safe`, it serves only `share_ready` runs, and edge auth is optional.
 
@@ -258,8 +243,8 @@ does not yet detect free-form PII or PHI such as names, emails,
 phone numbers, dates of birth, or medical identifiers. Keeping those out depends
 on using synthetic data and on review, so `redaction: passed` means the
 automated secret and path scan found no matches, not that the artifact was
-certified free of PII or PHI. A first-class PII/PHI detector is on the roadmap
-([#108](https://github.com/danielgwilson/humanish/issues/108)).
+certified free of PII or PHI. A first-class PII/PHI detector is
+[planned](https://github.com/danielgwilson/humanish/issues/108).
 
 `humanish verify --json` also reports `shareSafety.status`:
 
@@ -285,14 +270,16 @@ or runs a signed-in agent. The `*.live.test.ts` suites run only when a
 `HUMANISH_LIVE_*` variable and real keys are set. Live behavior is checked only
 by runs made outside CI.
 
-**Codex versions are pinned.** Codex participants (local browser studies and
-`local-agent` with Codex) and the Codex account analyst accept only the Codex
-CLI versions admitted for your host, listed in
-[`qualified-versions.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/qualified-versions.ts).
-On Linux x64 and Apple-silicon macOS those are the versions humanish has qualified. Linux arm64
-and Intel macOS keep the one version they ran before qualification began, which has not been
-qualified there. Any other version, including one Codex updated itself to, is refused with the
-list of accepted versions.
+**Codex versions.** Codex participants (local browser studies and
+`local-agent` with Codex) and the Codex account analyst run any stable Codex CLI release from
+0.154.0 on, except releases humanish refuses, listed in
+[`codex-admission.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/codex-admission.ts).
+A new release runs the day it ships, including one Codex updated itself to. Each launch checks
+the release's app-server schema against the fields humanish uses and refuses one that changed
+them. Prereleases and releases below 0.154.0 are refused, and the refusal names the release and
+why. A hosted participant on a release humanish has not tested records a warning.
+
+**Mobile emulation.** Mobile viewport and touch flags do not certify gesture equivalence.
 
 **Credentials.** humanish fills each provider key that is not already set from
 the first of these sources that has it. It prints the name and source of a key it
@@ -305,12 +292,12 @@ fills from sources 2 to 4, never the value:
 4. `$XDG_CONFIG_HOME/humanish/keys.env` (by default `~/.config/humanish/keys.env`),
    which `humanish keys set` writes as plain text with mode `0600`.
 
-A dry run reads no provider key, so `run`, `lab run` and `watch` consult sources 2 to 4 only
-for a live lab. A live run fills every key it finds and prints the ones its plan reads: its model,
+A dry run reads no provider key, so `run`, `run` and `watch` consult sources 2 to 4 only
+for a live study. A live run fills every key it finds and prints the ones its plan reads: its model,
 desktop and runtime keys, its `subject.env` names, the variable
 `comms.email.external.authTokenEnv` names, `ANTHROPIC_API_KEY` for a Claude Code participant, and
 `OPENAI_API_KEY` when its automatic analysis runs on OpenAI. With a declared scorer it prints
-every key it fills, since the scorer's code may read any. `lab preflight`, `doctor`, `tui` and the
+every key it fills, since the scorer's code may read any. `study check`, `doctor`, `tui` and the
 `comms` commands still consult them.
 `humanish analyze` consults them for a live OpenAI analysis, and not for `--dry-run` or the
 Codex analyst.
@@ -323,73 +310,78 @@ never reads the subject app's own `.env` files.
 **What leaves your machine.** [Trust boundaries](https://humanish.dev/docs/trust-boundaries)
 has the providers' retention terms.
 
-| Party                | What it receives                                                                                                                                                                                                                                                                                                                                            | When                                                                                                                          |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI               | Each step's screenshot, the persona, the mission and the actions so far; after a run, selected text and captures for analysis; for an external-public shared-world lab, the host participant's screen while its lobby code is read; for a terminal study, the agent's requests from the E2B sandbox                                                         | `openai-computer-use` participants; automatic or `humanish analyze` runs; external-public shared-world labs; terminal studies |
-| Codex or Claude Code | The same screenshots and prompts, through your signed-in agent and its provider                                                                                                                                                                                                                                                                             | `local-agent` participants, local browser studies, the Codex analyst                                                          |
-| E2B                  | A desktop or shell running your app and everything on its screen; the repository a `clone` subject names; your working tree for a `local-tree` subject, minus gitignored files, `.env*` and other secret-shaped files; the credentials you declare for the subject app; for a terminal study, your OpenAI key unless `execution.runtimeAuth: openai-egress` | Every hosted study                                                                                                            |
-| PostHog              | Telemetry events, described [below](#telemetry)                                                                                                                                                                                                                                                                                                             | By default                                                                                                                    |
+| Party                | What it receives                                                                                                                                                                                                                                                                                                                                            | When                                                                                                                             |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI               | Each step's screenshot, the persona, the mission and the actions so far; after a run, selected text and captures for analysis; for an external-public shared-world study, the host participant's screen while its lobby code is read; for a terminal study, the agent's requests from the E2B sandbox                                                       | `openai-computer-use` participants; automatic or `humanish analyze` runs; external-public shared-world studies; terminal studies |
+| Codex or Claude Code | The same screenshots and prompts, through your signed-in agent and its provider                                                                                                                                                                                                                                                                             | `local-agent` participants, local browser studies, the Codex analyst                                                             |
+| E2B                  | A desktop or shell running your app and everything on its screen; the repository a `clone` subject names; your working tree for a `local-tree` subject, minus gitignored files, `.env*` and other secret-shaped files; the credentials you declare for the subject app; for a terminal study, your OpenAI key unless `execution.runtimeAuth: openai-egress` | Every hosted study                                                                                                               |
+| PostHog              | Telemetry events, described [below](#check-what-telemetry-sends)                                                                                                                                                                                                                                                                                            | By default                                                                                                                       |
 
-## Commands
+## Find the main commands
 
 Use `npx humanish` from your project. Full arguments and options are generated
 from the shipped CLI in the [command reference](https://humanish.dev/docs/cli).
 
 | Command                                                  | Purpose                                                                   |
 | -------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `humanish init --yes`                                    | Scaffold lab source and ignored runtime state.                            |
-| `humanish doctor --lab <lab> --json`                     | Check the selected route's setup without exposing key values or spending. |
-| `humanish lab list --json`                               | List available labs.                                                      |
-| `humanish lab inspect <lab> --json`                      | Read a lab before running it.                                             |
-| `humanish lab preflight <lab> --json`                    | Check configuration and route warnings.                                   |
-| `humanish run <lab>`                                     | Run the named preview or live study.                                      |
-| `humanish watch <lab>`                                   | Run a lab with an attached Observer.                                      |
+| `humanish init --yes`                                    | Scaffold study source and ignored runtime state.                          |
+| `humanish doctor --study <study> --json`                 | Check the selected route's setup without exposing key values or spending. |
+| `humanish study list --json`                             | List available studies.                                                   |
+| `humanish study show <study> --json`                     | Read a study before running it.                                           |
+| `humanish study check <study> --json`                    | Check configuration and route warnings.                                   |
+| `humanish run <study>`                                   | Run the named preview or live study.                                      |
+| `humanish watch <study>`                                 | Run a study with an attached Observer.                                    |
 | `humanish runs --json`                                   | List local run history.                                                   |
 | `humanish review --run latest --json`                    | Read an existing run's evidence.                                          |
 | `humanish verify --run latest --json`                    | Check evidence and share-safety gates.                                    |
 | `humanish feedback issue --run latest --repo owner/repo` | Print an eligible feedback draft.                                         |
 
-## Exit Codes
+## Check exit codes
 
 | Code    | Meaning                                                                                   |
 | ------- | ----------------------------------------------------------------------------------------- |
 | `0`     | Success.                                                                                  |
-| `1`     | Commander usage error: unknown command, unknown option, or a missing/invalid argument.    |
+| `1`     | Usage error: unknown command, unknown option, or a missing/invalid argument.              |
 | `2`     | humanish domain or validation failure. Check the JSON envelope's `error.code` for detail. |
 | `128+N` | Terminated by signal `N`: `130` for SIGINT, `143` for SIGTERM, `129` for SIGHUP.          |
 
-## The Terminal Surface
+## Browse studies in the terminal
 
-`humanish tui` is for a person browsing labs and runs. It needs an
+`humanish tui` is for a person browsing studies and runs. It needs an
 interactive stdin/stdout, and refuses detected coding-agent sessions even with
-a TTY. Agents should use `lab list --json`, `lab inspect <lab> --json`, and
+a TTY. Agents should use `study list --json`, `study show <study> --json`, and
 `runs --json`. Read [TUI behavior and JSON alternatives](https://humanish.dev/docs/review-surfaces#for-coding-agents-and-scripts).
 
 Its Connections screen (**c**) adds an AgentMail key for
-[real email receiving](docs/architecture/real-email-receiving.md), which gives each participant a
+[real email receiving](https://humanish.dev/docs/email-receiving), which gives each participant a
 fresh hosted inbox.
 
+## Give coding agents the skill
+
+For coding agents, install the companion skill:
+
+```bash
+npx skills add danielgwilson/humanish --skill humanish
+```
+
+Source: [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md).
+
 ## Find more guides
 
-- [Lab manifests](https://humanish.dev/docs/lab-manifests): source directories, route selection,
-  ignored private labs and
-  [scripted browser scenarios](https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios).
+- [Study files](https://humanish.dev/docs/study-files): source directories, route selection,
+  ignored private studies and
+  [scripted browser scenarios](https://humanish.dev/docs/study-files#scripted-browser-scenarios).
 - [Computer use](https://humanish.dev/docs/computer-use): subjects, screenshots, devices, mobile
   emulation, stop rules, dwell windows and reruns of failed participants. The
   [cost model](https://humanish.dev/docs/budgets-and-privacy#how-cost-estimates-work) explains
   model selection, dated estimates, and study and per-participant caps.
 - [A signed-in coding agent](https://humanish.dev/docs/local-agents): Codex or Claude Code supplies
   the participant's model on your existing plan. E2B still needs a key and bills for desktops.
-- [The run library](https://humanish.dev/docs/review-surfaces#serve-the-run-library): `humanish serve`
+- [The run library](https://humanish.dev/docs/review-surfaces#serve-the-run-library): `humanish observe --all`
   serves your runs on loopback, with authenticated remote access,
   [live viewing from a phone](https://humanish.dev/docs/review-surfaces#watch-a-live-run-from-your-phone)
   and share-safe public exposure.
 
-Mobile viewport and touch flags do not certify gesture equivalence. The
-[2026-09-05 input-conformance correction](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/mobile-input-conformance-2026-09-05.md)
-qualifies the historical results from phone-sized participants: they describe humanish's
-measured input path, not established physical-device app behavior.
-
 ## Drive an already-running local app
 
 Use a custom executor and non-vision provider to drive your app's state contract
@@ -404,47 +396,41 @@ Run it after installing `humanish`. It makes no model calls; it proves the
 integration, not persona behavior. See [state-driven local adapters](https://humanish.dev/docs/computer-use#state-driven-local-adapters)
 for the supported library seam.
 
-## Library API
+## Use humanish as a library
 
 `import ... from "humanish"` covers four things:
 
-- run a lab: `runLab`, `RunLabOptions`, `LabOutcome`, `LabResult`, `LabEvent`, `routeOf`,
-  `parseLabConfig`, `LAB_CONFIG_SCHEMA`;
+- run a study: `runStudy`, `RunStudyOptions`, `StudyOutcome`, `StudyResult`, `StudyEvent`, `routeOf`,
+  `parseStudy`, `STUDY_SCHEMA`;
 - read a run: `verifyRun`, `renderObserver`, `RunBundle`, `ActorTrace`;
-- bring a participant: `CuaProvider`, `CuaExecutor`, `ProviderContext`,
+- bring a participant: `ComputerUseProvider`, `ComputerUseExecutor`, `ProviderContext`,
   `createOpenAiResponsesProvider`, `runComputerUseLoop`, `defaultRedactionHooks`;
 - score a run: `AdapterScorerModule` and its scoring contexts.
 
 Everything else runs through the `humanish` command. The
 [library page](https://humanish.dev/docs/library) has an example for each, and
-[the options contract](docs/contracts/schemas.md#library-options-runlaboptions) lists which routes
+[the options contract](docs/contracts/schemas.md#library-options) lists which routes
 take which option.
 
-## Three Roles
-
-The researcher declares the study, the participant tries the product, and the
-stakeholder reads what happened. [Three roles](docs/principles/three-roles.md)
-explains the design; the [email-gated signup receipts](https://github.com/danielgwilson/humanish/tree/main/docs/goals/email-gated-signup/receipts/)
-show a completed two-participant study and a reported keyboard-accessibility finding.
-
-## Telemetry
+## Check what telemetry sends
 
 humanish sends anonymous usage events to PostHog by default. Each event carries
 the command, the humanish version, your OS and Node major version, whether it
 ran in CI, the exit code, a duration bucket and a random machine id made on
 first use. A study adds whether it was a dry run, an outcome word, the
 participant's brain route, stop and diagnostic categories, and humanish's error
-code when it fails. The lab id is sent only when it is a starter lab that
-`humanish init` writes; any other lab is sent as `custom`. Your lab ids,
+code when it fails. The study id is sent only when it is a starter study that
+`humanish init` writes; any other study is sent as `custom`. Your study ids,
 subjects, personas, prompts, paths, run ids and evidence are never sent.
 `humanish telemetry status` prints the exact event, and `humanish telemetry
 disable` or `DO_NOT_TRACK=1` turns it off. [TELEMETRY.md](TELEMETRY.md) lists
 every field.
 
-## Development
+## Contribute
 
-Contributors: read [CONTRIBUTING.md](CONTRIBUTING.md) first. It gives the reading order, the
-commands CI runs and what a pull request needs.
+Contributors: read
+[CONTRIBUTING.md](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md) first. It
+gives the reading order, the commands CI runs and what a pull request needs.
 
 ```bash
 pnpm install --frozen-lockfile
@@ -457,27 +443,14 @@ Try the CLI from source:
 ```bash
 pnpm humanish watch
 pnpm humanish verify
-pnpm humanish lab list
+pnpm humanish study list
 ```
 
-Maintainers draft this repository's feedback issues with
-`pnpm humanish feedback issue --repo danielgwilson/humanish`. It prints a draft and posts nothing.
-
-## Docs
+## Browse the docs
 
 - [User guides and generated CLI reference](https://humanish.dev/docs)
-- [Current safety state and goals](docs/goals/current.md)
-- [Contributing: reading order, commands and pull requests](CONTRIBUTING.md)
-- [Contributor and agent ramp](docs/ramp/README.md)
+- [Contributing: reading order, commands and pull requests](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md)
+- [Contributor and agent ramp](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md)
 - [Architecture: the run path, code map and invariants](ARCHITECTURE.md)
-- [Project layout: the `humanish/` and `.humanish/` folders](docs/architecture/project-layout.md)
+- [Project layout: the `humanish/` and `.humanish/` folders](https://humanish.dev/docs/project-layout)
 - [Feedback contract](docs/contracts/feedback.md)
-- [Release readiness and gates](docs/release/open-source-readiness.md)
-
-Dated design documents may preserve historical mechanisms. Start with the
-current goals and the executable CLI when checking what is supported.
-
-## Release Status
-
-The package is published on npm. Publishing a new version requires explicit
-maintainer authorization; see the [release procedure](docs/release/open-source-readiness.md#publish-procedure).

package/SECURITY.md

@@ -1,34 +1,24 @@
-# Security Policy
+# Security policy
 
-## Public-Safety Boundary
+## Report a vulnerability privately
 
-humanish must not contain or emit PII, PHI, secrets, keys, tokens, raw private
-transcripts, private screenshots, private customer data, private patient data,
-or private source snippets.
-
-Do not file public issues that contain sensitive data. Redact the data and
-describe the class of problem instead.
-
-## Reporting A Vulnerability
-
-If you find a security issue, open a minimal public issue only when the report
-does not disclose exploitable details or sensitive data. Otherwise, contact the
-maintainer privately through the repository owner profile.
+Report a vulnerability through GitHub private vulnerability reporting:
+<https://github.com/danielgwilson/humanish/security/advisories/new>. Only you and the maintainer
+see the report until a fix ships. If you cannot use GitHub, email the maintainer at the address in
+`package.json`'s `author` field.
 
 Include:
 
-- affected version or commit;
-- command run;
-- safe reproduction steps;
-- redacted evidence path or synthetic fixture;
-- whether any generated `.humanish/` artifact may contain sensitive data.
+- the affected version or commit;
+- the command you ran;
+- safe steps to reproduce it;
+- a redacted evidence path or a synthetic fixture;
+- whether a generated `.humanish/` artifact may contain sensitive data.
 
-## Maintainer Release Checks
+## Keep sensitive data out of public issues
 
-Before any public release, run:
+humanish must not contain or emit PII, PHI, secrets, keys, tokens, raw private transcripts,
+private screenshots, private customer data, private patient data or private source snippets.
 
-```bash
-pnpm check
-pnpm public-surface:scan
-pnpm pack:dry-run
-```
+Do not file a public issue that contains sensitive data. Redact it and describe the kind of
+problem.