humanish 0.106.1 → 0.108.0

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

@@ -1,240 +0,0 @@
-# Open-Source Install Experience
-
-Date: 2026-06-01
-
-Status: product target for the first `humanish` implementation.
-
-Safety amendment (2026-07-14): the `0.15.1` package binds managed run and
-output storage to validated physical paths and treats provider IDs persisted in a
-run bundle as evidence rather than cleanup authority. The historical product target below remains useful for
-intent and sequencing, but current behavior is defined by the README and
-[`docs/goals/current.md`](../goals/current.md).
-
-## Product Promise
-
-Drop humanish into an app and let a coding agent set up realistic persona
-simulations, run them safely, watch them in a polished observer, and turn
-friction into public-safe issue drafts.
-
-The first experience should feel like a mature one-command simulation harness,
-but with an open-source-safe package shape:
-
-```bash
-npm i -D humanish
-npx humanish init
-npm run humanish:doctor
-npm run humanish:watch
-npm run humanish:verify
-npx humanish feedback issue --run latest --repo example/app --format markdown
-```
-
-## Two-Part Distribution
-
-### NPM Package
-
-The npm package owns executable behavior:
-
-- binary: `humanish`;
-- CLI framework: `commander`;
-- commands: `init`, `doctor`, `run`, `watch`, `review`, `verify`,
-  `lab`, `feedback`;
-- schemas and validators;
-- synthetic starter templates;
-- observer static assets;
-- artifact and run-bundle utilities;
-- redaction and public issue-draft generation.
-
-### Agent Skill
-
-The agent skill owns installation guidance and repo adaptation:
-
-```bash
-npx skills add danielgwilson/humanish --skill humanish
-```
-
-Installable repo skill: [`skills/humanish/SKILL.md`](../../skills/humanish/SKILL.md).
-
-The skill should teach the user's coding agent how to:
-
-- install `humanish`;
-- run `humanish init`;
-- inspect the target app's routes and dev command;
-- create synthetic personas and scenarios;
-- create public-safe `humanish/labs/*.yaml` lab manifests;
-- keep private/local labs under ignored `.humanish/labs/*.yaml` or
-  `.humanish/local/labs/*.yaml`;
-- configure local app targets;
-- document E2B and OpenAI env var names without storing values;
-- use `--env-file <path>` for explicit local env hydration without persisting
-  values into artifacts;
-- run `doctor`, `watch`, `verify`, and `feedback issue`;
-- avoid PII, PHI, secrets, real customer data, and private artifacts.
-
-The skill should not hide critical behavior in chat memory. It should point to
-repo-owned `humanish/` files and package-owned docs.
-
-## Project File Formats
-
-New projects should get a boring, legible format stack:
-
-- `.yaml` for human-authored humanish source such as labs, personas and
-  scenarios;
-- `.mjs` for executable adopter scorers;
-- `.json` and `.ndjson` for generated run artifacts, Observer data, review
-  output, event streams, and synthetic fixtures.
-
-Use `.yml` only where an outside tool's convention already expects it, for
-example GitHub Actions workflows. Do not scaffold `.yml` for humanish source and
-do not use TOML unless a future scalar global-config case clearly needs it.
-
-## First-Run Principles
-
-- No keys required for the first successful run.
-- No live GitHub mutation.
-- No hosted queues or private infrastructure.
-- No real customer/user/patient data.
-- No generated personas from tickets, logs, transcripts, screenshots, or
-  production analytics.
-- Safe dry-run should produce a valid synthetic run bundle and observer view.
-- The user should see what changed in git.
-
-## Lab Manifest Shape
-
-Labs are the public-safe way to name a reusable simulation run. A starter app
-gets a committed synthetic lab:
-
-```yaml
-schema: humanish.lab.v2
-id: first-run
-title: First-run synthetic Observer
-description: Public-safe starter lab that generates a synthetic run bundle and Observer without provider spend.
-subject:
-  source: this-repo
-actors:
-  - type: synthetic-persona
-    count: 4
-scenario:
-  mode: dry-run
-defaults:
-  open: true
-```
-
-Resolution order:
-
-1. `humanish/labs/<id>.yaml` for committed, reproducible labs.
-2. `.humanish/labs/<id>.yaml` for ignored local labs.
-3. `.humanish/local/labs/<id>.yaml` for ignored machine-specific overlays.
-4. explicit `.yaml` path, for example
-   `.humanish/labs/local-dogfood.yaml`.
-
-Private repo targets, local env references, and maintainer dogfood variants
-belong in ignored lab manifests and should be invoked with explicit
-`--env-file`; do not make them package defaults.
-
-## `humanish init`
-
-`humanish init` should:
-
-1. Detect package manager and app framework when possible.
-2. Create committed starter files under `humanish/`.
-3. Create ignored runtime state under `.humanish/`.
-4. Add `.humanish/` and secret/local overlays to `.gitignore`.
-5. Patch `package.json` scripts only after showing the intended diff or when
-   `--yes` is passed.
-6. Create only synthetic public-safe personas and scenarios.
-7. Write credential references as env var names only.
-8. Run a dry-run verification if dependencies are available.
-
-Suggested scripts:
-
-```json
-{
-  "scripts": {
-    "humanish": "humanish",
-    "humanish:doctor": "humanish doctor",
-    "humanish:run": "humanish run --dry-run",
-    "humanish:watch": "humanish watch",
-    "humanish:lab:list": "humanish lab list",
-    "humanish:watch:ci": "humanish watch --json --no-open",
-    "humanish:verify": "humanish verify"
-  }
-}
-```
-
-## Command Ladder
-
-| Command                           | Purpose                                 | First version should                                                                                  |
-| --------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `humanish init`                   | Set up project-owned harness files      | Scaffold committed `humanish/`, ignored `.humanish/`, package scripts                                 |
-| `humanish doctor`                 | Explain readiness                       | Check config, gitignore, app target, browser, env var names, redaction policy                         |
-| `humanish run --dry-run`          | Prove contract without app/browser/keys | Write synthetic run bundle                                                                            |
-| `humanish verify`                 | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors                                                       |
-| `humanish review`                 | Build review packet from evidence       | Summarize verdicts without inventing product proof                                                    |
-| `humanish watch`                  | Run synthetic participants and watch    | Create a fresh four-participant bundle, render Observer, open it, and keep the shell attached         |
-| `humanish watch [lab]`            | Run a named lab and watch it            | Resolve committed or ignored `.yaml` lab manifests, then open/follow Observer                         |
-| `humanish watch --json --no-open` | Agent/CI proof path                     | Create the same bundle and Observer artifacts without browser open or attached watch server           |
-| `humanish lab list`               | Discover available labs                 | List committed labs and ignored local labs with origin labels                                         |
-| `humanish lab inspect <lab>`      | Read a lab manifest                     | Print the parsed lab config, origin, path, and warnings without executing                             |
-| `humanish lab preflight <lab>`    | Check lab readiness before spend        | Validate routing and optionally probe declared targets from a hosted desktop without launching actors |
-| `humanish lab run <lab>`          | Run a lab manifest                      | Human or JSON execution path for every lab route                                                      |
-| `humanish feedback issue`         | Produce public-safe issue draft         | Print Markdown or prefilled issue URL, no GitHub API mutation                                         |
-
-## Live Capability Ladder
-
-Live execution should be staged after the dry-run path is boring:
-
-1. Synthetic dry-run bundle.
-2. Local app reachability and browser smoke.
-3. Scripted browser scenario.
-4. Observer over real screenshots/traces.
-5. Computer-use / OpenAI actor.
-6. E2B substrate.
-7. Multi-persona matrix.
-8. Optional maintainer-only issue sync tooling.
-
-Do not make E2B, OpenAI, or GitHub credentials part of the first successful
-run.
-
-For step 3, app-specific browser scenarios are authored as `.yaml` source under
-`humanish/scenarios/*.yaml`:
-
-```yaml
-schema: humanish.scenario.v1
-id: core-browser-flow
-title: Core browser flow
-persona: synthetic-new-user
-goal: Reach the first meaningful product state with synthetic data.
-mode: browser
-browser:
-  startPath: /
-  steps:
-    - id: open-home
-      label: Open the app
-      action: goto
-      path: /
-      expect:
-        text: "Get started"
-    - id: submit-primary-action
-      label: Submit the primary action
-      action: click
-      selector: "button[type='submit']"
-      expect:
-        stateChanged: true
-```
-
-A scripted-browser lab runs the scenario named by `scenario.ref` against a
-loopback `subject.appUrl`; `humanish/labs/scripted-demo.yaml` is the example.
-A missing or non-executable scenario fails before any browser starts.
-
-Live E2B desktop labs are an optional advanced path. Target projects that need
-them should install `@e2b/desktop` explicitly instead of receiving that
-substrate as part of the default humanish package install. When a GitHub token is
-present, repo labels are redacted in durable artifacts by default; live stream
-auth URLs are used only by the attached watch server and are not persisted.
-
-An explicitly selected [local browser lab](../architecture/local-browser-runtime.md)
-can instead use Linux x64, Docker/KVM and an existing Codex ChatGPT login for
-participants and findings. The installed CLI prepares its pinned image before
-the first live run. It does not install host prerequisites, and Mac, inbox and
-media integration remain separate follow-ups. Existing hosted lab configuration
-is preserved.

package/docs/ramp/README.md

@@ -1,294 +0,0 @@
-# humanish Ramp
-
-Use this page when you are starting cold on `humanish`. It is meant to be
-useful without chat history, private notes, local machine paths, or maintainer
-context. It is the last step of the reading order in
-[CONTRIBUTING.md](../../CONTRIBUTING.md#read-these-in-order) and adds current state, how to pick
-work and the quality bar.
-
-## First Read
-
-Start with three things:
-
-1. The files in [CONTRIBUTING.md's reading order](../../CONTRIBUTING.md#read-these-in-order).
-2. The current task and [`docs/goals/current.md`](../goals/current.md) for current
-   product status. Explicit task direction takes precedence over historical queues.
-3. Instructions in the component being changed, then its relevant contracts.
-
-Use the references below as needed. Historical plans are context, not a backlog
-to resume automatically. Keep one concise current task handoff with the requested
-outcome, demonstrated behavior, next complete result, constraints and rejected or
-deferred approaches; link evidence rather than repeating its chronology.
-
-| When working on                            | Reference                                                                                                                                                                      |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Install, commands or first-run UX          | [`README.md`](../../README.md), [install experience](../product/open-source-install-experience.md)                                                                             |
-| Security, evidence handling or defaults    | [Invariants and defaults](../principles/invariants-and-defaults.md)                                                                                                            |
-| Observer                                   | [Observer architecture](../architecture/observer.md) and its component instructions                                                                                            |
-| Bundle formats or policy                   | [Run bundle](../contracts/run-bundle.md), [policy](../contracts/policy.md)                                                                                                     |
-| Public artifacts or packaging              | [Public-readiness standard](../release/public-readiness-standard.md), [release procedure](../release/open-source-readiness.md)                                                 |
-| Proof architecture or historical decisions | [Proof roadmap](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md), [historical delivery roadmap](../roadmap/world-class-open-source-v0.md) |
-
-## Mental Model
-
-humanish is a persona simulation harness for apps, CLIs, and agent-facing product
-flows.
-
-- `humanish/` is committed source: lab manifests, personas, scenarios and
-  coverage notes.
-- `.humanish/` is ignored runtime state: runs, Observer output, transcripts,
-  reviews, temporary clones, and local evidence.
-- humanish source uses `.yaml` for human-authored simulation intent and
-  JSON/NDJSON for generated artifacts.
-- A run bundle is the source of truth.
-- The Observer is the projection that makes that truth reviewable.
-- Feedback commands turn verified evidence into public-safe issue drafts.
-
-If a change does not improve one of those loops, it probably belongs elsewhere.
-
-## Current State
-
-[CHANGELOG.md](../../CHANGELOG.md) lists what each version changed. This section describes
-what the source supports now.
-
-humanish has a working public package shape and a safe first-run path.
-
-Implemented:
-
-- `commander` CLI with stable command help;
-- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, `analyze`, and `feedback`;
-- study analysis with bounded provider admission, a live-run default and opt-out, immutable findings,
-  source-bound corrections and evidence-linked Observer review;
-- synthetic run bundles;
-- public-safety verification with machine-readable `shareSafety.status`
-  (`share_ready`, `local_only`, or `blocked`);
-- mission-control Observer over UI, CLI, TUI, and Codex UI stream contracts;
-- public-safe feedback issue drafts without GitHub API mutation, gated on
-  `share_ready` evidence;
-- skills.sh-compatible agent skill;
-- first-class lab manifest resolution through `humanish/labs/*.yaml` and
-  ignored `.humanish/labs/*.yaml` overlays, as `humanish.lab.v2` compositions
-  (`src/lab/config.ts`) with one engine and no hardcoded lab kinds;
-- a first-party actor registry with five registered descriptors
-  (`src/actors/registry.ts`); `actors[0].type` is a real dispatch key on the
-  computer-use, scripted-browser, and terminal-product routes;
-- a computer-use route and clone subject provider: `subject.source: app-url`
-  drives a lab-owner loopback app in a hosted desktop, and `subject.source:
-clone` + `serve` clones, installs, and serves a real app in-sandbox from
-  config before the actor drives it (`src/routes/computer-use/route.ts`);
-- seven declared subject sources: `this-repo` (dry-run-only), `clone`, `app-url`,
-  `local-app` (library-assisted, in-process, no desktop), `terminal-product`,
-  `desktop-cli` (computer-use participant at a terminal), and `local-tree`;
-  each route fails closed on unsupported combinations;
-- bounded fan-out with separate worlds (`actors[0].count`, `lanes[]`, or `roster[]`),
-  backed by deterministic and kept live proof;
-- concurrent single-origin shared-world execution with deterministic and kept
-  live proof; verify still reads bundles from the sequential route removed in
-  0.106.0;
-- `subject.source: local-tree`, which packages one selected working tree with a
-  content pin before using the same provision-and-serve path as clone subjects;
-- an off-app comms funnel for email-gated flows: a vendor-neutral in-sandbox
-  catch redirects the app's own send API, a persona reads a minimal inbox surface
-  and clicks through, and a digest-only `humanish.comms-thread.v1` artifact
-  records the thread with no raw address, link, or code. It is wired into the
-  computer-use and concurrent shared-world routes and live-proven on computer-use.
-  SMS is not yet a configured execution route;
-- resolved-persona directives that actually shape the actor prompt on the
-  terminal-product route (traits are applied and recorded in the actor trace, not
-  decorative), reusing the same `persona.ts` compiler as the computer-use route;
-- a CLI-loadable adopter scorer seam (`review.scorer.ref` in the lab manifest, or
-  a `--scorer <path>` override): a config-declared `.mjs` supplies
-  `{score, deriveFeedback, deriveArtifacts}`, resolved with the same containment
-  as `scenario.ref` and digest-pinned in the bundle
-  (`humanish.scorer-provenance.v1`); a config-declared scorer that fails to render
-  a pass fails the run on the scorer-capable routes, while library callers keep
-  the additive behavior (`costProbe` stays library-only); on the terminal route
-  the scoring context carries the FULL normalized transcript (byte-identical to
-  the persisted `terminal-transcript.txt`) instead of the ~2KB tail projection. The
-  [scorer example](../../examples/scorer/README.md) attaches one from the CLI and from a
-  library caller;
-- containment checks for managed run storage, Observer and feedback reads,
-  actor artifacts, lab discovery, Git metadata, and source archives;
-- cleanup inspection receipts that do not treat mutable run-bundle IDs as
-  provider-mutation authority;
-- every route publishes through the run lifecycle (`runScope` and `Run` in
-  `src/run/run.ts`): computer-use, shared-world, scripted, terminal, and the preview's
-  `runDryRun`.
-
-Still not good enough:
-
-- capability receipts are not adopter replacement: no first-party deletion
-  branch has yet removed a bespoke generic harness while preserving
-  decision-equivalent proof;
-- the five actor descriptors are a closed first-party union, not a supported
-  out-of-tree actor-registration API;
-- multi-origin shared-world is an accepted design direction, but remains
-  unimplemented and gated on a real adopter proving the need;
-- the README hero is the drawDB real-application study, a legible capture of a
-  studied public subject (drawDB is not a humanish adopter); coverage beyond that single
-  studied subject (the stratified breadth panel) remains open.
-
-## Check which compositions a lab can declare
-
-`parseLabConfig` (`src/lab/config.ts`) enforces this matrix through `compositionReason`
-(`src/lab/composition-rules.ts`), which uses the predicates in `src/lab/routing.ts` and the reasons
-in `src/lab/validation.ts`. The route entries check it again
-for library callers. `tests/fixtures/task-route-preflight/labs.json` holds one lab for each
-accepted row except the local browser row. `tests/lab/task-route-preflight.test.ts` checks that
-each of those labs routes as shown. `tests/run-lab-local-substrate.test.ts` covers the local
-browser row. Accepted rows have further required fields, such as `subject.serve` on `clone`, and
-the parse error names the missing one. The computer-use actors are `openai-computer-use` and
-`local-agent`.
-
-| Route (backend name)                       | `subject.source`                                 | `execution.target`       | `actors[0].type`                       | Result                                                                         |
-| ------------------------------------------ | ------------------------------------------------ | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
-| `computer-use` (`cua`)                     | `app-url`                                        | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
-| `computer-use` (`cua`)                     | `app-url`                                        | `local`                  | a computer-use actor                   | Supported on a local Firecracker desktop, inside Lima on macOS                 |
-| `computer-use` (`cua`)                     | `clone`, `local-tree`                            | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
-| `computer-use` (`cua`)                     | `desktop-cli`                                    | `e2b-desktop` or absent  | a computer-use actor                   | Supported                                                                      |
-| `computer-use` (`cua`)                     | `local-app`                                      | `local` or absent        | a computer-use actor                   | Library only; the CLI refuses it with `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR` |
-| `shared-world` (`concurrent-shared-world`) | `clone`, `local-tree` + `topology: shared-world` | `e2b-desktop`            | a computer-use actor                   | Supported                                                                      |
-| `shared-world` (`concurrent-shared-world`) | `app-url` + `topology: shared-world`             | `e2b-desktop`            | a computer-use actor                   | Supported with `policies.allowPublicTargets: true`                             |
-| `scripted`                                 | `app-url` with a loopback URL                    | `local` or absent        | `scripted-browser`                     | Supported                                                                      |
-| `scripted`                                 | `clone`                                          | `e2b-desktop`            | `scripted-browser`                     | Supported                                                                      |
-| `terminal`                                 | `terminal-product`                               | `e2b-terminal` or absent | `codex-exec`                           | Supported                                                                      |
-| `preview` (`synthetic`)                    | `this-repo`                                      | absent                   | not `scripted-browser` or `codex-exec` | Dry run only                                                                   |
-| none                                       | any other pairing                                | any                      | any                                    | Refused at parse with `HUMANISH_LAB_INVALID`                                   |
-
-The fixture's `supported` field records which routes accept declared `actors[0].tasks`. The
-computer-use labs in the fixture accept them. The other routes refuse them at parse.
-
-## First Commands
-
-From a clean checkout:
-
-```bash
-git status --short --branch
-pnpm install --frozen-lockfile
-pnpm humanish lab list
-pnpm humanish watch --json --no-open   # a keyless preview run
-pnpm humanish runs --json
-pnpm vitest run tests/<file>           # one test file: the fast loop
-pnpm check                             # the full local gate
-pnpm release:check                     # what CI runs; last, before a pull request
-```
-
-For local product feel:
-
-```bash
-pnpm humanish watch
-```
-
-For private/local dogfood, author an ignored lab manifest under
-`.humanish/labs/` or `.humanish/local/labs/`, then invoke it explicitly with an
-ignored env file:
-
-```bash
-pnpm humanish watch .humanish/labs/local-dogfood.yaml --env-file .humanish/local/provider.env
-```
-
-## How To Pick Work
-
-Start from [`docs/goals/current.md`](../goals/current.md).
-
-Prefer work that makes humanish more believable to a new maintainer:
-
-- a command becomes easier to run;
-- a run bundle becomes more truthful;
-- Observer evidence becomes more inspectable;
-- verification catches a real bad state;
-- feedback drafts become more actionable;
-- public-safety gates catch a class of leak or stale residue.
-
-If no GitHub issue exists for substantial work, draft one with the repo issue
-template before building. Use labels to communicate authority, area, risk, and
-required proof.
-
-## Quality Bar
-
-Do not close a change on narrative alone.
-
-Useful proof includes:
-
-- `pnpm release:check`;
-- `pnpm release:dogfood` before a tag (see below);
-- focused unit or contract tests;
-- a generated run bundle under ignored `.humanish/`;
-- Observer screenshots or health output;
-- `humanish verify` results;
-- public-surface scan output;
-- fresh clone checks for packaging or release work.
-
-A green subset is not the same thing as complete coverage. If something is not
-covered, name it as a gap.
-
-## Public Boundary
-
-Assume this repository is public even when local or remote visibility says it is
-private.
-
-Never commit or paste:
-
-- PII or PHI;
-- secrets, keys, tokens, cookies, or raw env files;
-- raw private transcripts;
-- private screenshots;
-- private customer or patient data;
-- local machine paths;
-- private upstream code or operational details.
-
-Use synthetic examples, redacted evidence, and env var names without values.
-
-## Embarrassment Filter
-
-Before committing, ask:
-
-- Would this make sense to someone who found the repo through npm?
-- Would I be comfortable with this file quoted in a public issue?
-- Does this depend on private chat memory?
-- Does it mention removed docs, private machine paths, or internal-only names?
-- Does it claim product proof when it only proves a contract?
-
-If the answer is uncomfortable, rewrite it, synthesize it, or keep it out of the
-repo.
-
-## Hand-Off Format
-
-End substantial work with:
-
-- what changed;
-- what proof passed;
-- what remains uncertain;
-- the next best issue or command.
-
-Future agents should be able to continue from the repo, not from the previous
-chat transcript.
-
-## Before you tag: send a participant to meet the build
-
-```bash
-pnpm release:dogfood     # needs OPENAI_API_KEY + E2B_API_KEY; costs about a dollar
-```
-
-`release:check` proves the code is internally consistent. It cannot tell you whether
-someone landing on this build can get anywhere with it. That gap has cost a release:
-`0.56.0` passed every check and shipped a regression that hid a run's
-price at exactly the moment a person was deciding whether to set keys up. A
-synthetic participant found it hours later.
-
-So the last gate before a tag is the product's own first-contact study, pointed at
-the release candidate. It packs the tarball, uploads it into the sandbox, and has a
-real autonomous agent install that tarball. Installing `humanish@latest` instead would
-measure the last release, the one artifact we already know about.
-
-It prints the participant's report and fails the gate if they could not get there.
-**Read the report even when it passes.** The verdict is a marker the participant
-sets; the paragraph underneath it is the finding, and it has twice repeated an
-adoption problem we already knew about in words no test could produce.
-
-This spends money and needs keys, so it is deliberately NOT part of `release:check`
-and never runs in CI. The lab's caps hold product spend to `$0`; what it costs is
-the agent's own tokens and a few sandbox-minutes. The agent's model key stays outside
-the sandbox in an E2B egress rule (`runtimeAuth: openai-egress`), and its `web_search`
-fetches run on the model provider's side, so an error from one says nothing about the
-sandbox's network.