humanish 0.104.3 → 0.106.0

package/README.md

@@ -3,15 +3,15 @@
 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
+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 stands
-between that evidence and anything public, 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/`.
+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)
 
@@ -24,52 +24,53 @@ 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](bench/RESULTS-2026-09-04-0.76.0.md)). Precision on apps the
+([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](bench/RESULTS-TODOMVC-2026-09-01.md)). Cold install to a live study:
-9 of 9 fresh directories in under three minutes at $0.16 to $0.35 each
-([receipt](docs/goals/computer-use-actor/receipts/cold-install-try-live-2026-09-01.md)).
-Same mission, different personas: keyboard-first participants blocked at drawDB's
-database modal 5 of 5 times and at TodoMVC's rename 6 of 6; mouse newcomers 0 of 5
-and 0 of 6 ([receipt](docs/goals/computer-use-actor/receipts/persona-axis-phone-2026-09-03.md)).
+([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 lanes, each showing its final full-desktop screenshot and outcome](https://unpkg.com/humanish@0.16.0/docs/assets/humanish-drawdb-hero.png)
+![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 lane
-is 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.
+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.
 
 [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
 
-Use **Node.js 20 or newer**, in a project directory:
+Use **Node.js 22.19 or newer**, in a project directory:
 
 ```bash
 npm install --save-dev humanish
 ```
 
 `@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
+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
 preview and local-browser setup need only `humanish`.
 
 Choose how the participant runs:
 
-| Route | 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](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 |
 
 A Codex ChatGPT login can power a `local-agent` participant. It does not
-authenticate Humanish's OpenAI API requests. Choose the actor explicitly in
+authenticate humanish's OpenAI API requests. Choose the actor explicitly in
 your lab; installing Codex does not change an `openai-computer-use` lab.
 
 For local browsers, install only `humanish` and follow the
@@ -80,7 +81,7 @@ ahead of time. Supported Macs use Lima instead of Docker Desktop.
 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.
 
-For a new local study, initialize with your app URL and task:
+For a new local lab, initialize with your app URL and task:
 
 ```bash
 npx humanish init --yes \
@@ -88,12 +89,19 @@ npx humanish init --yes \
   --local-mission "Complete the primary flow and explain anything confusing"
 npx humanish doctor --lab local-browser
 npx humanish run local-browser
+npx humanish verify
 ```
 
-Start your app before running the study. If you already initialized this project,
-edit `humanish/labs/local-browser.yaml` to change its URL or mission; `init`
+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`
 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
+browser or model, not the live study above.
+
 `doctor` only inspects setup. It does not install or start the runtime, open a
 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
@@ -103,9 +111,9 @@ TUN; M3-or-newer Apple Silicon Macs need native ARM64 Node and Lima 2.2+.
 send one synthetic participant into the included drawDB study:
 
 ```bash
-npx humanish init --yes
 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 run try-live
@@ -116,8 +124,13 @@ Existing `E2B_API_KEY` and `OPENAI_API_KEY` environment variables also work.
 `doctor --lab` 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.
-`try-live` clones and studies drawDB, not your project. Its **$2 cap covers
-estimated participant model spend**. Post-run analysis defaults to a separate
+`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
+`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.
 Hosted desktop time is additional. Participant caps are checked
 between turns and are not provider billing ceilings. Allow a few minutes for
@@ -146,10 +159,12 @@ Source: [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md).
 ## How It Works
 
 ```text
-humanish/     committed labs, personas, scenarios, policy, adapters
+humanish/     committed labs, personas, scenarios, coverage notes
 .humanish/   ignored run evidence, Observer output, reviews, local state
 ```
 
+[ARCHITECTURE.md](ARCHITECTURE.md) traces `humanish run <lab>` through the code.
+
 After a run, read its findings and verification grade:
 
 ```bash
@@ -190,13 +205,15 @@ review:
 `humanish run <lab>`, `humanish lab run <lab>`, `humanish watch <lab>`, 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. Opening the TUI or Observer never starts a request.
+recording stays successful. A default analysis whose admission estimate is over
+its limit is skipped the same way, and the CLI prints the `humanish analyze`
+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
 
-Humanish is designed for public repositories and public issue queues. The
+humanish is designed for public repositories and public issue queues. The
 boundary is three planks, each enforced where it actually holds:
 
 **1. This repo and the published package are kept public-safe by CI.** Every
@@ -205,7 +222,7 @@ allowlist, over both tracked files and the packed npm payload) plus a
 full-history gitleaks scan. That protects what we ship; it does not scan your
 repo.
 
-**2. Persisted text is scrubbed for known values and secret patterns.** Humanish
+**2. Persisted text is scrubbed for known values and secret patterns.** humanish
 uses literal matching for provisioned secret values and pattern redaction for
 secret-shaped text in logs, errors, and model narration. Environment provenance
 records variable names. These checks have coverage limits: unknown values,
@@ -214,14 +231,30 @@ screenshots contain whatever was on screen. Use synthetic data, verify the
 bundle, and review the actual text and pixels before sharing.
 
 **3. Run bundles are local by default.** Evidence lands under gitignored
-`.humanish/`, and no command publishes it for you. Sharing evidence (committing
-screenshots, pasting transcripts, attaching bundles to issues) is a deliberate
-act, and reviewing what you share is on you. Use synthetic personas and
-synthetic data so there is nothing sensitive to capture in the first place.
+`.humanish/`. No command uploads a bundle or files an issue. Two commands serve
+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
+  `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
+  `--safe`, everyone the edge admits sees every run, raw screenshots included.
+  With `--safe`, it serves only `share_ready` runs, and edge auth is optional.
+
+Sharing evidence (committing screenshots, pasting transcripts, attaching bundles
+to issues, exposing a server) is a deliberate act, and reviewing what you share
+is on you. Use synthetic personas and synthetic data so there is nothing
+sensitive to capture in the first place.
 
 **What the automated gate enforces.** `humanish verify` scans public-bound
 artifacts and fails closed on secret, key, and token shapes and on known local
-path shapes. It does not yet detect free-form PII or PHI such as names, emails,
+path shapes. It reads text only, judged by a file's bytes rather than its name:
+any file in the run folder that is not UTF-8 text, other than a stream
+screenshot or recording, keeps the run `local_only` (`UNSCANNED_ARTIFACT`). It
+matches after undoing escapes, percent-encoding, HTML entities and base64. It
+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
@@ -238,145 +271,201 @@ certified free of PII or PHI. A first-class PII/PHI detector is on the roadmap
 Feedback commands require `share_ready`. A valid local run can still be
 reviewed in Observer without being promoted into a public issue draft.
 
+## Know these limits before you depend on humanish
+
+**Stability.** humanish is 0.x. There is no written compatibility policy, and
+a minor release can remove exports and options that an earlier release
+deprecated. Pin the exact version and read [CHANGELOG.md](CHANGELOG.md) before
+upgrading.
+
+**CI runs nothing live.** CI runs the offline test suite, the Observer browser
+proofs and, when guest files change, a guest-desktop container proof. It passes
+no provider keys, so no CI job makes a model request, creates a hosted desktop
+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.
+
+**Credentials.** For each provider key a command needs, humanish uses the first
+of these sources that has it. It prints the name and source of each key it
+fills from sources 2 to 4, never the value:
+
+1. the process environment, including a file passed with `--env-file`;
+2. `.humanish/local/provider.env`;
+3. the vendor's own store: `~/.e2b/config.json` for `E2B_API_KEY`, and
+   `gh auth token` for `GH_TOKEN`;
+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. `lab preflight`, `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.
+`HUMANISH_STRICT_KEYS=1` turns off sources 2 to 4. `init` and `doctor` also run
+`codex login status` and `claude auth status` to see which agent is signed in. A live
+computer-use or shared-world run with a `local-agent` participant runs them too, and a live
+computer-use run without `OPENAI_API_KEY` runs them to suggest a signed-in agent. humanish
+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                                                                                                                    |
+
 ## 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 study 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 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. |
+| 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 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
 
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Commander 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. |
+| Code    | Meaning                                                                                   |
+| ------- | ----------------------------------------------------------------------------------------- |
+| `0`     | Success.                                                                                  |
+| `1`     | Commander 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
 
-`humanish tui` is for a person browsing labs and runs. It needs Node 22+ and an
+`humanish tui` is for a person browsing labs 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
 `runs --json`. Read [TUI behavior and JSON alternatives](https://humanish.dev/docs/review-surfaces#for-coding-agents-and-scripts).
 
-Press **c** for Connections, then choose **Add API key** to enter an AgentMail
-key with input hidden. Humanish saves the key in its user-level store (shared
-across your projects) and non-secret connection metadata in
-`.humanish/local/comms.yaml`. Ctrl+C cancels entry and returns to the TUI.
-Existing environment or project keys take precedence over the saved key.
-Saving a key runs a read-only authentication check. Choose **Configure a lab**
-to preview a local copy that gives each participant a fresh real inbox. Email
-is hosted by AgentMail and may be processed by actor/analysis models; these
-recordings require local review. [Setup, tradeoffs and recovery](docs/architecture/real-email-receiving.md).
-
-## Serve the Library
-
-`humanish serve` serves your run library on loopback. The [Observer and terminal guide](https://humanish.dev/docs/review-surfaces#serve-the-run-library)
-covers local viewing, authenticated remote access, and share-safe public exposure.
-
-### Watch a live run from your phone
-
-See [authenticated live viewing](https://humanish.dev/docs/review-surfaces#watch-a-live-run-from-your-phone).
-
-## Lab Manifests
-
-See the [lab manifest reference](https://humanish.dev/docs/lab-manifests) for
-source directories, route selection, and ignored private labs.
-
-### Computer-Use Labs
-
-The [computer-use reference](https://humanish.dev/docs/computer-use) covers
-subjects, screenshots, devices, mobile emulation, stop rules, dwell windows,
-and failed-lane reruns. The [cost model](https://humanish.dev/docs/budgets-and-privacy#how-cost-estimates-work)
-explains model selection, dated estimates, and study/per-participant caps.
+Its Connections screen (**c**) adds an AgentMail key for
+[real email receiving](docs/architecture/real-email-receiving.md), which gives each participant a
+fresh hosted inbox.
+
+## 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).
+- [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`
+  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](docs/goals/computer-use-actor/receipts/mobile-input-conformance-2026-09-05.md)
-qualifies the historical phone-lane results: they describe Humanish's measured input path,
-not established physical-device app behavior.
+[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
+## Drive an already-running local app
 
 Use a custom executor and non-vision provider to drive your app's state contract
-without E2B. The [runnable npm example](docs/architecture/examples/state-driven-local-app/README.md)
+without E2B. The [runnable npm example](examples/participant/README.md)
 includes a synthetic loopback app, deterministic provider, verification and cleanup:
 
 ```bash
-node node_modules/humanish/docs/architecture/examples/state-driven-local-app/runner.mjs
+node node_modules/humanish/examples/participant/run.mjs
 ```
 
 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.
 
-## Browser Scenario Manifests
+## Library API
 
-See [scripted browser scenarios](https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios)
-for executable steps against a running local app.
+`import ... from "humanish"` covers four things:
 
-## A First Live Run Without a Provider API Key
+- run a lab: `runLab`, `RunLabOptions`, `LabOutcome`, `LabResult`, `LabEvent`, `routeOf`,
+  `parseLabConfig`, `LAB_CONFIG_SCHEMA`;
+- read a run: `verifyRun`, `renderObserver`, `RunBundle`, `ActorTrace`;
+- bring a participant: `CuaProvider`, `CuaExecutor`, `ProviderContext`,
+  `createOpenAiResponsesProvider`, `runComputerUseLoop`, `defaultRedactionHooks`;
+- score a run: `AdapterScorerModule` and its scoring contexts.
 
-A [signed-in local Codex or Claude Code](https://humanish.dev/docs/local-agents)
-can supply the participant's model. It consumes your existing plan; E2B still
-requires a key and bills for desktops.
+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
+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](docs/goals/email-gated-signup/receipts/)
+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.
 
-## Maintainer OSS Meta-Lab Example
-
-The bundled `oss` lab is a dry-run contract. Live OSS meta-lab execution is
-unavailable until repository instructions have an isolated credential boundary.
-See the [maintainer reference](https://humanish.dev/docs/lab-manifests#maintainer-oss-meta-lab-example).
-
 ## Telemetry
 
-Humanish collects anonymous command usage by default, excluding labs, subjects,
-personas, paths, and evidence. `humanish telemetry disable` or `DO_NOT_TRACK=1`
-turns it off. See [TELEMETRY.md](TELEMETRY.md) for the exact fields.
+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,
+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
 
+Contributors: read [CONTRIBUTING.md](CONTRIBUTING.md) first. It gives the reading order, the
+commands CI runs and what a pull request needs.
+
 ```bash
-pnpm install
-pnpm check
-pnpm public-surface:scan
-pnpm pack:dry-run
+pnpm install --frozen-lockfile
+pnpm vitest run tests/<file>   # while editing
+pnpm release:check             # once before pushing
 ```
 
-Local dogfood:
+Try the CLI from source:
 
 ```bash
-pnpm humanish:watch
-pnpm humanish:verify
-pnpm humanish:feedback
-pnpm humanish:lab:list
+pnpm humanish watch
+pnpm humanish verify
+pnpm humanish lab list
 ```
 
+Maintainers draft this repository's feedback issues with
+`pnpm humanish feedback issue --repo danielgwilson/humanish`. It prints a draft and posts nothing.
+
 ## 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)
-- [Project layout and architecture](docs/architecture/project-layout.md)
+- [Architecture: the run path, code map and invariants](ARCHITECTURE.md)
+- [Project layout: the `humanish/` and `.humanish/` folders](docs/architecture/project-layout.md)
 - [Feedback contract](docs/contracts/feedback.md)
 - [Release readiness and gates](docs/release/open-source-readiness.md)
 

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Public-Safety Boundary
 
-Humanish must not contain or emit PII, PHI, secrets, keys, tokens, raw private
+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.