humanish 0.104.3 → 0.106.0

package/docs/product/open-source-install-experience.md

@@ -2,19 +2,17 @@
 
 Date: 2026-06-01
 
-Status: product target for the first world-class `humanish` implementation.
+Status: product target for the first `humanish` implementation.
 
 Safety amendment (2026-07-14): the `0.15.1` package binds managed run and
-output storage to validated physical paths, treats provider IDs persisted in a
-run bundle as evidence rather than cleanup authority, and disables live OSS
-meta-lab execution until repository-derived instructions have an isolated
-credential boundary. The historical product target below remains useful for
+output storage to validated physical paths and treats provider IDs persisted in a
+run bundle as evidence rather than cleanup authority. The historical product target below remains useful for
 intent and sequencing, but current behavior is defined by the README and
 [`docs/goals/current.md`](../goals/current.md).
 
 ## Product Promise
 
-Drop Humanish into an app and let a coding agent set up realistic persona
+Drop humanish into an app and let a coding agent set up realistic persona
 simulations, run them safely, watch them in a polished observer, and turn
 friction into public-safe issue drafts.
 
@@ -79,19 +77,19 @@ repo-owned `humanish/` files and package-owned docs.
 
 New projects should get a boring, legible format stack:
 
-- `.yaml` for human-authored Humanish source such as personas, scenarios,
-  policies, labs, and review vocabulary;
-- `.ts` for executable integration such as `humanish/config.ts` and adapters;
+- `.yaml` for human-authored humanish source such as labs, personas and
+  scenarios;
+- `.mjs` for executable adopter scorers;
 - `.json` and `.ndjson` for generated run artifacts, Observer data, review
   output, event streams, and synthetic fixtures.
 
-Use `.yml` only where an outside ecosystem convention already expects it, for
-example GitHub Actions workflows. Do not scaffold `.yml` for Humanish source and
+Use `.yml` only where an outside tool's convention already expects it, for
+example GitHub Actions workflows. Do not scaffold `.yml` for humanish source and
 do not use TOML unless a future scalar global-config case clearly needs it.
 
 ## First-Run Principles
 
-- No keys required for the first wow moment.
+- No keys required for the first successful run.
 - No live GitHub mutation.
 - No hosted queues or private infrastructure.
 - No real customer/user/patient data.
@@ -154,34 +152,32 @@ Suggested scripts:
   "scripts": {
     "humanish": "humanish",
     "humanish:doctor": "humanish doctor",
-  "humanish:run": "humanish run --dry-run",
-  "humanish:watch": "humanish watch",
-  "humanish:lab:list": "humanish lab list",
-  "humanish:watch:ci": "humanish watch --json --no-open",
-  "humanish:verify": "humanish verify"
+    "humanish:run": "humanish run --dry-run",
+    "humanish:watch": "humanish watch",
+    "humanish:lab:list": "humanish lab list",
+    "humanish:watch:ci": "humanish watch --json --no-open",
+    "humanish:verify": "humanish verify"
   }
 }
 ```
 
 ## Command Ladder
 
-| Command | Purpose | First version should |
-| --- | --- | --- |
-| `humanish init` | Set up project-owned harness files | Scaffold committed `humanish/`, ignored `.humanish/`, package scripts |
-| `humanish doctor` | Explain readiness | Check config, gitignore, app target, browser, env var names, redaction policy |
-| `humanish run --dry-run` | Prove contract without app/browser/keys | Write synthetic run bundle |
-| `humanish verify` | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors |
-| `humanish review` | Build review packet from evidence | Summarize verdicts without inventing product proof |
-| `humanish watch` | Run sims and watch the observer | Create a fresh four-lane bundle, render Observer, open it, and keep the shell attached |
-| `humanish watch [lab]` | Run a named lab and watch it | Resolve committed or ignored `.yaml` lab manifests, then open/follow Observer |
-| `humanish watch --json --no-open` | Agent/CI proof path | Create the same bundle and Observer artifacts without browser open or attached watch server |
-| `humanish lab list` | Discover available labs | List committed labs and ignored local labs with origin labels |
-| `humanish lab inspect <lab>` | Read a lab manifest | Print the parsed lab config, origin, path, and warnings without executing |
-| `humanish lab preflight <lab>` | Check lab readiness before spend | Validate routing and optionally probe declared targets from a hosted desktop without launching actors |
-| `humanish lab run <lab>` | Run a lab manifest | Human or JSON execution path for synthetic, OSS meta, and smoke labs |
-| `humanish lab run oss` | Maintainer contract example | Render a dry-run Observer-of-Observers contract for selected repo labels; live execution fails closed pending credential isolation |
-| `humanish lab run oss-smoke` | Maintainer smoke example | Shallow clone lightweight GitHub repos, run setup/proof/verify, report, and remove clones |
-| `humanish feedback issue` | Produce public-safe issue draft | Print Markdown or prefilled issue URL, no GitHub API mutation |
+| Command                           | Purpose                                 | First version should                                                                                  |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `humanish init`                   | Set up project-owned harness files      | Scaffold committed `humanish/`, ignored `.humanish/`, package scripts                                 |
+| `humanish doctor`                 | Explain readiness                       | Check config, gitignore, app target, browser, env var names, redaction policy                         |
+| `humanish run --dry-run`          | Prove contract without app/browser/keys | Write synthetic run bundle                                                                            |
+| `humanish verify`                 | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors                                                       |
+| `humanish review`                 | Build review packet from evidence       | Summarize verdicts without inventing product proof                                                    |
+| `humanish watch`                  | Run synthetic participants and watch    | Create a fresh four-participant bundle, render Observer, open it, and keep the shell attached         |
+| `humanish watch [lab]`            | Run a named lab and watch it            | Resolve committed or ignored `.yaml` lab manifests, then open/follow Observer                         |
+| `humanish watch --json --no-open` | Agent/CI proof path                     | Create the same bundle and Observer artifacts without browser open or attached watch server           |
+| `humanish lab list`               | Discover available labs                 | List committed labs and ignored local labs with origin labels                                         |
+| `humanish lab inspect <lab>`      | Read a lab manifest                     | Print the parsed lab config, origin, path, and warnings without executing                             |
+| `humanish lab preflight <lab>`    | Check lab readiness before spend        | Validate routing and optionally probe declared targets from a hosted desktop without launching actors |
+| `humanish lab run <lab>`          | Run a lab manifest                      | Human or JSON execution path for every lab route                                                      |
+| `humanish feedback issue`         | Produce public-safe issue draft         | Print Markdown or prefilled issue URL, no GitHub API mutation                                         |
 
 ## Live Capability Ladder
 
@@ -226,13 +222,13 @@ browser:
         stateChanged: true
 ```
 
-`humanish run --app-url <loopback-url>` uses the first executable browser
-scenario it finds. If no executable browser steps exist, Humanish falls back to
-the built-in two-step browser persona proof and says so in warnings/review.
+A scripted-browser lab runs the scenario named by `scenario.ref` against a
+loopback `subject.appUrl`; `humanish/labs/scripted-demo.yaml` is the example.
+A missing or non-executable scenario fails before any browser starts.
 
 Live E2B desktop labs are an optional advanced path. Target projects that need
 them should install `@e2b/desktop` explicitly instead of receiving that
-substrate as part of the default Humanish package install. When a GitHub token is
+substrate as part of the default humanish package install. When a GitHub token is
 present, repo labels are redacted in durable artifacts by default; live stream
 auth URLs are used only by the attached watch server and are not persisted.
 

package/docs/ramp/README.md

@@ -1,22 +1,16 @@
-# Humanish Ramp
-
-Status: public-safe contributor and agent ramp.
-
-Package/source version in this tree: `0.104.3` (2026-09-28). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to `0.42.0`. The containment boundary introduced in
-`0.15.1` remains in force: managed run and output paths bind to validated
-physical filesystem identities, and stored provider IDs are evidence, not
-cleanup authority. The bundled OSS meta-lab is dry-run only until
-repository-derived instructions have an isolated credential boundary.
+# humanish Ramp
 
 Use this page when you are starting cold on `humanish`. It is meant to be
 useful without chat history, private notes, local machine paths, or maintainer
-context.
+context. It is the last step of the reading order in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#read-these-in-order) and adds current state, how to pick
+work and the quality bar.
 
 ## First Read
 
 Start with three things:
 
-1. [`AGENTS.md`](../../AGENTS.md) for engineering judgment and public boundaries.
+1. The files in [CONTRIBUTING.md's reading order](../../CONTRIBUTING.md#read-these-in-order).
 2. The current task and [`docs/goals/current.md`](../goals/current.md) for current
    product status. Explicit task direction takes precedence over historical queues.
 3. Instructions in the component being changed, then its relevant contracts.
@@ -26,26 +20,26 @@ to resume automatically. Keep one concise current task handoff with the requeste
 outcome, demonstrated behavior, next complete result, constraints and rejected or
 deferred approaches; link evidence rather than repeating its chronology.
 
-| When working on | Reference |
-| --- | --- |
-| Install, commands or first-run UX | [`README.md`](../../README.md), [install experience](../product/open-source-install-experience.md) |
-| Security, evidence handling or defaults | [Invariants and defaults](../principles/invariants-and-defaults.md) |
-| Observer | [Observer architecture](../architecture/observer.md) and its component instructions |
-| Bundle formats or policy | [Run bundle](../contracts/run-bundle.md), [policy](../contracts/policy.md) |
-| Public artifacts or packaging | [Public-readiness standard](../release/public-readiness-standard.md), [release procedure](../release/open-source-readiness.md) |
+| When working on                            | Reference                                                                                                                                                                      |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Install, commands or first-run UX          | [`README.md`](../../README.md), [install experience](../product/open-source-install-experience.md)                                                                             |
+| Security, evidence handling or defaults    | [Invariants and defaults](../principles/invariants-and-defaults.md)                                                                                                            |
+| Observer                                   | [Observer architecture](../architecture/observer.md) and its component instructions                                                                                            |
+| Bundle formats or policy                   | [Run bundle](../contracts/run-bundle.md), [policy](../contracts/policy.md)                                                                                                     |
+| Public artifacts or packaging              | [Public-readiness standard](../release/public-readiness-standard.md), [release procedure](../release/open-source-readiness.md)                                                 |
 | Proof architecture or historical decisions | [Proof roadmap](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md), [historical delivery roadmap](../roadmap/world-class-open-source-v0.md) |
 
 ## Mental Model
 
-Humanish is a persona simulation harness for apps, CLIs, and agent-facing product
+humanish is a persona simulation harness for apps, CLIs, and agent-facing product
 flows.
 
-- `humanish/` is committed source: personas, scenarios, policy, adapters, and
-  lab manifests.
+- `humanish/` is committed source: lab manifests, personas, scenarios and
+  coverage notes.
 - `.humanish/` is ignored runtime state: runs, Observer output, transcripts,
   reviews, temporary clones, and local evidence.
-- Humanish source uses `.yaml` for human-authored simulation intent, `.ts` for
-  executable integration, and JSON/NDJSON for generated artifacts.
+- humanish source uses `.yaml` for human-authored simulation intent and
+  JSON/NDJSON for generated artifacts.
 - A run bundle is the source of truth.
 - The Observer is the projection that makes that truth reviewable.
 - Feedback commands turn verified evidence into public-safe issue drafts.
@@ -54,147 +48,10 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
-The [0.104.3 release note](../release/0.104.3-local-smtp-catch.md)
-describes SMTP capture for apps hosted by the study operator.
-
-The [0.104.2 release note](../release/0.104.2-recording-timestamps.md)
-describes video capture timestamp precision and retained recording limits.
-
-The [0.104.1 release note](../release/0.104.1-recording-startup.md)
-describes the recording mix buffer correction for early video capture.
-
-The [0.104.0 release note](../release/0.104.0-local-captured-inboxes.md)
-describes captured inboxes for local browser studies.
-
-The [0.103.2 release note](../release/0.103.2-analysis-ending-context.md)
-describes adjacent ending captures for outcome review within the existing budget.
-
-The [0.103.1 release note](../release/0.103.1-analysis-capture-allocation.md)
-describes fairer capture allocation after image-byte reservations are released.
-Evidence limits and completion requirements remain unchanged.
-
-The [0.103.0 release note](../release/0.103.0-desktop-recording.md) describes
-optional desktop video and audio, playback on the shared Observer clock, and
-local-only media evidence. Screenshots remain the default.
-
-The [0.102.0 release note](../release/0.102.0-participant-media.md) describes
-optional native camera and speech. Linux and Mac conversations passed, including
-spoken clarification of a misheard answer. The retained Mac recording also
-produced a validated report after the analysis citation instructions were
-clarified; the validator and original evidence remain unchanged.
-
-The [0.101.0 release note](../release/0.101.0-codex-ui-tools.md) describes native
-Codex UI tools shared by local Firecracker and hosted E2B participants.
-
-The [0.100.1 release note](../release/0.100.1-participant-continuity.md) describes
-continuing local participant conversations and per-turn usage accounting.
-
-The [0.100.0 release note](../release/0.100.0-local-setup.md) describes local
-browser setup discovery, initial navigation readiness and Codex failure stages.
-
-The [0.99.1 release note](../release/0.99.1-action-recovery.md) describes
-participant recovery from browser actions rejected before dispatch.
-
-The [0.99.0 release note](../release/0.99.0-local-browser-mac.md) describes
-local browser studies on supported Apple Silicon Macs through Lima, public ARM
-runtime setup, Codex account participants and automatic analysis.
-
-The [0.98.0 release note](../release/0.98.0-local-browser-studies.md) describes
-installed Linux browser studies with managed runtime images, Codex account
-participants and automatic analysis, and shared CLI/TUI setup checks.
-
-The [0.97.0 release note](../release/0.97.0-codex-account-analysis.md) describes
-explicit Codex account analysis on a qualified Linux CLI/login profile, with
-separate analyst authority, evidence-linked reports and unknown-dollar accounting.
-Existing API defaults remain unchanged; managed local desktops and Mac account
-analysis are not qualified by this release.
-
-The [0.96.1 release note](../release/0.96.1-browser-navigation.md) describes
-accurate physical browser measurements and bounded fitting that preserves normal
-browser controls when they fit. Narrow screens retain the fullscreen fallback.
-
-The [0.96.0 release note](../release/0.96.0-real-email-receiving.md) describes
-fresh per-participant AgentMail inboxes, isolated desktop mail views, host-owned
-cleanup/recovery, local-only evidence publication, and authentication/configuration
-in Connections. SMS and local-agent receiving remain unsupported.
-
-The [0.95.0 release note](../release/0.95.0-connections-setup.md) introduced
-connection profiles and hidden key entry; 0.96.0 makes those connections usable
-in supported browser studies.
-
-The [0.94.0 release note](../release/0.94.0-reliability.md) describes analysis
-request deadlines and budget-aware output, smaller portable recordings,
-recipient-scoped synthetic inboxes, route-aware setup checks, decoded capture
-transitions, pin movement, and explicit camera-support boundaries.
-
-The [0.93.1 release note](../release/0.93.1-observer-review-controls.md) describes
-a compact findings overview, separate analysis-attempt details, styled Observer
-selects and checkboxes, clearer pin/theme states, and smoother navigation.
+[CHANGELOG.md](../../CHANGELOG.md) lists what each version changed. This section describes
+what the source supports now.
 
-The [0.93.0 release note](../release/0.93.0-global-playback.md) describes
-a compact bottom transport whose study time and playback state persist across
-the participant grid and individual recordings.
-
-The [0.92.0 release note](../release/0.92.0-grid-playback.md) describes
-whole-grid recording playback, capture-time scrubbing, explicit coverage gaps,
-and returning from an individual frame to the same paused grid.
-
-The [0.91.1 release note](../release/0.91.1-study-review-polish.md) describes
-retained analysis costs in study totals, finding previews and caveats, final
-active-page viewport measurements, and corrected setup guidance.
-
-The [0.91.0 release note](../release/0.91.0-analysis-quality-and-defaults.md)
-describes automatic analysis by default on supported live recordings, its
-separate disclosed budget and opt-out, fairer evidence selection, and
-evidence-linked review of material concerns and exclusions.
-
-The [0.90.0 release note](../release/0.90.0-automatic-analysis.md) describes
-opt-in analysis after live runs, truthful job states, cancellation, and scripted
-captures and assignments in findings and playback.
-
-The [0.89.1 release note](../release/0.89.1-analysis-finished-notice.md)
-clarifies that an analysis with limitations has finished.
-
-The [0.89.0 release note](../release/0.89.0-study-findings.md) describes explicit
-analysis of completed studies, versioned findings and review corrections, exact
-evidence links, and Participants / Findings within one Observer shell. Analysis
-remains separate from participant feedback and recorded outcomes.
-
-The [0.88.2 release note](../release/0.88.2-sequential-study-budgets.md)
-describes model-spend thresholds on sequential shared-world studies, blocked
-later participants, and explicit unknown-usage accounting.
-
-The [0.88.1 release note](../release/0.88.1-completion-evidence-and-local-app.md)
-describes computer-use labels that distinguish participant reports from
-recorded condition matches. It also covers the complete npm local-app example
-and public `stableProgressKey` export, plus the clipboard fallback correction
-for inherited output pipes.
-
-The [0.88.0 release note](../release/0.88.0-study-diagnostics.md) describes
-computer-use CLI diagnostics, explicit local admission limits and retained
-uncertainty when an earlier provider request did not report usage.
-
-The [0.87.0 release note](../release/0.87.0-participant-endings-and-phone-review.md)
-describes recorded interruption causes, phone playback controls beside fitted
-captures, and credential and evidence-sharing guidance by execution route.
-
-The [0.86.1 release note](../release/0.86.1-task-preflight-saved-recordings.md)
-describes task preflight on unsupported execution paths and saved HTML recordings
-that remain snapshots when served over HTTP.
-
-The [0.86.0 release note](../release/0.86.0-participant-evidence.md) describes
-participant assignments, action-specific replay links and bounded cleanup with
-the current desktop SDK. Old runs without assignment fields remain readable;
-the Observer labels that absence instead of borrowing another participant's goal.
-
-Humanish has a working public package shape and a safe first-run path:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm release:check
-pnpm humanish -- watch --json --no-open
-pnpm humanish -- verify --run latest --json
-```
+humanish has a working public package shape and a safe first-run path.
 
 Implemented:
 
@@ -210,34 +67,35 @@ Implemented:
   `share_ready` evidence;
 - skills.sh-compatible agent skill;
 - first-class lab manifest resolution through `humanish/labs/*.yaml` and
-  ignored `.humanish/labs/*.yaml` overlays — `humanish.lab.v2` compositions
-  (`src/lab-config.ts`), one engine, no hardcoded lab kinds;
-- a first-party actor registry with seven registered descriptors
-  (`src/actor-registry.ts`); `actors[0].type` is a real dispatch key on the
+  ignored `.humanish/labs/*.yaml` overlays, as `humanish.lab.v2` compositions
+  (`src/lab/config.ts`) with one engine and no hardcoded lab kinds;
+- a first-party actor registry with five registered descriptors
+  (`src/actors/registry.ts`); `actors[0].type` is a real dispatch key on the
   computer-use, scripted-browser, and terminal-product routes;
 - a computer-use route and clone subject provider: `subject.source: app-url`
   drives a lab-owner loopback app in a hosted desktop, and `subject.source:
-  clone` + `serve` clones, installs, and serves a real app in-sandbox from
-  config before the actor drives it (`src/cua-actor-lab.ts`);
+clone` + `serve` clones, installs, and serves a real app in-sandbox from
+  config before the actor drives it (`src/routes/computer-use/route.ts`);
 - seven declared subject sources: `this-repo` (dry-run-only), `clone`, `app-url`,
   `local-app` (library-assisted, in-process, no desktop), `terminal-product`,
   `desktop-cli` (computer-use participant at a terminal), and `local-tree`;
   each route fails closed on unsupported combinations;
-- bounded per-lane-world fan-out (`actors[0].count`, `lanes[]`, or `roster[]`),
+- bounded fan-out with separate worlds (`actors[0].count`, `lanes[]`, or `roster[]`),
   backed by deterministic and kept live proof;
-- sequential/concurrent single-origin shared-world execution: sequential has
-  deterministic proof, while concurrent has deterministic and kept live proof;
+- concurrent single-origin shared-world execution with deterministic and kept
+  live proof; verify still reads bundles from the sequential route removed in
+  0.106.0;
 - `subject.source: local-tree`, which packages one selected working tree with a
   content pin before using the same provision-and-serve path as clone subjects;
 - an off-app comms funnel for email-gated flows: a vendor-neutral in-sandbox
   catch redirects the app's own send API, a persona reads a minimal inbox surface
   and clicks through, and a digest-only `humanish.comms-thread.v1` artifact
-  records the thread with no raw address, link, or code — wired into the
+  records the thread with no raw address, link, or code. It is wired into the
   computer-use and concurrent shared-world routes and live-proven on computer-use.
   SMS is not yet a configured execution route;
 - resolved-persona directives that actually shape the actor prompt on the
   terminal-product route (traits are applied and recorded in the actor trace, not
-  decorative), reusing the same `persona.ts` compiler as the computer-use lane;
+  decorative), reusing the same `persona.ts` compiler as the computer-use route;
 - a CLI-loadable adopter scorer seam (`review.scorer.ref` in the lab manifest, or
   a `--scorer <path>` override): a config-declared `.mjs` supplies
   `{score, deriveFeedback, deriveArtifacts}`, resolved with the same containment
@@ -246,37 +104,60 @@ Implemented:
   a pass fails the run on the scorer-capable routes, while library callers keep
   the additive behavior (`costProbe` stays library-only); on the terminal route
   the scoring context carries the FULL normalized transcript (byte-identical to
-  the persisted `terminal-transcript.txt`), not only the ~2KB tail projection;
+  the persisted `terminal-transcript.txt`) instead of the ~2KB tail projection. The
+  [scorer example](../../examples/scorer/README.md) attaches one from the CLI and from a
+  library caller;
 - containment checks for managed run storage, Observer and feedback reads,
   actor artifacts, lab discovery, Git metadata, and source archives;
-- an OSS meta-lab dry-run contract and a separate disposable public-repo OSS
-  smoke harness;
 - cleanup inspection receipts that do not treat mutable run-bundle IDs as
-  provider-mutation authority.
+  provider-mutation authority;
+- every route publishes through the run lifecycle (`runScope` and `Run` in
+  `src/run/run.ts`): computer-use, shared-world, scripted, terminal, and the preview's
+  `runDryRun`.
 
 Still not good enough:
 
-The [current proof-roadmap checkpoint](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/README.md)
-supersedes implementation-status phrases in the 2026-06-10 roadmap packet
-(kept as written — it is a dated record; its README carries current status)
-without changing its success standard.
-
 - capability receipts are not adopter replacement: no first-party deletion
   branch has yet removed a bespoke generic harness while preserving
   decision-equivalent proof;
-- the seven actor descriptors are a closed first-party union, not a supported
+- the five actor descriptors are a closed first-party union, not a supported
   out-of-tree actor-registration API;
-- run storage and provider-resource lifecycle logic still spans several routes
-  instead of one `RunStore` and `ResourceLease` boundary;
-- multi-origin shared-world is a ratified design direction, but remains
+- multi-origin shared-world is an accepted design direction, but remains
   unimplemented and gated on a real adopter proving the need;
-- live OSS meta-lab execution remains disabled until repository-derived
-  instructions have an isolated credential boundary; historical headed-lane
-  evidence does not make the current entrypoint available;
-- the README hero is the drawDB real-application study — a legible capture of a
-  studied public subject, not a Humanish adopter; coverage beyond that single
+- the README hero is the drawDB real-application study, a legible capture of a
+  studied public subject (drawDB is not a humanish adopter); coverage beyond that single
   studied subject (the stratified breadth panel) remains open.
 
+## Check which compositions a lab can declare
+
+`parseLabConfig` (`src/lab/config.ts`) enforces this matrix through `compositionReason`
+(`src/lab/composition-rules.ts`), which uses the predicates in `src/lab/routing.ts` and the reasons
+in `src/lab/validation.ts`. The route entries check it again
+for library callers. `tests/fixtures/task-route-preflight/labs.json` holds one lab for each
+accepted row except the local browser row. `tests/lab/task-route-preflight.test.ts` checks that
+each of those labs routes as shown. `tests/run-lab-local-substrate.test.ts` covers the local
+browser row. Accepted rows have further required fields, such as `subject.serve` on `clone`, and
+the parse error names the missing one. The computer-use actors are `openai-computer-use` and
+`local-agent`.
+
+| Route (backend name)                       | `subject.source`                                 | `execution.target`       | `actors[0].type`                       | Result                                                                         |
+| ------------------------------------------ | ------------------------------------------------ | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
+| `computer-use` (`cua`)                     | `app-url`                                        | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
+| `computer-use` (`cua`)                     | `app-url`                                        | `local`                  | a computer-use actor                   | Supported on a local Firecracker desktop, inside Lima on macOS                 |
+| `computer-use` (`cua`)                     | `clone`, `local-tree`                            | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
+| `computer-use` (`cua`)                     | `desktop-cli`                                    | `e2b-desktop` or absent  | a computer-use actor                   | Supported                                                                      |
+| `computer-use` (`cua`)                     | `local-app`                                      | `local` or absent        | a computer-use actor                   | Library only; the CLI refuses it with `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR` |
+| `shared-world` (`concurrent-shared-world`) | `clone`, `local-tree` + `topology: shared-world` | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
+| `shared-world` (`concurrent-shared-world`) | `app-url` + `topology: shared-world`             | `e2b-desktop`            | a computer-use actor                   | Supported with `policies.allowPublicTargets: true`                             |
+| `scripted`                                 | `app-url` with a loopback URL                    | `local` or absent        | `scripted-browser`                     | Supported                                                                      |
+| `scripted`                                 | `clone`                                          | `e2b-desktop`            | `scripted-browser`                     | Supported                                                                      |
+| `terminal`                                 | `terminal-product`                               | `e2b-terminal` or absent | `codex-exec`                           | Supported                                                                      |
+| `preview` (`synthetic`)                    | `this-repo`                                      | absent                   | not `scripted-browser` or `codex-exec` | Dry run only                                                                   |
+| none                                       | any other pairing                                | any                      | any                                    | Refused at parse with `HUMANISH_LAB_INVALID`                                   |
+
+The fixture's `supported` field records which routes accept declared `actors[0].tasks`. The
+computer-use labs in the fixture accept them. The other routes refuse them at parse.
+
 ## First Commands
 
 From a clean checkout:
@@ -284,23 +165,18 @@ From a clean checkout:
 ```bash
 git status --short --branch
 pnpm install --frozen-lockfile
-pnpm release:check
-pnpm humanish -- watch --json --no-open
-pnpm humanish -- runs --json
-pnpm humanish -- lab list
+pnpm humanish lab list
+pnpm humanish watch --json --no-open   # a keyless preview run
+pnpm humanish runs --json
+pnpm vitest run tests/<file>           # one test file: the fast loop
+pnpm check                             # the full local gate
+pnpm release:check                     # what CI runs; last, before a pull request
 ```
 
 For local product feel:
 
 ```bash
-pnpm humanish -- watch
-```
-
-For public OSS dogfood without credentials:
-
-```bash
-pnpm humanish -- lab run oss --dry-run --json --no-open
-pnpm humanish -- lab run oss-smoke --limit 1 --json
+pnpm humanish watch
 ```
 
 For private/local dogfood, author an ignored lab manifest under
@@ -308,14 +184,14 @@ For private/local dogfood, author an ignored lab manifest under
 ignored env file:
 
 ```bash
-pnpm humanish -- watch .humanish/labs/local-dogfood.yaml --env-file .humanish/local/provider.env
+pnpm humanish watch .humanish/labs/local-dogfood.yaml --env-file .humanish/local/provider.env
 ```
 
 ## How To Pick Work
 
 Start from [`docs/goals/current.md`](../goals/current.md).
 
-Prefer work that makes Humanish more believable to a new maintainer:
+Prefer work that makes humanish more believable to a new maintainer:
 
 - a command becomes easier to run;
 - a run bundle becomes more truthful;
@@ -335,7 +211,7 @@ Do not close a change on narrative alone.
 Useful proof includes:
 
 - `pnpm release:check`;
-- `pnpm release:dogfood` before a tag — see below;
+- `pnpm release:dogfood` before a tag (see below);
 - focused unit or contract tests;
 - a generated run bundle under ignored `.humanish/`;
 - Observer screenshots or health output;
@@ -388,7 +264,6 @@ End substantial work with:
 Future agents should be able to continue from the repo, not from the previous
 chat transcript.
 
-
 ## Before you tag: send a participant to meet the build
 
 ```bash
@@ -396,15 +271,15 @@ pnpm release:dogfood     # needs OPENAI_API_KEY + E2B_API_KEY; costs about a dol
 ```
 
 `release:check` proves the code is internally consistent. It cannot tell you whether
-someone landing on this build can get anywhere with it, and that gap is not
-theoretical: `0.56.0` passed every check and shipped a regression that hid a run's
+someone landing on this build can get anywhere with it. That gap has cost a release:
+`0.56.0` passed every check and shipped a regression that hid a run's
 price at exactly the moment a person was deciding whether to set keys up. A
 synthetic participant found it hours later.
 
 So the last gate before a tag is the product's own first-contact study, pointed at
 the release candidate. It packs the tarball, uploads it into the sandbox, and has a
-real autonomous agent install THAT — not `humanish@latest`, which would measure the
-last release, the one artifact we already know about.
+real autonomous agent install that tarball. Installing `humanish@latest` instead would
+measure the last release, the one artifact we already know about.
 
 It prints the participant's report and fails the gate if they could not get there.
 **Read the report even when it passes.** The verdict is a marker the participant
@@ -413,4 +288,7 @@ adoption problem we already knew about in words no test could produce.
 
 This spends money and needs keys, so it is deliberately NOT part of `release:check`
 and never runs in CI. The lab's caps hold product spend to `$0`; what it costs is
-the agent's own tokens and a few sandbox-minutes.
+the agent's own tokens and a few sandbox-minutes. The agent's model key stays outside
+the sandbox in an E2B egress rule (`runtimeAuth: openai-egress`), and its `web_search`
+fetches run on the model provider's side, so an error from one says nothing about the
+sandbox's network.

package/docs/release/open-source-readiness.md

@@ -136,7 +136,7 @@ the scanner allowlist and keep their approved checksum.
 
 ## Version Policy
 
-Humanish remains on `0.x` until the maintainer explicitly decides to release
+humanish remains on `0.x` until the maintainer explicitly decides to release
 `1.0.0`. General authority to merge and publish does not imply that decision.
 Semantic-version components are integers, not decimals: the next minor after
 `0.99.0` is `0.100.0`; a patch is `0.99.1`. Use patch releases for compatible
@@ -152,7 +152,7 @@ over local publication:
 ```bash
 pnpm release:check
 npm version patch --no-git-tag-version
-# Open and merge the release PR.
+# Add the version's entry at the top of CHANGELOG.md, then open and merge the release PR.
 git fetch origin main --tags
 git switch main
 git pull --ff-only origin main
@@ -161,6 +161,9 @@ git tag "v${VERSION}"
 git push origin "v${VERSION}"
 ```
 
+The GitHub Release for the tag carries the full notes; its opening paragraph is the
+CHANGELOG.md entry.
+
 No agent should run `npm publish` locally without explicit human approval in the
 current thread. That approval must come from the maintainer responsible for the
 release.

package/docs/release/public-readiness-standard.md

@@ -165,7 +165,7 @@ Nice-to-have after public launch:
 - release provenance and staged publishing where practical;
 - signed releases when the release process matures.
 
-## Humanish Application
+## humanish Application
 
 For `humanish`, the honest standard is:
 

package/examples/README.md

@@ -0,0 +1,11 @@
+# Run the examples
+
+Each folder is a complete example that ships in the npm package. After `npm install humanish`, run
+one from `node_modules/humanish/examples/`. Both need Node.js 22.19 or newer, and neither needs a
+key. `pnpm api:proof`, part of `pnpm release:check`, runs both against the packed package.
+
+- [participant/](participant/README.md): bring your own participant. A synthetic loopback app is
+  driven through its state contract by a `CuaExecutor` and a deterministic provider, with no
+  browser, screenshots or E2B.
+- [scorer/](scorer/README.md): score a run with your own rubric. One scorer module is attached to a
+  dry run from a library caller and from the CLI, with no desktop or running app.