humanish 0.107.0 → 0.109.0

package/docs/architecture/observer.md

@@ -1,13 +1,8 @@
 # Observer Architecture
 
-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 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
-proof.
+The Observer renders synthetic streams and saved live browser, terminal-product, fan-out and
+shared-world evidence. A computer-use or shared-world run can publish its in-progress bundle to an
+attached loopback Observer without saving runtime stream-auth URLs.
 
 ## Decision
 
@@ -80,7 +75,7 @@ forwarding, and only contained run paths in the TUI's project are accepted.
 | `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   |
+| `observe --all`          | 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
@@ -103,7 +98,7 @@ 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.
 
-Watch is deliberately distinct from `humanish serve`. Watch serves ONE
+Watch is deliberately distinct from `humanish observe --all`. 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
@@ -123,23 +118,23 @@ Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
 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
+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. 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
+`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 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, 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
+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
-to Ctrl-C. `serve` still never injects stream URLs. See
+to Ctrl-C. `observe --all` still never injects stream URLs. See
 [Serve: the run library surface](serve.md).
 
 ### Live desktop iframe authority
@@ -178,8 +173,9 @@ between an active study and its provisional evidence outcome.
 
 ## UI Shape
 
-See [Watching and reviewing evidence](observer-review.md) for current controls,
-entry-point capabilities, timing limits and browser acceptance commands.
+[Watch and review in the Observer](https://humanish.dev/docs/review-surfaces#watch-and-review-in-the-observer)
+describes the current controls, entry points and timing limits for users;
+[Browser checks](#browser-checks) below covers the proofs that pin them.
 
 The Observer shell has:
 
@@ -198,7 +194,7 @@ the frozen Observer data schema or start provider requests. Analysis polling has
 an independent lifecycle, so a delayed companion does not stall recording updates.
 Invalid or stale interpretation never overwrites original participant outcomes.
 Recording navigation retains its originating view, and nonvisual citations open
-the source event rather than inventing a playback frame.
+the source event with no invented 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;
@@ -230,29 +226,16 @@ A host adapter may provide:
 If no embed URL exists, the Observer still renders the Codex-style timeline and
 session contract instead of failing the stream.
 
-## Historical slice and remaining gaps
-
-The original 2026-06-01 slice implemented the Observer substrate and synthetic
-stream contracts; local `codex-exec` active-run snapshots followed.
-
-Subsequent additions through 2026-06-11 included:
+## Remaining gaps
 
-- Playwright-backed browser proof with scripted, app-specific
-  `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/routes/computer-use/participant-execution.ts` writes them).
-
-Intentionally still adapter work:
+These remain adapter work:
 
 - local PTY capture;
 - Codex TUI live follow after workspace trust bootstrap;
 - richer screenshot/trace galleries across multi-step product journeys;
 - reviewer acceptance gates over real product behavior.
 
-## The rendering layer (#426, cut over 2026-08-16)
+## The rendering layer
 
 The renderer is the `observer/` workspace: a Vite single-file build on the
 `@humanish` registry tokens, frozen against `humanish.observer-data.v1`
@@ -260,10 +243,27 @@ The renderer is the `observer/` workspace: a Vite single-file build on the
 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 function every surface (observe, watch, serve, labs) renders through,
+the one function every surface (observe, observe --all, watch, studies) 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).
+
+## Browser checks
+
+`pnpm observer:browser:proof` exercises generated synthetic evidence in the
+production artifact. `pnpm observer:iframe:proof`, after `pnpm build`, checks the
+actual serving boundary against direct, redirected and scripted iframe attacks.
+CI retains their screenshots and JSON receipts. These Chromium checks do not
+claim physical-device or non-Chromium coverage. Actual provider checks and their
+resource-cleanup receipts are separate acceptance evidence.
+
+Interaction references rechecked September 8, 2026:
+[Base UI popover](https://base-ui.com/react/components/popover),
+[React state structure](https://react.dev/learn/choosing-the-state-structure),
+[WAI-ARIA tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/),
+[iframe sandboxing](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe),
+[Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer), and
+[PostHog recording controls](https://posthog.com/docs/session-replay/how-to-watch-recordings).

package/docs/architecture/restricted-codex-analysis.md

@@ -5,24 +5,28 @@ execution, with a separate conversation, process and tool authority. It can use
 the same host Codex login as a local-agent participant. Existing API analysis
 remains a separate provider.
 
-The qualified launcher profile is **a qualified Codex CLI release for the host, Linux x64
-or Apple Silicon macOS, file-backed ChatGPT login, `gpt-6-astra`, low reasoning effort**.
-Qualified releases are listed per host in
-[`src/actors/codex/qualified-versions.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/qualified-versions.ts).
-Linux x64 accepts 0.154.0, 0.157.1
-([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.157.1-requalification-2026-09-30.md))
+The launcher profile is **a stable Codex CLI release from 0.154.0 on, Linux x64 or Apple
+Silicon macOS, file-backed ChatGPT login, `gpt-6-astra`, low reasoning effort**.
+[`src/actors/codex/codex-admission.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/codex-admission.ts)
+admits every stable `MAJOR.MINOR.PATCH` release from 0.154.0, the oldest known to work, except
+those in `REFUSED_CODEX_CLI_VERSIONS` (none yet). There is no ceiling: a new release runs the
+day it ships, and one that breaks humanish is refused there until humanish handles it.
+Prereleases and older releases are refused, and the refusal names the release and why. Hosted
+participants (operator mode) run the same releases on Linux x64 and arm64 and macOS x64 and
+arm64; a hosted run on a release outside `TESTED_CODEX_CLI_VERSIONS` records a warning that its
+evidence rests on the checks each launch makes. `TESTED_CODEX_CLI_VERSIONS` gates nothing. It
+lists the releases the qualifier passed on Linux x64, and its newest is the default and the
+install target: 0.154.0, 0.157.1
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.157.1-requalification-2026-09-30.md))
 0.159.2
-([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.159.2-qualification-2026-09-30.md))
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.159.2-qualification-2026-09-30.md))
 0.159.3
-([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.159.3-qualification-2026-10-01.md))
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.159.3-qualification-2026-10-01.md))
 and 0.160.0
-([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.160.0-qualification-2026-10-01.md)).
-Apple Silicon accepts 0.154.0, which passed installed participant/analysis studies and the
-native dispatch restriction check on an M5 Max; later releases need the same check on a Mac.
-Hosted participants on Linux arm64 and Intel macOS keep 0.154.0 as a pre-existing admission,
-listed separately in `PREEXISTING_CODEX_CLI_ADMISSIONS`: it is what they ran before per-host
-lists existed, not a qualification, and no later release is admitted there. Other releases and
-platforms, keychain-only logins and API-key Codex logins are refused before a model turn.
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.160.0-qualification-2026-10-01.md)).
+On Apple Silicon, 0.154.0 passed installed participant/analysis studies and the native dispatch
+restriction check on an M5 Max; no later release has run on a Mac. Other platforms,
+keychain-only logins and API-key Codex logins are refused before a model turn.
 
 A release string is a compatibility check, not binary attestation. The launcher compares the
 release that `codex --version`, initialize and thread start report, then executes the same
@@ -30,8 +34,8 @@ path; it does not pin the executable's contents, and a modified binary can repor
 The launcher records the detected release in the participant execution profile and in the
 analysis identity. A recorded release alone is not execution proof: prelaunch and failed
 attempts can carry the declared default, and a request's `dispatched` and `profileVerified`
-receipt shows that the launched release passed its checks. Saved bundles naming any recorded
-release stay readable.
+receipt shows that the launched release passed its checks. Saved bundles naming any stable
+release from 0.154.0 on stay readable, whether or not a launch list names it.
 Readiness validates the installation and effective profile without submitting a
 model turn; it does not guarantee current quota or model access.
 
@@ -159,10 +163,11 @@ not established by that proof. Recovery deliberately fails closed if storage
 behaves differently. Keychain/other-platform support and whole-process-tree
 leases require their own qualification.
 
-## Admitting a Codex CLI release
+## Testing a Codex CLI release
 
-A release enters a host's list only with a dated receipt under
-`docs/goals/computer-use-actor/receipts/` showing all of the following, on that host:
+Admission does not wait for a test. A release enters `TESTED_CODEX_CLI_VERSIONS`, which gates
+nothing, with a dated receipt under `docs/evidence/computer-use/` showing all of
+the following, on Linux x64:
 
 1. The release notes since the baseline were read for changes near the tool boundary.
 2. A drift check against a release already qualified on the host found no exec, connection or
@@ -170,27 +175,28 @@ A release enters a host's list only with a dated receipt under
    launches, and the same tool inventory, denials and isolate behavior. `pnpm codex:qualify`
    runs this check; see "The qualifier" below.
 3. One hosted participant study with the candidate first on `PATH` (for example
-   `PATH=<evidence>/npm-<version>/node_modules/.bin:$PATH pnpm humanish lab run <lab>
+   `PATH=<evidence>/npm-<version>/node_modules/.bin:$PATH pnpm humanish run <study>
 --env-file <file with E2B_API_KEY only>`) reached its goal in the final capture, with a
    verified request receipt, `humanish verify --run <id>` passing and the automatic Codex
    analysis recording the release. Keep `OPENAI_API_KEY` out of that environment so the
    participant stays on ChatGPT-account billing.
 
 The drift check compares a candidate with a vendor release that has already been qualified. It
-can show that an honest new release does nothing new in those scenarios; it cannot show that a
+can show that a benign new release does nothing new in those scenarios; it cannot show that a
 binary built to evade it is safe. Pair that with the attestation limit above: the launcher
 admits by release string and does not pin the executable.
 
-Then commit the release in `QUALIFIED_CODEX_CLI_VERSIONS`
-(`src/actors/codex/qualified-versions.ts`) for that host, in `RECORDED_CODEX_CLI_VERSIONS`
-(`src/actors/contract.ts`) and in the Observer's copy
-(`observer/lib/actor-execution-profile.ts`). If any check fails, change no code and record
-what differs.
+Then commit the release in `TESTED_CODEX_CLI_VERSIONS` (`src/actors/codex/codex-admission.ts`);
+launch admission does not change. Readers need no change: saved
+profiles may name any stable release from `RECORDED_CODEX_CLI_FLOOR` (0.154.0) on, in
+`src/actors/contract.ts` and the Observer's copy (`observer/lib/actor-execution-profile.ts`).
+If any check fails, record what differs; a release that breaks humanish goes in
+`REFUSED_CODEX_CLI_VERSIONS` with its issue.
 
 ### The qualifier
 
 `pnpm codex:qualify` produces the drift evidence step 2 above requires. Its threat model:
-it detects an honest new vendor release that, in these scenarios, executes a program, connects
+it detects a benign new vendor release that, in these scenarios, executes a program, connects
 to a destination or writes a file the baseline release did not, and it fails closed when the
 harness cannot see (a failed trace, sampler read or parse). A binary built to evade it is out of
 scope. Named limits, none of which it inspects:

package/docs/architecture/serve.md

@@ -1,33 +1,28 @@
 # Serve: the run library surface
 
-Date: 2026-08-02
-
-Status: shipped. The `loopback`, `exposed` (edge-authed) and `share-safe-open`
-modes live in `src/observer/serve.ts`, `src/observer/library.ts`,
-`src/observer/http.ts`, `src/observer/exposure.ts` and `src/observer/tunnel.ts`,
-with per-run routes and the history index in `src/observer/run-routes.ts` and the
-loopback bind in `src/observer/listen.ts`. The CLI wiring is in
+The `loopback`, `exposed` (edge-authed) and `share-safe-open` modes live in
+`src/observer/serve.ts`, `src/observer/library.ts`, `src/observer/http.ts`,
+`src/observer/exposure.ts` and `src/observer/tunnel.ts`, with per-run routes and the history
+index in `src/observer/run-routes.ts` and the loopback bind in `src/observer/listen.ts`. The CLI wiring is in
 `src/cli/commands/observe.ts`. The `/_humanish/api/*` control-plane namespace is
 reserved and answers `501`; no mutating route ships.
 
-Exposure auth is **tunnel-edge only**. As of 0.18.0 humanish carries NO
-in-process auth: the hand-rolled capability-link (cookie/token/TTL, its auth
-module and the `serve --auth link|none` flags) was removed as
-a pre-1.0 breaking change. The gate now lives entirely at the edge: ngrok
-`--oauth google` (with `--allow-email`/`--allow-domain` allow rules), or an
-operator-secured `--public-url` (Cloudflare Access, Tailscale, a reverse proxy
-you own).
+Exposure auth happens only at the tunnel edge. humanish has had no in-process auth since 0.18.0,
+which removed the capability link (cookie, token and TTL), its auth module and the
+`serve --auth link|none` flags. The gate is ngrok `--oauth google` with `--allow-email` or
+`--allow-domain` rules, or an operator-secured `--public-url` (Cloudflare Access, Tailscale or a
+reverse proxy you own).
 
 ## What serve is
 
-`humanish serve` is the third observer surface, and the first whose subject is
-the LIBRARY rather than a run:
+`humanish observe --all` is the third observer surface, and the first whose subject is
+the library rather than a run:
 
 - `humanish watch` serves one attached run: the process that created the run
   serves it and may inject runtime stream URLs for live following (see the
   stream-URL rules below and `watch --expose`);
 - `humanish observe` re-serves one finished run read-only;
-- `humanish serve` serves the whole local library under `.humanish/runs/`: a
+- `humanish observe --all` serves the whole local library under `.humanish/runs/`: a
   library index, per-run Observer pages, `/_humanish/history.json` polling, and
   optional edge-authenticated exposure beyond the machine.
 
@@ -39,11 +34,11 @@ authenticated edge (or `--safe`, see the fail-closed matrix).
 ## Fail-closed exposure matrix
 
 One shared validator (`validateExposure` in `src/observer/exposure.ts`) governs
-both `serve` and `watch`. `--expose` must always resolve to a reachable public
+both `observe --all` and `watch`. `--expose` must always resolve to a reachable public
 origin (a `--tunnel` or a `--public-url`), even under `--safe`, since an
 origin-less exposed server is an unreachable loopback no-op. With an origin
-present, exposure requires EITHER edge auth (`--oauth` on the ngrok edge, or a
-`--public-url` you secure) OR `--safe` (share_ready runs only). A tunnel with
+present, exposure requires either edge auth (`--oauth` on the ngrok edge, or a
+`--public-url` you secure) or `--safe` (share_ready runs only). A tunnel with
 neither is a wide-open public URL to local bundles and is refused.
 
 | `--expose` | `--tunnel` | `--oauth` | `--public-url` | `--safe` | Outcome                                                                                       |
@@ -51,11 +46,11 @@ neither is a wide-open public URL to local bundles and is refused.
 | no         | no         | no        | no             | any      | `loopback` (no exposure)                                                                      |
 | yes        | yes        | yes       | no             | any      | OK → `exposed` (edge-authed; all runs unless `--safe`)                                        |
 | yes        | yes        | no        | no             | yes      | OK → `share-safe-open` (public, share_ready only)                                             |
-| yes        | yes        | no        | no             | no       | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`                                |
+| yes        | yes        | no        | no             | no       | **refused** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`                                |
 | yes        | no         | no        | yes            | any      | OK → `exposed` (operator-secured edge)                                                        |
-| yes        | no         | no        | no             | any      | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
-| yes        | no         | yes       | no             | any      | **REFUSED** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`                                            |
-| yes        | yes        | yes       | yes            | any      | **REFUSED** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url)                            |
+| yes        | no         | no        | no             | any      | **refused** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
+| yes        | no         | yes       | no             | any      | **refused** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`                                            |
+| yes        | yes        | yes       | yes            | any      | **refused** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url)                            |
 
 Guard order (all before any bind/spawn): `--allow-email`/`--allow-domain` without
 `--oauth` → `HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH`; `--oauth` without `--tunnel` →
@@ -66,8 +61,8 @@ http(s) origin → conflict; a tunnel/public-url without `--expose` →
 no `--public-url` (even under `--safe`) →
 `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN`; `--expose` with an origin but without
 edge auth and without `--safe` →
-`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`. `--oauth google` with NO
-allow rule is ALLOWED (any Google account authenticates) but pushes a prominent
+`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`. `--oauth google` with no
+allow rule is allowed (any Google account authenticates) but pushes a prominent
 warning recommending at least one `--allow-email`/`--allow-domain`.
 
 The `watch` surface reuses the same validator but is stricter: a live,
@@ -77,7 +72,7 @@ therefore refused outright with `HUMANISH_WATCH_SAFE_NOT_APPLICABLE` (exit 2), s
 never silently ignored.
 `watch --expose` always requires edge auth (`--tunnel --oauth` or `--public-url`),
 and is also refused with `--dry-run`/`--detach`/`--json` (no live desktop / no
-attached follow). An exposed watch serves ONLY the attached live run: its
+attached follow). An exposed watch serves only the attached live run: its
 `/_humanish/history.json` lists just that run and every other run id 404s
 byte-identically to a nonexistent one, so a remote viewer can never enumerate or
 reach any prior run's raw evidence (loopback watch still serves the full library).
@@ -122,14 +117,14 @@ which adds `sandbox allow-scripts` to that policy.
 
 | Mode              | Invocation                                                                      | Boundary class                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `loopback`        | `humanish serve`                                                                | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed.                                                                                                                                                                                                                                                                                                                                             |
+| `loopback`        | `humanish observe --all`                                                        | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed.                                                                                                                                                                                                                                                                                                                                             |
 | `exposed`         | `--expose --tunnel ngrok --oauth google …`, or `--expose --public-url <origin>` | Edge-authed exposure: only viewers who clear the edge OAuth (or the operator's own edge) reach the loopback server, which then serves everything it grants unless `--safe` composes in. The gate is the edge, not humanish.                                                                                                                                                                                                                                                    |
 | `share-safe-open` | `--expose --safe --tunnel ngrok` (no `--oauth`)                                 | Genuine publishing behind the feedback-grade `share_ready` gate: only runs that pass verify are served. Each request walks the run, and any added, removed or changed file re-verifies it first; a file is read only while its inode, size, mtime and ctime match the walk verify covered, and its bytes are served only when their sha256 matches the hash taken at admission. Everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
 
 ## Keep stream URLs off the library surface
 
 Live desktop stream URLs (auth-bearing hosted-VNC links) are never served by the
-LIBRARY surface, in any mode, and the guarantee is layered:
+library surface, in any mode, and the guarantee is layered:
 
 - **Structural:** runtime stream URLs live in a `WeakMap` keyed by the watch
   process's in-memory `ObserverResult` (`src/observer/render.ts`) and are never
@@ -149,12 +144,14 @@ disk). See observer.md.
 
 ## Know what `share_ready` checks
 
-`share_ready` was designed as the bar for FEEDBACK payloads: evidence eligible
+`share_ready` was designed as the bar for feedback payloads: evidence eligible
 to leave the machine inside a public issue draft. Serve's `share-safe-open` mode
-extends that same gate to arbitrary-audience BROWSING, which is a broader
-exposure of the same artifacts. The honest caveat carries over unchanged:
+extends that same gate to arbitrary-audience browsing, which is a broader
+exposure of the same artifacts. The same caveat carries over:
 `humanish verify` does not yet detect free-form PII/PHI (names, emails, medical
-identifiers; see the README's public-safety boundary and issue #108), so
+identifiers; see
+[Share evidence safely](../../README.md#share-evidence-safely) and the
+[open detector issue](https://github.com/danielgwilson/humanish/issues/108)), so
 `share_ready` means the automated secret/path scan passed, not that a human would
 publish every pixel. Maintainers should treat open mode accordingly: synthetic
 data upstream, review before exposing, and treat `--safe` without edge auth as
@@ -173,13 +170,13 @@ any mutating route ships, the contract is:
 - an operator identity distinct from a viewer, sourced from the edge/control
   plane, not from a humanish-minted cookie;
 - mutating routes require CSRF defenses appropriate to the chosen edge session;
-- the spend rule is invariant 3 applied to remote hands: a phone-initiated LIVE
+- the live-spend rule applies to remote hands too: a phone-initiated live
   run needs its own affirmative declaration at serve startup (an explicit opt-in
-  naming the lab and budget), never a default the viewer UI can reach.
+  naming the study and budget), never a default the viewer UI can reach.
 
 ## Why not Better Auth here
 
-Better Auth is a strong TypeScript auth framework, but it is deliberately NOT
+Better Auth is a strong TypeScript auth framework, but it is deliberately not
 used for this CLI serve surface: serve is an ephemeral, no-database,
 per-invocation loopback server whose only job is to hand persisted evidence to an
 already-authenticated edge. A password/session/social-login framework with a
@@ -193,6 +190,6 @@ where accounts, org membership, and durable sessions actually exist.
 - **Traffic Policy for ngrok.** Migrate off the deprecated `--oauth*` flags to a
   generated Traffic Policy YAML once ngrok requires it (the `yaml` dep is already
   available); pin the behavior in `tests/observer/tunnel.test.ts` first.
-- **Shipped in 0.18.0: `watch --expose`.** Remote LIVE following of a run,
+- **Shipped in 0.18.0: `watch --expose`.** Remote live following of a run,
   including its live E2B desktop stream, behind the same edge auth. It is the one
   surface that deliberately serves runtime stream URLs. See observer.md.