humanish 0.104.3 → 0.106.0

package/docs/architecture/guest-desktop.md

@@ -1,9 +1,9 @@
 # Headed browser guest components
 
-These internal components implement native input and full-desktop captures for a
-maintained browser-only guest. They do not enable a public local-runtime mode.
-The VM owner, control transport, app network policy, installed setup and complete
-study journey require separate qualification.
+These internal components implement native input and full-desktop captures for the browser guest
+that [local browser studies](local-browser-runtime.md) run in a Firecracker VM. This page covers
+the guest driver and its container proof; the local browser page covers the VM, its network
+policy and the installed study.
 
 The driver uses the existing `CuaExecutor` contract behind
 [browser control](browser-control.md). Coordinates refer to the complete Xvfb
@@ -20,7 +20,10 @@ Xauthority and guest temporary directory come from the owner. Key names map to a
 closed list before reaching xdotool, whose own command syntax must never receive
 arbitrary participant strings. A native wheel step is not an exact pixel-scroll
 promise; one action permits at most 100 wheel steps. The entire drag is checked
-before its first input.
+before its first input. A pointer action's held keys must be modifiers (Shift,
+Ctrl, Alt, Super). They go down with one `keydown` before the action and up with
+one `keyup` after it. When an input fails, the `keyup` is still sent once, unless
+the session was revoked; the failure then closes the executor as below.
 
 Each input checks the current authority after asynchronous preparation. A
 partial or unacknowledged input closes the executor; it is never automatically
@@ -57,6 +60,14 @@ raw diagnostic text is never returned as an executor error. Only an acquired,
 still-live child handle authorizes termination. If capture-helper exit cannot
 be confirmed, its private files stay for runtime-owner reclamation.
 
+## Three guest files stay at the `src/` root
+
+Three guest files stay at the `src/` root because the guest image and its packager name their
+`dist/` paths. The guest's `vsock.py` launches `guest-runtime-main.js`, and
+`scripts/guest-runtime-package.mjs` walks the payload from it. The packager also regenerates
+`guest-runtime-revision.js` by name. The packager and the `runtime/browser-media/` recipes copy
+`guest-media-worker.js` by name.
+
 ## Build and proof
 
 The source-only [guest recipe](https://github.com/danielgwilson/humanish/blob/main/runtime/browser-guest/README.md) builds a
@@ -80,8 +91,9 @@ attempts, full-frame captures, synthetic app readback and exact-container cleanu
 under ignored `.humanish/guest-desktop-proof/`.
 
 The proof covers visible browser chrome, address-bar navigation, Unicode and
-rapid/large/stalled-renderer text insertion, page/focus rejection, pointer and
-keyboard input, native scrolling and cancellation. CI reruns this proof for
-changes to the guest driver, image recipe, protocol or dependency lockfile. Its deterministic fixture is not a model participant,
-a run bundle, a host network policy, an independent watchdog or a Linux/Mac
-installed study. Those remain separate gates before local runtime support.
+rapid/large/stalled-renderer text insertion, page/focus rejection, pointer and keyboard input,
+native scrolling and cancellation. CI reruns this proof for changes to the guest driver, image
+recipe, protocol or dependency lockfile. Its deterministic fixture is not a model participant, a
+run bundle, a host network policy, an independent watchdog or a Linux/Mac installed study. The
+local browser runtime is qualified separately; see [local browser
+studies](local-browser-runtime.md).

package/docs/architecture/local-browser-runtime.md

@@ -15,7 +15,7 @@ version supporting nested virtualization; see [Mac setup](#apple-silicon-macs).
 Docker Desktop is unnecessary. See
 [Codex account setup](restricted-codex-analysis.md) for the qualified version
 and account restrictions. Docker access is an administrative capability.
-Humanish does not install Docker on Linux or change host permissions. On Mac,
+humanish does not install Docker on Linux or change host permissions. On Mac,
 setup installs Docker only inside the dedicated Lima host.
 
 Configure the starter while initializing the project, then start your app on
@@ -26,39 +26,46 @@ npx humanish init --yes \
   --local-browser http://127.0.0.1:3000 \
   --local-mission "Create a note and explain anything confusing about saving it"
 npx humanish doctor --lab local-browser
-npx humanish lab run local-browser
+npx humanish run local-browser
+npx humanish verify
 ```
 
-`init` also writes `humanish/labs/local-browser.yaml` with safe defaults when
-the two options are omitted. The options provide the normal setup path for the
-app URL and mission on first setup. If the file already exists, `init` preserves
-it and warns that these options were skipped; edit the existing manifest to
-change its URL or mission. The resulting lab has this shape:
+`verify` checks the saved run bundle, and its share-safety line says whether the evidence can be
+shared as-is. `init` also adds `humanish:*` scripts to `package.json`; `humanish:run` among them
+is `humanish run --dry-run`, a contract-proof dry run rather than this live study. `init` also
+writes `humanish/labs/local-browser.yaml` with safe defaults when the two options are omitted.
+The options provide the normal setup path for the app URL and mission on first setup. If the
+file already exists, `init` preserves it and warns that these options were skipped; edit the
+existing manifest to change its URL or mission. The commands above write this lab (its
+`description` is omitted here):
 
 ```yaml
 schema: humanish.lab.v2
 id: local-browser
-title: Review the note editor
+title: Local browser · your app · Codex account
 subject:
   source: app-url
-  appUrl: http://127.0.0.1:3000
+  appUrl: "http://127.0.0.1:3000"
 actors:
   - type: local-agent
     localAgent: codex
-    count: 2
-    mission: Create a note and explain anything confusing about saving it.
-scenario:
-  mode: live
+    persona: synthetic-new-user
+    mission: "Create a note and explain anything confusing about saving it"
 execution:
   target: local
-  concurrency: 2
+  concurrency: 1
   timeoutMs: 120000
+scenario:
+  mode: live
+defaults:
+  open: true
 ```
 
 ```sh
 npx humanish runtime status --json
 npx humanish doctor --lab local-browser --json
-npx humanish lab run local-browser
+npx humanish run local-browser
+npx humanish verify
 ```
 
 The first live run downloads the pinned runtime archive (about 569 MiB on x64 or
@@ -81,7 +88,7 @@ For API billing and its supported caps, use `type: openai-computer-use`, remove
 default. Neither path silently falls back to another provider or hosted desktop.
 Existing labs without `execution.target: local` retain their previous behavior.
 
-Before handing the desktop to the participant, the guest navigates to the
+Before handing the desktop to the participant, the guest opens the
 selected app and waits up to 30 seconds for the initial document's
 `DOMContentLoaded` event, then allows a bounded paint. It does not wait for app
 data, images or network idle: the app's own loading screen remains observable.
@@ -90,8 +97,10 @@ Later participant actions and observations do not use this startup wait.
 
 ## Current limits
 
-- Linux x64 or M3-or-newer Mac with native ARM64 Node and Lima. The installed
-  Mac journey was tested on an M5 Max; smaller machines are not capacity-qualified.
+- Linux x64 or M3-or-newer Mac with native ARM64 Node and Lima. Linux ARM64 is
+  refused: the local participant, the restricted Codex participant, runs only on
+  Linux x64 and Apple-silicon macOS. The installed Mac setup was tested on an M5
+  Max; smaller machines are not capacity-qualified.
 - On Linux, a local Docker Engine; remote contexts, rootless Docker and Docker
   Desktop are unsupported. The Mac adapter uses Docker inside its own Lima host.
 - Loopback HTTP(S) app URLs on explicit ports above 1023. Each participant can
@@ -119,13 +128,13 @@ rules. An unconfirmed release is reported as such.
 ## Runtime maintenance
 
 The npm build pins a release URL, byte count, SHA-256 and immutable Docker image
-ID in `src/local-runtime-release.ts`. It has no moving `latest` image dependency.
+ID in `src/substrates/local/runtime-release.ts`. It has no moving `latest` image dependency.
 Runtime releases include source archives and notices separately; study users do
 not download those archives. Updating a runtime requires a reviewed catalog
 change and a new CLI release.
 
 Source builders can use the
-[maintained recipes](../../runtime/local-firecracker/README.md) and set
+[maintained recipes](https://github.com/danielgwilson/humanish/blob/main/runtime/local-firecracker/README.md) and set
 `HUMANISH_LOCAL_RUNTIME_IMAGE` to an already-built compatible local image. An
 invalid override fails; it does not cause an implicit registry pull.
 
@@ -157,7 +166,7 @@ Status and doctor do not create or start Lima. Explicit setup/first live use
 starts the owned host; closing a study removes its participant containers and
 volumes, but keeps the reusable Lima host running. Stop it with
 `limactl stop humanish-runtime` when no studies are running. An interrupted
-first provision remains inspectable through Lima and can be retried. Humanish
+first provision remains inspectable through Lima and can be retried. humanish
 does not replace a conflicting instance or stop unrelated instances.
 
 Normal close, cancellation and controller death were exercised on established

package/docs/architecture/observer-review.md

@@ -3,7 +3,7 @@
 Observer shows a study's participants, their recorded screens, and the events
 that explain those screens. The grid, player and exported HTML use the same
 current renderer. Screens fit their actual aspect ratio; a portrait capture is
-never cropped to fill a landscape tile.
+never cropped to fill a wide tile.
 
 ## Choose the right entry point
 
@@ -12,11 +12,11 @@ that owns a hosted desktop can offer its live stream while it runs. `--no-open`
 keeps that attachment without launching a browser. `--json` is the machine-result
 path and does not keep an interactive stream server attached.
 
-`humanish observe --run <id>` opens an existing study without starting another.
-The TUI's **Open Observer** action does the same through its session-owned
-loopback library. These entry points follow saved captures; they cannot recover
-live desktop credentials owned by another process. Keep the owning CLI or TUI
-open while using its viewer. Exported HTML is an independent offline recording.
+`humanish observe --run <id>` opens an existing study without starting another. The
+TUI's **Open in Observer** action does the same through its session-owned loopback
+library. These entry points follow saved captures; they cannot recover live desktop
+credentials owned by another process. Keep the owning CLI or TUI open while using its
+viewer. Exported HTML is an independent offline recording.
 
 ## Read status without guessing
 
@@ -62,7 +62,7 @@ limit while keeping selected participants removable.
 
 Icon buttons use Lucide glyphs, accessible names, hover/focus hints and visible
 keyboard focus. Touch targets expand to 44px. Popovers have explicit close buttons;
-Escape dismisses a hint without navigating the player. These conventions follow
+Escape dismisses a hint without moving the player. These conventions follow
 [Carbon icon usage](https://carbondesignsystem.com/elements/icons/usage/),
 [ARIA toggle-button semantics](https://www.w3.org/WAI/ARIA/apg/patterns/button/),
 and [WCAG target sizing](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
@@ -81,8 +81,8 @@ following. A missing addressed moment is reported instead of silently replaced.
 
 Screenshot playback is sparse evidence, not a video recording. Capture gaps stay
 visible. **Skip waits** compresses intervals associated with recorded waits and
-reports the skipped duration. **Next action**, **Next finding**, activity filters
-and grouped waits make long traces easier to inspect without deleting events.
+reports the skipped duration. **Next action**, **Next flagged frame**, activity
+filters and grouped waits make long traces easier to inspect without deleting events.
 Older unstamped recordings use labeled estimated pacing. Long feeds, filmstrips,
 terminal output and event lists stay bounded while earlier/later content remains
 reachable.

package/docs/architecture/observer.md

@@ -3,7 +3,7 @@
 Date: 2026-06-01 (current-state note updated 2026-07-14)
 
 Status: implemented for synthetic streams and persisted live browser,
-terminal-product, fan-out, and sequential/concurrent shared-world evidence.
+terminal-product, fan-out, and shared-world evidence.
 Plain computer-use and shared-world runs can publish an in-progress bundle to
 an attached loopback Observer without persisting runtime stream-auth URLs. The
 version-pinned README image is a synthetic technical sample, not real-application
@@ -35,16 +35,16 @@ event stream contract that live adapters update while a run is active.
 
 ## Stream Model
 
-Streams are the central abstraction. A stream is one watchable persona lane,
+Streams are the central abstraction. A stream is one watchable view of a persona,
 regardless of substrate:
 
-- `ui`: browser/VNC style UI simulation lane;
-- `browser`: browser-specific lane when the app and actor are separate;
-- `terminal`: CLI persona lane with stdout/stderr evidence;
-- `tui`: PTY/ANSI terminal UI lane;
-- `codex-ui`: Codex-style app-server session lane;
-- `artifact`: artifact-only evidence lane;
-- `summary`: run-level synthesis lane.
+- `ui`: browser/VNC style UI simulation stream;
+- `browser`: browser-specific stream when the app and actor are separate;
+- `terminal`: CLI persona stream with stdout/stderr evidence;
+- `tui`: PTY/ANSI terminal UI stream;
+- `codex-ui`: Codex-style app-server session stream;
+- `artifact`: artifact-only evidence stream;
+- `summary`: run-level synthesis stream.
 
 Each stream points back to a simulation and carries its own transport,
 terminal tail, UI state, artifact links, event timeline, and public-safe
@@ -54,7 +54,7 @@ metadata.
 
 `humanish watch` now:
 
-1. creates a fresh four-lane synthetic run bundle;
+1. creates a fresh four-participant synthetic run bundle;
 2. writes `observer-data.json` and `events.ndjson`;
 3. starts a localhost Observer server;
 4. opens the served Observer URL;
@@ -67,19 +67,21 @@ the same fresh evidence without browser open or a long-running process.
 
 ### Reopening a run
 
-The TUI's **Open Observer** action opens an HTTP view that follows saved captures
-as the run writes them. One loopback evidence server is shared by the session's
-browser tabs; exiting the TUI closes it, including when the UI fails. Opening a
-run does not launch a study. The URL is always shown for manual opening or SSH
-port forwarding, and only contained run paths in the TUI's project are accepted.
-
-| Entry point | What updates | Lifetime |
-| --- | --- | --- |
-| `watch` during a study | Saved evidence and available in-memory desktop streams | Until the attached command exits |
-| `observe --run <id>` | Saved evidence from the selected run | Until the command exits |
-| TUI Open Observer | Saved evidence in the selected run; shares the project's evidence library | Until the TUI exits |
-| `serve` | Saved evidence across the project's library | Until the server command exits |
-| Static HTML or `file://` | The exported snapshot | Independent of a server |
+The TUI's **Open in Observer** action opens an HTTP view of the selected run's saved
+captures, including a run that is still going: the server renders it from the saved
+bundle on each poll. The TUI offers it once the run has written its bundle, after
+Stop on a running run. One loopback evidence server is shared by the session's
+browser tabs; exiting the TUI closes it, including when the UI fails. Opening a run
+does not launch a study. The URL is always shown for manual opening or SSH port
+forwarding, and only contained run paths in the TUI's project are accepted.
+
+| Entry point              | What updates                                                              | Lifetime                         |
+| ------------------------ | ------------------------------------------------------------------------- | -------------------------------- |
+| `watch` during a study   | Saved evidence and available in-memory desktop streams                    | Until the attached command exits |
+| `observe --run <id>`     | Saved evidence from the selected run                                      | Until the command exits          |
+| TUI Open in Observer     | Saved evidence in the selected run; shares the project's evidence library | Until the TUI exits              |
+| `serve`                  | Saved evidence across the project's library                               | Until the server command exits   |
+| Static HTML or `file://` | The exported snapshot                                                     | Independent of a server          |
 
 `observe` uses the same current-data projection as the attached viewer, scoped
 to the selected run. Its history cannot enumerate other runs. HTML exports use
@@ -101,16 +103,10 @@ mismatched records omit the observation. A stale heartbeat alone does not prove
 interruption, and stored PIDs are neither probed nor returned. Static rendering
 and export do not create this served-only observation.
 
-Local `codex-exec` actor runs now publish an initial running `run.json` and
-`observer/observer-data.json` before actor completion, then refresh both after
-sanitized transcripts, traces, and verdict events are available. This gives a
-served Observer a truthful active state to poll while noninteractive local
-actors are still running.
-
 Watch is deliberately distinct from `humanish serve`. Watch serves ONE
 attached run, and the process that created it may inject runtime stream URLs
 (live hosted-desktop viewers) into the observer data it serves. Serve is the
-LIBRARY surface — every run under `.humanish/runs/` — and never serves runtime
+library surface (every run under `.humanish/runs/`) and never serves runtime
 stream URLs in any mode; remote viewers see persisted evidence only. See
 [Serve: the run library surface](serve.md).
 
@@ -120,26 +116,26 @@ The live `serveObserver` server binds `127.0.0.1` and, by default, is a
 local-dev server without a Host allowlist. Every response carries security
 headers, including `X-Frame-Options: DENY` and CSP `frame-ancestors 'none'`.
 Under its
-`exposed` option — set by `watch --expose` — it enforces the SAME
+`exposed` option, which `watch --expose` sets, it enforces the same
 DNS-rebinding defense as the library surface: a strict Host allowlist (loopback
 names at bind, extended by `addPublicOrigin(tunnel.url | public-url)`, `421
 Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
-every response (both live in `src/serve-http.ts`, shared without a module cycle).
+every response (both live in `src/observer/http.ts`, shared without a module cycle).
 The Host allowlist applies in exposed mode; frame-denial headers apply in both modes.
 
 Exposed mode also SCOPES the surface to the attached live run (`result.run`): the
 `/_humanish/history.json` index is filtered to that one run, and `/_humanish/runs/<id>/…`
 404s byte-identically to a nonexistent run for any other id. A remote viewer who
-clears the edge auth can therefore see only the run being watched — never enumerate
-or fetch a prior run's raw, unverified evidence. Loopback keeps the full cross-run
+clears the edge auth can therefore see only the run being watched. They can never
+enumerate or fetch a prior run's raw, unverified evidence. Loopback keeps the full cross-run
 library (history + any run by id) exactly as before.
 
 `watch --expose` is the ONE surface that DELIBERATELY streams the live E2B
 desktop to a remote viewer: the attached watch process genuinely holds the
-runtime stream URLs (in the in-memory `WeakMap`, never persisted), and streaming
-them is the whole point of watching from a phone. It is safe only because the
+runtime stream URLs (in the in-memory `WeakMap`, never persisted), and watching
+from a phone needs them. It is safe only because the
 ngrok edge (Google OAuth + allow rules) or an operator `--public-url` edge
-authenticates the viewer first — `watch --expose` therefore always requires edge
+authenticates the viewer first, so `watch --expose` always requires edge
 auth (a live run is never `share_ready`, so `--safe` alone cannot gate it). The
 attached server comes up DURING the run and survives a `timed_out`/`failed` run
 (serving is not gated on pass/fail), so a failed run's evidence stays inspectable
@@ -189,8 +185,9 @@ The Observer shell has:
 
 - a persistent study library and a compact study header;
 - Participants and Findings views that share the same shell geometry;
-- stream filters for UI, CLI, TUI, and Codex UI lanes;
-- grid mode with one tile per sim stream;
+- status and participant-kind filters, where kind is the stream kind (`ui`,
+  `terminal`, `tui`, `codex-ui` and others);
+- grid mode with one tile per participant stream;
 - focus mode with left stream rail, center stage, and right tabs;
 - terminal/TUI transcript stage;
 - right evidence rail for events, artifacts, and known gaps.
@@ -205,8 +202,8 @@ the source event rather than inventing a playback frame.
 
 The participant grid uses equal-height previews whose widths follow each screen's
 aspect ratio. A 44px identity/source/outcome caption sits below the captured pixels;
-no badges or controls cover the screen. Generated computer-use lane labels display
-the recorded persona identity; repeated identities gain a lane or stream qualifier.
+no badges or controls cover the screen. Generated computer-use participant labels display
+the recorded persona identity; repeated identities gain a participant or stream qualifier.
 A stable details button opens labeled Pin/Compare actions, recorded notices, final
 messages, dimensions, duration and exact identifiers. Exceptional outcomes remain
 in the caption. Icon controls have visible hover/focus hints and touch-sized targets. Search, preview size and monitor mode
@@ -231,7 +228,7 @@ A host adapter may provide:
 - public-safe artifact links.
 
 If no embed URL exists, the Observer still renders the Codex-style timeline and
-session contract instead of failing the lane.
+session contract instead of failing the stream.
 
 ## Historical slice and remaining gaps
 
@@ -241,12 +238,12 @@ stream contracts; local `codex-exec` active-run snapshots followed.
 Subsequent additions through 2026-06-11 included:
 
 - Playwright-backed browser proof with scripted, app-specific
-  `browser.steps` authored in `humanish/scenarios/*.yaml` (`src/run.ts`);
-- native Codex app-server session adapter (`src/codex-app-server.ts`,
-  registered in `src/actor-registry.ts`);
-- E2B desktop substrate lanes on the meta and computer-use routes;
+  `browser.steps` authored in `humanish/scenarios/*.yaml` (`src/actors/scripted-browser/`);
+- native Codex app-server session adapter (`src/actors/codex/app-server.ts`,
+  registered in `src/actors/registry.ts`);
+- E2B desktop participants on the computer-use and shared-world routes;
 - computer-use bundles persist a `screenshots/` directory and the Observer
-  renders the frames (`src/cua-actor-lab.ts`).
+  renders the frames (`src/routes/computer-use/lanes.ts` writes them).
 
 Intentionally still adapter work:
 
@@ -259,15 +256,14 @@ Intentionally still adapter work:
 
 The renderer is the `observer/` workspace: a Vite single-file build on the
 `@humanish` registry tokens, frozen against `humanish.observer-data.v1`
-(`tests/observer-data-contract.test.ts`). The root build copies the workspace
+(`tests/observer/data-contract.test.ts`). The root build copies the workspace
 artifact to `dist/observer-app.html`; in a repo checkout a missing or stale
 artifact auto-builds, and an unconditional preflight at CLI startup makes a
-broken artifact cost seconds, never a completed session. `renderObserverHtml`
-— the one choke point every surface (observe, watch, serve, labs) funnels
-through — injects the run's snapshot into the artifact
-(`tests/observer-artifact.test.ts` pins the path, cold, so CI exercises the
-auto-build every run). The legacy string-concat renderer
-(`src/observer-assets.ts`) was deleted at cutover; there is no flag and no
-fallback — rollback is a version pin. The workspace's own tests pin the
-durability constraints (self-contained single file, fonts inlined, no network
-references).
+broken artifact cost seconds, never a completed session. `renderObserverHtml`,
+the one function every surface (observe, watch, serve, labs) renders through,
+injects the run's snapshot into the artifact
+(`tests/observer/artifact.test.ts` pins the path, cold, so CI exercises the
+auto-build every run). The legacy string-concat renderer was deleted at
+cutover; there is no flag and no fallback. Rollback is a version pin. The
+workspace's own tests pin the durability constraints (self-contained single
+file, fonts inlined, no network references).

package/docs/architecture/participant-media.md

@@ -1,6 +1,6 @@
 # Optional participant media
 
-Media belongs to the desktop. The participant still navigates through screenshots
+Media belongs to the desktop. The participant still works through screenshots
 and the shared computer-use loop, using one continuing Codex conversation for
 clicks, listening and spoken replies.
 
@@ -55,11 +55,11 @@ can retain actual screen and audio playback alongside this evidence.
 
 ## Hosted desktops
 
-The same worker and participant loop support hosted speech. Humanish selects a
+The same worker and participant loop support hosted speech. humanish selects a
 versioned public E2B media template when speech is requested; ordinary browser
 studies keep the stock desktop. The usual E2B credentials and Codex login are
 sufficient. `execution.desktop.template` remains an explicit override for your
-own compatible image; see the [build recipe](../../runtime/browser-media/E2B.md).
+own compatible image; see the [build recipe](https://github.com/danielgwilson/humanish/blob/main/runtime/browser-media/E2B.md).
 The host starts the worker through the SDK's streaming command interface, and
 model credentials stay on the host. Missing dependencies fail desktop preparation
 before a participant starts.

package/docs/architecture/project-layout.md

@@ -1,166 +1,62 @@
-# Project Layout Contract
+# Project Layout
 
-Date: 2026-06-01
-
-Status: target layout for apps that install `humanish`.
-
-## Decision
-
-Use two roots:
+`humanish init` gives a project two roots:
 
 ```text
-humanish/   # committed source of simulation intent
-.humanish/  # ignored runtime state, evidence, local overlays, and secrets
+humanish/   # committed lab source
+.humanish/  # ignored runtime state, evidence and local overrides
 ```
 
-Do not gitignore all Humanish state. Labs, personas, scenarios, policies,
-adapters, coverage maps, and review vocabulary are the harness. They must be
-versioned, reviewed, and reproducible from a clean clone.
-
-Do not commit run bundles, raw screenshots, browser traces, transcripts,
-draft issue bodies before verification, local auth, local overrides, or secrets.
+## Committed lab source: `humanish/`
 
-## Committed Source Plane
-
-`humanish/` is the project-owned simulation contract:
+`init` writes:
 
 ```text
 humanish/
   README.md
-  config.ts
+  labs/
+    first-run.yaml          # keyless preview
+    try-live.yaml           # first live lab
+    cua-browser.yaml        # computer-use participants on a hosted desktop
+    local-browser.yaml      # computer-use participants on a local desktop
+    lobby-trivia-3player.yaml
   personas/
     synthetic-new-user.yaml
     skeptical-power-user.yaml
   scenarios/
     first-run-smoke.yaml
     onboarding-regression.yaml
-  labs/
-    first-run.yaml
-  policies/
-    redaction.yaml
-    network.yaml
-    credentials.example.yaml
-  adapters/
-    app.ts
-  review/
-    vocabulary.yaml
-    milestones.yaml
   coverage-map.md
   coverage-matrix.md
-  fixtures/
-    synthetic-login-state.json
 ```
 
-## Humanish Format Stack
-
-Use formats based on who edits the file and how it is consumed:
+Labs select their subject, actors, personas, scenarios, tasks, budgets and
+policies. Personas and scenarios are referenced by id. An adopter scorer is an
+`.mjs` module that a lab names under `review.scorer.ref`.
 
-- `.yaml` for human-authored Humanish source: personas, scenarios, policies,
-  labs, review vocabulary, and review milestones. Prefer `.yaml` over `.yml`
-  for Humanish-owned source files.
-- `.ts` for executable project integration: `humanish/config.ts`, adapters,
-  route catalogs, app launch plans, and logic that benefits from imports or
-  type checking.
-- `.json` for generated machine artifacts and synthetic fixtures: run bundles,
-  observer data, review JSON, latest/history pointers, and fixture records.
-- `.ndjson` for appendable event or transcript streams.
-- `.yml` is acceptable for ecosystem files that conventionally use it, such as
-  `.github/workflows/*.yml`; do not use `.yml` for Humanish-owned authored
-  source.
+Keep this directory reviewable and reproducible from a clean clone. Everything in
+it is public-safe: synthetic personas and fixtures, env var names without values.
 
-Do not convert personas or scenarios to JSON because parser implementation is
-easier. Keep authored simulation intent readable, then validate it through
-schemas and CLI checks. TOML is not part of the current Humanish stack; add it
-only if a concrete scalar global-config need appears that is better served by
-TOML than YAML, TypeScript, or JSON.
-
-Committed files must be public-safe:
-
-- synthetic personas only;
-- synthetic or redacted fixtures only;
-- env var names only, never values;
-- no PHI, PII, keys, tokens, raw private transcripts, real screenshots, real
-  customer data, or real patient data.
-
-Changing a scenario or persona is equivalent to changing a test. It should be
-visible in PR review.
-
-## Ignored Runtime Plane
-
-`.humanish/` is local/generated state:
+## Ignored runtime state: `.humanish/`
 
 ```text
 .humanish/
-  runs/
-    <run-id>/
-      run.json
-      review.md
-      review.json
-      observer/
-      screenshots/
-      traces/
-      terminal/
-      feedback/
-  cache/
-  tmp/
-  logs/
-  labs/
-  local/
-    labs/
-    personas/
-    policies/
-  secrets/
+  runs/           # run bundles, screenshots, transcripts, Observer output
+  labs/           # private labs; a committed lab with the same id wins
+  local/labs/     # machine-local labs
+  local/personas/ # machine-local personas; a committed persona with the same id wins
+  cache/ tmp/ logs/
 ```
 
-Default `.gitignore` entry:
-
-```gitignore
-.humanish/
-.env*
-```
-
-If a target repo already uses `.env.example`, preserve its existing exception.
-
-## Local Overrides
-
-When a team needs private local personas or credentials, use ignored overlays:
-
-```text
-.humanish/local/personas/*.yaml
-.humanish/local/policies/*.yaml
-.humanish/local/labs/*.yaml
-.humanish/labs/*.yaml
-.humanish/secrets/*
-```
-
-Committed `humanish/labs/*.yaml` should be useful to anyone with a clean clone.
-Ignored `.humanish/labs/*.yaml` and `.humanish/local/labs/*.yaml` are for
-machine-specific or private dogfood labs. The CLI should warn that local
-overlays cannot be used for reproducible CI or public issue drafts unless
-redacted into committed synthetic equivalents.
-
-## CI And Reproducibility
-
-CI should reproduce proof from committed inputs:
-
-- app commit;
-- `humanish` version;
-- `humanish/config.ts`;
-- scenario and persona catalog;
-- lab manifest;
-- policy files;
-- synthetic fixtures;
-- declared env var names.
-
-CI should store generated run bundles as artifacts, not commit them.
-
-## Why Not `.humanish/` For Everything?
+Never commit run bundles, raw screenshots, transcripts, local overrides or
+secrets. `init` adds `.humanish/` to `.gitignore`.
 
-A fully ignored `.humanish/` makes setup feel tidy, but it hides the product
-contract. Future agents and contributors cannot see what the harness is meant
-to prove, CI cannot validate it from a clean clone, and PR review cannot catch
-weakened personas or dropped hard paths.
+## Formats
 
-A partially tracked dotdir is possible but worse UX. Dotdirs read as local,
-editors hide them, and negated gitignore rules are easy to break. A visible
-`humanish/` source root plus ignored `.humanish/` runtime root is clearer.
+- `.yaml` for human-authored source: labs, personas, scenarios.
+  Prefer `.yaml` over `.yml`.
+- `.mjs` for executable adopter scorers.
+- `.json` for generated artifacts and synthetic fixtures; `.ndjson` for
+  appendable event and transcript streams.
+- `.yml` only where an outside tool expects it, such as
+  `.github/workflows/*.yml`.