humanish 0.106.1 → 0.108.0

package/docs/architecture/participant-media.md

@@ -1,90 +0,0 @@
-# Optional participant media
-
-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.
-
-```yaml
-actors:
-  - type: local-agent
-    localAgent: codex
-execution:
-  target: local
-  desktop:
-    media:
-      camera: { source: synthetic }
-      microphone: { source: speech }
-policies:
-  mediaPermission: prompt
-```
-
-Omit `media` and `recording` for ordinary browser studies. They keep the smaller
-browser image and start no audio server, camera producer or speech worker. Camera and speech
-can also be requested separately. Local media setup uses a separately pinned
-image, prepared by the first live study or `humanish runtime setup --media`.
-
-The local camera is an animated test pattern behind a native V4L2 device. Speech
-uses a synthetic microphone and a separate speaker sink. Chromium uses its
-ordinary devices and permission dialog. `mediaPermission: granted` bypasses the
-dialog explicitly; it does not replace the devices.
-
-## Speaking and listening
-
-With speech enabled, `humanish_ui` accepts `{kind: "speak", text: "..."}` in
-addition to browser actions. It plays into the microphone; the participant must
-join and unmute through the app. Tool narration is never automatically spoken.
-Keep each utterance within 400 characters. Playback acknowledgement establishes
-local microphone input, not delivery to another caller.
-
-The desktop captures actual speaker audio. Finalized English transcriptions
-arrive as `heardSpeech` observations with an utterance ID, `speaker_audio` source
-and duration. A participant can use the existing `wait` action while listening.
-Hearing something counts as progress even when the screen stays unchanged.
-
-Transcription and synthetic speech run inside the Linux desktop, without a
-speech API key or a host Python installation. Codex inference still runs remotely
-using the selected account. The first voice uses espeak-ng and sounds robotic;
-whisper.cpp uses the pinned English `base.en` model for recognition. This is bounded turn-taking, with recognition
-latency and possible transcription errors, not a streaming voice conversation
-with interruption handling.
-
-Spoken text and heard observations pass through the existing evidence redaction
-before being retained in the trace. Analysis reads that evidence alongside screenshots and actions; it does not
-inspect raw audio or video. Raw audio is not saved by default. [Optional desktop recording](desktop-recording.md)
-can retain actual screen and audio playback alongside this evidence.
-
-## Hosted desktops
-
-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](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.
-
-Existing hosted synthetic cameras use Chromium's fake-device flags. Those flags
-also replace its microphone, so hosted camera and speech cannot currently be
-combined. Use a local native-media desktop for both, or a hosted audio-only
-study. Microphone files and speech through other participant providers are not
-supported. A template alone cannot add camera support to a kernel without V4L2.
-
-## Runtime maintenance
-
-`runtime/local-firecracker/build.py --media` extends the maintained browser image
-with native devices and the speech worker. The published media image must carry
-`to.humanish.runtime.media=1`; a cached browser image cannot satisfy a media
-request. Source builds can select an already-built media image with
-`HUMANISH_LOCAL_MEDIA_RUNTIME_IMAGE`.
-
-The media worker owns its subprocesses and buffers. Failed speech recognition,
-worker exit and queue overflow stop the media session instead of appearing as
-successful silence. Closing the desktop stops media and reclaims its isolated
-state. No conferencing vendor or room-specific behavior is implemented in core.
-
-Retain the matching media sources and package notices when publishing runtime
-assets. Pass `--media-browser` and `--media-inputs` to the existing
-`runtime/local-firecracker/sources.py` collector alongside its ordinary inputs.
-Hardware capacity and conferencing topology require their own measured proof;
-requesting media does not qualify twenty concurrent participants or TURN.

package/docs/architecture/project-layout.md

@@ -1,62 +0,0 @@
-# Project Layout
-
-`humanish init` gives a project two roots:
-
-```text
-humanish/   # committed lab source
-.humanish/  # ignored runtime state, evidence and local overrides
-```
-
-## Committed lab source: `humanish/`
-
-`init` writes:
-
-```text
-humanish/
-  README.md
-  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
-  coverage-map.md
-  coverage-matrix.md
-```
-
-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`.
-
-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.
-
-## Ignored runtime state: `.humanish/`
-
-```text
-.humanish/
-  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/
-```
-
-Never commit run bundles, raw screenshots, transcripts, local overrides or
-secrets. `init` adds `.humanish/` to `.gitignore`.
-
-## Formats
-
-- `.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`.

package/docs/architecture/real-email-receiving.md

@@ -1,136 +0,0 @@
-# Real email receiving
-
-A supported browser study can give each participant a fresh AgentMail inbox. The
-application sends real email to that address; humanish polls it on the host and
-publishes a private inbox surface on that participant's desktop. The participant
-can read the original email, switch to a plain view and follow an approved link.
-
-Use local capture when you can redirect the app's send configuration and want to
-avoid hosted mail. Use real receiving when the app must send normally or delivery
-itself is part of the flow. These are separate modes; do not combine their settings.
-SMS and participant outbound mail are not supported.
-
-## Setup
-
-Open `humanish tui`, press **c** for Connections, and choose **Add API key** to add an
-AgentMail key. Hidden entry saves it in the existing user key store and checks
-authentication without creating an inbox; Ctrl+C cancels entry and returns to the TUI.
-The project profile, `.humanish/local/comms.yaml`, stores only the provider and
-environment-variable name.
-Environment and explicit env-file values retain precedence over saved keys.
-A rejected or unavailable authentication check does not delete the saved key.
-Authentication does not prove inbox creation/deletion permissions, quota or delivery.
-This release requires an organization-scoped key.
-
-Connections can preview and save a receiving-enabled local lab copy. The preview
-discloses hosted email, model processing, local review and separate provider charges.
-The original manifest is preserved. Select the new exact path when launching.
-
-The same operations are available to agents:
-
-```bash
-humanish keys set agentmail
-humanish comms connections add agentmail --json
-humanish comms check --online --json
-humanish comms configure --lab humanish/labs/signup.yaml --json
-# Review the returned path, disclosures and planToken, then:
-humanish comms configure --lab humanish/labs/signup.yaml --apply --plan-token <digest> --json
-humanish lab run .humanish/local/labs/signup-receiving.yaml --json --no-open
-```
-
-Direct manifest authoring selects a saved connection:
-
-```yaml
-comms:
-  email:
-    connection: agentmail
-    # Optional: additional trusted email-link destinations, exact origins only.
-    allowedOrigins:
-      - https://accounts.example.test
-```
-
-The target origin is automatically allowed. On provisioned subjects, the declared
-serve origin and optional `linkOrigin` use the existing target-origin rewrite.
-Review additional origins as destinations the participant is allowed to open from
-mail. This policy governs the inbox surface, not all later browser navigation.
-
-Supported execution is hosted computer use with app-url, clone or local-tree
-subjects, including shared-world studies. Local-agent, scripted, terminal, desktop-cli, in-process and local-app routes reject
-real receiving before allocation. Connection mode cannot declare capture options,
-recipients or borrowed mailbox IDs. A fresh address is not an existing account;
-assignments must allow signup or arranging mail to the new identity.
-
-## What a run does
-
-1. Resolve the selected connection and host credential. Reject forwarding that
-   management credential through target environment names, aliases or literals.
-2. Authenticate and durably record each acquisition intent in private host state.
-   Acquire all participant addresses before starting desktops.
-3. Give each participant its address and loopback inbox URL. No management key or
-   other participant's mailbox is installed in its desktop. Each surface has only
-   its own list/message/plain/JSON routes, with no send endpoint or aggregate inbox.
-4. Poll received mail, register scrub targets, sanitize/render and atomically
-   publish the complete inbox snapshot. Repeated reads can fill temporarily missing
-   bodies and inline images without changing local message identity.
-5. Before desktop teardown, perform a bounded final read, save evidence, stop the
-   inbox surface and request deletion. Confirm provider absence; otherwise retain
-   unresolved cleanup for recovery. Provider deletion is not an erasure guarantee.
-
-The original view preserves supported email structure and inline PNG/JPEG/GIF/WebP
-images. Parsed HTML removes active content; response CSP blocks scripts, forms,
-frames and remote assets. Remote images show an explicit unavailable placeholder.
-Links use the same origin policy in original, plain and JSON views. Attachment
-bytes are fetched only through the fixed provider API and its observed CDN host;
-provider authorization never goes to the CDN. General attachments, arbitrary remote
-images and raw-MIME fallback are unsupported. Raster checks are bounded signature
-checks, not a guarantee that every malformed image will decode in a browser.
-
-Collection is bounded by request time, request/page count, bytes, images and a
-100-message retained inbox limit. Limits, failed reads, blocked content and failed
-publication are recorded as coverage limitations. Inbox pages require reload to
-show later messages. No webhook/public mail ingress is required on the host.
-
-## Evidence and publication
-
-`comms/receiving.json` uses `humanish.comms-receiving.v2`. It records local IDs,
-counts, timestamps and lifecycle/coverage status, without raw mail, provider IDs,
-addresses or stable content digests. The final run bundle embeds that projection.
-Receipt, successful inbox publication, participant reading and target success are
-separate claims; analysis receives this distinction and the harness limitations.
-A missing message alone does not establish that the application failed to send.
-Immediate automatic analysis scrubs known exact values from generated narration
-using a bounded, invocation-local registry. It never saves that registry. Later
-analysis cannot reconstruct it; screenshots may still expose mail content, and the
-publication restriction applies to both immediate and later findings.
-
-Mail is hosted by AgentMail. Its content can reach the hosted desktop, actor model,
-screenshots, narration and analysis model. Such runs carry a durable
-`real-communications` publication restriction: verification returns `local_only`,
-public feedback/exposure and shareable exports remain gated, and screenshot
-blurring does not clear the restriction. Local Observer review and explicitly local
-HTML export remain available. Local-only publication is not local-only processing.
-
-## Interrupted-run recovery
-
-Process interruption can bypass normal final reads and teardown. Inspect recovery
-state after stopping a run; do not assume Ctrl+C or killing a process deleted its
-inboxes:
-
-```bash
-humanish comms recover --json
-humanish comms recover --run <run-id> --apply --json
-```
-
-Connections also exposes pending cleanup. Recovery only uses private host journals
-under `$XDG_STATE_HOME/humanish/comms` (default `~/.local/state/humanish/comms`),
-with private directories/files and bound project, connection, account and scope.
-A live or unknown owner blocks takeover. The adapter checks resource/client identity
-before deletion; it cannot delete an inbox named only in a run artifact. Lost
-creation responses can be reconciled through the recorded idempotent client ID.
-Do not delete private journals while resources remain unresolved. Moving/replacing
-the project or changing account/scope can intentionally prevent recovery.
-
-If final evidence persistence fails, the provider inbox is retained as unresolved
-rather than discarding the last retrievable copy. Explicit recovery is a deletion
-operation, not message-history reconstruction. Sandbox reclamation remains a
-separate operation.

package/docs/goals/current.md

@@ -1,207 +0,0 @@
-# Current Goals
-
-This page guides work on current source. [CHANGELOG.md](../../CHANGELOG.md) lists what each
-version changed.
-The [September 9 history](https://github.com/danielgwilson/humanish/blob/main/docs/goals/current-history-2026-09-09.md)
-preserves the former status log; its queues do not supersede this page.
-
-## North Star
-
-Humanish should let a maintainer ask:
-
-> What happens when synthetic personas try to use this app, CLI, or
-> agent-facing workflow?
-
-The answer should be observable, verifiable, public-safe, and useful for
-making a repair. The working loop is:
-
-```text
-study → recorded evidence → verify → feedback → repair → comparable rerun
-```
-
-The run bundle is the source of truth; Observer is its review surface. Keep
-product-specific tasks, state checks and vocabulary in adapters, with generic
-execution, evidence and lifecycle primitives in core.
-
-## The Three Roles
-
-Check changes against the [researcher, stakeholder and participant](../principles/three-roles.md):
-
-- The researcher declares the study, tasks, hidden success criteria, panel and
-  budgets. Supported routes return observation-backed task outcomes.
-- The stakeholder needs inspectable moments, findings and denominators, with
-  evidence quality separate from participant success.
-- The participant receives a goal and behavioral constraints. They may finish,
-  abandon, encounter a blocker or be interrupted; these outcomes must remain
-  distinct from failures of the harness.
-
-A participant does not see their hidden success criteria. Missing observation
-inputs remain unmeasured. Provider and session limits are safeguards, and a
-limit ending a session must not be presented as natural completion.
-
-## Best Next Work
-
-An independent maintainer uses the published package on their own app,
-adjudicates a useful finding, makes a repair and retains a comparable rerun.
-Voluntary repeat use is the next adoption signal to establish.
-
-Measure the effort and decisions in that loop:
-
-- setup effort and interventions needed to obtain a usable recording;
-- findings confirmed, dismissed or left uncertain after evidence review;
-- accepted repair decisions and the results of comparable reruns;
-- whether the maintainer chooses to use Humanish again.
-
-Prioritize work that changes one of those outcomes. Fix a reproduced first-use
-failure or evidence-review obstacle before expanding the platform. Use actual
-recordings to check whether people can identify what happened, find the
-relevant capture and understand the limits of the evidence.
-
-The [own-app guide](https://humanish.dev/docs/your-app) and
-[TodoMVC repair study](https://humanish.dev/docs/todomvc-edit-study) provide
-starting points. Named public applications in study receipts are subjects,
-not adopters or endorsements. An invitation is not activation.
-
-## What The Evidence Establishes
-
-- A keyless `first-run` is a contract and review preview. It does not establish
-  live execution, app findings or independent use.
-- Kept live studies establish the behavior observed on their named subjects,
-  versions, tasks and actors. Preserve interruptions and unsuccessful attempts
-  alongside successful ones.
-- The [TodoMVC repair comparison](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/todomvc-edit-confirmation-2026-09-05.md)
-  supports one synthetic keyboard repair result; it does not estimate human
-  completion rates or general defect recall.
-- The [evidence/export workflow receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/redacted-evidence-workflow-2026-09-07.md)
-  establishes readable originals and verified shareable derivatives on retained
-  runs. External maintainer acceptance remains a separate gate.
-- Explicit keyboard/pointer contrasts do not isolate the value of rich persona
-  prompting. Matched comparisons need the same tasks, model, budgets and source
-  conditions, with validated findings and adjudication effort measured. See
-  [actor fidelity](../principles/actor-fidelity.md) for claim boundaries.
-
-Capability proof also differs from replacing an adopter's bespoke harness.
-The [proof roadmap](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/README.md)
-requires decision-equivalent retained evidence and a real deletion branch.
-No first-party deletion branch has met that gate. Public demonstrations do not
-substitute for it.
-
-## Current Program Truth
-
-| Surface               | Available in source                                                                                                                                                                                                                                                                                                                  | Remaining boundary                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Study authoring       | YAML labs, `lanes[]`/roster composition, model settings and study/per-participant caps                                                                                                                                                                                                                                               | Route support varies; declarations are not promises of engine parity                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Actors                | Seven first-party descriptors; computer-use, scripted-browser and terminal-product dispatch                                                                                                                                                                                                                                          | No supported public out-of-tree actor-registration API                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Subjects              | `this-repo`, `clone`, `app-url`, `local-app`, `terminal-product`, `desktop-cli`, `local-tree`                                                                                                                                                                                                                                        | `this-repo` is dry-run-only; `local-app` needs a caller-supplied executor/provider                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Task protocol         | Hidden criteria and per-task outcomes on supported separate-world CUA paths, including local-agent and desktop-cli                                                                                                                                                                                                                   | Shared-world, terminal-product, scripted and synthetic routes reject `tasks` before execution                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Shared state          | Concurrent single-origin shared-world studies with retained evidence (the sequential route was removed in 0.106.0)                                                                                                                                                                                                                   | Multi-origin implementation remains gated; concurrent state change does not establish per-action causation                                                                                                                                                                                                                                                                                                                                                                                     |
-| Observer              | Live/recorded views, shared grid and participant playback, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review                                                                                                                                                                    | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment                                                                                                                                                                                                                                                                                                                                                                                     |
-| Review and feedback   | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels                                                                                                                                                                                                           | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication                                                                                                                                                                                                                                                                                                                                                                                 |
-| Study findings        | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links; explicit restricted Codex account analysis on qualified Linux x64 and Apple Silicon Mac profiles | Account dollars/output-token caps are unavailable; Keychain/other CLI profiles are unqualified. Model interpretation needs review; selection limits coverage; opening Observer never dispatches analysis                                                                                                                                                                                                                                                                                       |
-| TUI and serving       | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail setup, authentication and lab configuration                                                                                                                                                                             | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups                                                                                                                                                                                                                                                                                                                                                                                |
-| Off-app communication | Recipient-scoped local capture and fresh real AgentMail receiving, supported inline raster images, bounded collection and host-owned recovery                                                                                                                                                                                        | Real mail uses isolated participant surfaces and remains local-only for publication. Hosted mail/model processing, bounded fidelity and interrupted-run recovery are explicit; real receiving through local-agent, borrowed inboxes and SMS are unsupported                                                                                                                                                                                                                                    |
-| Local browsers        | Shared study loop on Linux x64/Docker/KVM and M3-or-newer Mac/Lima; pinned runtime download, Codex account participants and automatic analysis                                                                                                                                                                                       | Explicit local labs support recipient-scoped captured inboxes; real receiving on local desktops, automatic onboarding, larger cohorts and sleep/wake remain unqualified                                                                                                                                                                                                                                                                                                                        |
-| Mobile and media      | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed; optional camera and speech passed two-person Linux and Mac conversations with validated analysis; hosted audio-only uses the same worker; optional screen/mixed-audio MP4 capture shipped with Linux/E2B and Mac acceptance              | Hosted camera+speech is unsupported; English recognition and robotic voice have fidelity limits; raw AV recording is shipped but local-only, excluded from HTML export and analysis (screenshots/text only); the reproduced recording-mix startup video gap is corrected; variable guest capture stalls, initial device/transport availability and cold audio-source delivery remain limits (#854); forced TURN, larger-cohort capacity, physical-device and touch fidelity remain unqualified |
-
-Use the [task support matrix](../architecture/task-protocol-support.md),
-[actor registry](https://github.com/danielgwilson/humanish/blob/main/src/actors/registry.ts)
-and [CLI reference](https://humanish.dev/docs/cli) when choosing a concrete path.
-Source and tests establish observed behavior. Resolve conflicts with requirements
-explicitly; neither stale status prose nor a passing test makes a bug correct.
-
-The library-assisted `local-app` route now includes a
-[runnable npm example](../../examples/participant/README.md).
-Its deterministic provider demonstrates the integration with a real loopback
-app; it does not establish persona effectiveness or independent adoption.
-
-The [local browser runtime](../architecture/local-browser-runtime.md)
-runs isolated Linux browser participants through the same scheduler, recordings
-and automatic analysis as hosted studies. It uses Docker-owned resources and
-ordinary TAP/NAT networking. Continue managed-local work from this complete study
-path. Explicit
-Linux local labs now use the installed CLI/TUI, with a verified runtime download
-before the first live run. Mac browser support is also shipped. Captured inbox integration reuses the existing
-catch and evidence contracts; local provider-backed receiving remains unsupported.
-Optional media passed Linux and Mac conversations with receiving-side evidence
-and owned-resource cleanup. The original Mac recording produced validated
-analysis after its citation instructions were clarified. Existing hosted labs
-retain their behavior.
-
-## Gates And Deferred Work
-
-- [Multi-origin shared-world work](https://github.com/danielgwilson/humanish/issues/239)
-  needs a real adopter's cross-origin requirement and a reviewed implementation
-  packet. It has a ratified core-design direction, but the implementation gate is still closed.
-- [Nested provider grants](https://github.com/danielgwilson/humanish/pull/534)
-  remain unmerged. Do not assume a nested provider-credential channel exists.
-- Paused adopter-deletion work stays paused until its current readiness and
-  maintainer decisions permit it. Do not resume it from the historical queue.
-- Broader actor/plugin APIs, additional media, registry promotion and TUI
-  expansion are follow-ups, not substitutes for a useful maintainer workflow.
-  A concrete use case and current issue readiness determine when to take them up.
-
-## Safety And Autonomous Work
-
-Follow [AGENTS.md](../../AGENTS.md), the [invariants](../principles/invariants-and-defaults.md)
-and the [public-readiness standard](../release/public-readiness-standard.md).
-
-- Keep `main` clean and work on scoped branches/worktrees. Keep the task's scope,
-  authority, relevant checks and material failure boundaries in its issue, PR or
-  current handoff; do not create a separate packet for routine work.
-- Existing explicit shipping authority governs implementation and merge;
-  otherwise issue readiness does not create authority by itself. Machine-readiness
-  fields gate automated queue pickup, not directly assigned interactive work.
-- Never commit secrets, private transcripts/screenshots, customer data or
-  private project context. Keep generated proof in ignored `.humanish/` and
-  retain needed evidence before removing a worktree.
-- Managed paths bind to validated filesystem identities. Stored provider IDs
-  are evidence, not cleanup authority; reclaim only resources the operation is
-  authorized to own, and keep unknown cleanup explicitly unresolved.
-- Verification distinguishes `share_ready`, `local_only` and `blocked`.
-  Feedback drafts do not mutate GitHub by default. Live spend, publishing,
-  external mutation and broader credential access are explicit choices.
-- Provider credential placement is route-specific. The computer-use model key stays
-  on the host; the default terminal runtime uses command-scoped credentials. Do not infer safety from an unqualified “keys stay outside” claim.
-
-## Proof Before Shipping
-
-Use the [verification guidance](../principles/engineering.md#verification): check the changed
-behavior and material risks, then stop unless new evidence warrants more work.
-Required CI remains the merge gate. For a release, run the full release gates
-from a clean contributor worktree:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm release:check
-pnpm docs:check
-git diff --check
-```
-
-For Observer changes, build before its tests and inspect real bundle data at
-390px and desktop width. Run `pnpm --filter humanish-observer test` and
-`pnpm observer:browser:proof`; preserve the source and limits of each receipt.
-For website changes, run site typecheck, build and `registry:check`.
-Required CI remains the merge gate.
-
-Before a release, follow the [release procedure](../release/open-source-readiness.md),
-including the candidate-package `pnpm release:dogfood` study with authorized
-credentials and bounded paid spend. A successful build alone is not participant
-proof. Verify the published package and any changed publishing surface.
-
-A disposable, keyless consumer check is:
-
-```bash
-npm i -D humanish
-npx humanish init --yes
-npx humanish run first-run --json
-npx humanish verify --run latest --json
-npx humanish feedback issue --run latest --repo owner/repo --format markdown
-```
-
-This checks installation, preview evidence and feedback generation. A live
-claim needs actual participant execution, retained evidence and verified
-cleanup. Use N > 1 where the claim needs replication; report cost estimates,
-unknowns and failures without turning them into zeros or successes.
-
-Start from the [ramp](../ramp/README.md), choose one changed user outcome, and
-close work with what changed, what was checked and what remains uncertain.

package/docs/product/lobby-trivia-3player-external-public.md

@@ -1,77 +0,0 @@
-# Example: 3 mobile personas share ONE public multiplayer lobby at once
-
-`humanish/labs/lobby-trivia-3player.yaml` is a worked example of the EXTERNAL-PUBLIC shared-world route
-(#164 phase 2): three mobile-LAYOUT personas play the SAME multiplayer lobby on a REAL public
-deployment simultaneously, watched in ONE Observer. Point `subject.appUrl` + `subject.publicTarget` at
-a public deployment YOU own/operate.
-
-## What it does
-
-- The public site is the shared plane DIRECTLY: no clone, no getHost, no subject sandbox, no seed.
-- A host-first barrier: the `host: true` participant creates the lobby; the orchestrator reads the
-  `/lobby/CODE` from the host's CDP-observed URL and threads it into the follower Join missions.
-  Followers go through the real Join flow (a direct `/lobby/CODE` visit does not auto-join a
-  non-member).
-- Convergence (all three participants reaching one `/lobby/CODE`) is the pass signal (a digest-only
-  `lobbyConvergenceDigest`), plus temporal co-occupancy of the three participants' windows.
-
-## Mobile fidelity caveat (read before over-reading the results)
-
-The participants are `device: mobile` (414×896) and `device: small-mobile` (360×740). On the E2B-desktop
-route the rendered WIDTH is floored to `MIN_DESKTOP_RENDER_WIDTH` (500): Chrome refuses a window
-narrower than ~500 CSS px, and a narrower X screen let the window overflow and clip the page
-(0.20.3, #304). So both presets render at **500 wide**, `mobile` and `small-mobile` are identical in
-layout on this route, and this example does NOT currently exercise two different mobile widths. Only
-the HEIGHT renders as declared (896 and 740).
-
-Note that `desktopGeometry.screen.verified` checks the FLOORED number against itself, so a matching
-`verified` block is not evidence that the preset width rendered. Read `requested` against the preset
-in `device-presets.ts` if you need to know.
-
-There is NO touch input, and isMobile/DPR are prompt-signal + metadata (DPR renders only via the CDP
-geometry path). So "3 mobile personas" means 3 mobile-LAYOUT desktop-Chromium participants, NOT touch
-devices. If a flow needs true touch/tap semantics, these participants will not exercise it. True sub-500
-CSS-viewport rendering is the #221 CDP-device-emulation upgrade.
-
-## Run it
-
-Dry-run (the default, $0; proves the plumbing + the honesty contract, with no sandboxes and no tokens):
-
-```
-humanish lab run lobby-trivia-3player          # or: humanish watch lobby-trivia-3player
-```
-
-Live (opens 3 real mobile-layout participants against the public app):
-
-```
-# flip scenario.mode to live in the lab (or override), then:
-humanish watch lobby-trivia-3player --env-file .env.local   # OPENAI_API_KEY + E2B_API_KEY
-```
-
-Watch it from a phone (today): serve the run directory's Observer through an authed edge:
-
-```
-humanish serve --expose --tunnel <provider> --oauth <provider> --allow-emails you@example.com
-```
-
-Native live-desktop `--expose` streaming on the concurrent path (watch the 3 live desktops as well as
-the evolving Observer artifacts) is a 0.20.1 fast-follow.
-
-## Honesty
-
-This is a real public-application study of a deployment the operator attests they own/operate
-(`subject.publicTarget: { owner, authorized: true }`; this is author trust, which the harness cannot
-verify).
-Attribution stays `shared-world` (N participants, ONE plane), but every strength claim degrades honestly and
-is asserted-absent by verify: provenance `external-public` (not seeded); NO synthetic attestation (you
-cannot claim synthetic on a real site); plane control is operator-attested, not harness-controlled; NO
-authoritative shared-state proof; concurrency by temporal co-occupancy + observed lobby convergence.
-No one run implies adoption, scale, or repeatability.
-
-## Before a live run against a third-party site
-
-The verified lobby-trivia lobby mechanics (createLobby/joinLobby → `/lobby/CODE`, the 6-char
-`ABCDEFGHJKLMNPQRSTUVWXYZ23456789` alphabet, non-auto-join on a direct visit) are read from current
-source and could change on the next deploy. The two coupling points to re-verify are the lobby-code
-regex (`/\/lobby\/([A-Z2-9]{6})(?:$|[/?#])/`, tolerant of a locale prefix and query/hash) and the
-follower Join-flow mission wording.