humanish 0.106.1 → 0.108.0

package/examples/scorer/run.mjs

@@ -5,27 +5,26 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { LAB_CONFIG_SCHEMA, parseLabConfig, runLab, verifyRun } from "humanish";
+import { STUDY_SCHEMA, parseStudy, runStudy, verifyRun } from "humanish";
 import { score } from "./scorer.mjs";
 
-// One scorer module, attached two ways to a dry run of a computer-use lab: as library hooks and
+// One scorer module, attached two ways to a dry run of a computer-use study: as library hooks and
 // through the CLI's --scorer flag. A dry run needs no keys, desktop or running app.
-const lab = {
-  schema: LAB_CONFIG_SCHEMA,
+const study = {
+  schema: STUDY_SCHEMA,
   id: "scorer-example",
   title: "Score a dry run",
+  route: "computer-use",
   subject: { source: "app-url", appUrl: "http://127.0.0.1:3000/" },
-  actors: [
-    { type: "openai-computer-use", persona: "pixel-pat", mission: "Find the pricing page." },
-  ],
+  actor: { type: "openai-computer-use", persona: "pixel-pat", mission: "Find the pricing page." },
   execution: { target: "e2b-desktop" },
   review: { analysis: false },
 };
 
 // A throwaway project directory; both runs write their bundles under its .humanish/runs/.
 const project = await mkdtemp(join(tmpdir(), "humanish-scorer-example-"));
-// JSON is valid YAML, so the CLI reads the same manifest the library call uses.
-await writeFile(join(project, "lab.yaml"), `${JSON.stringify(lab, null, 2)}\n`);
+// JSON is valid YAML, so the CLI reads the same study file the library call uses.
+await writeFile(join(project, "study.yaml"), `${JSON.stringify(study, null, 2)}\n`);
 await copyFile(new URL("./scorer.mjs", import.meta.url), join(project, "scorer.mjs"));
 
 /** @param {string} runId */
@@ -37,9 +36,9 @@ async function scored(runId) {
   return { runId, adapterScore: bundle.adapterScore, verified: verification.ok };
 }
 
-const parsed = parseLabConfig(lab);
+const parsed = parseStudy(study);
 if (!parsed.ok) throw new Error(parsed.error.message);
-const outcome = await runLab(parsed.config, { cwd: project, dryRun: true, scorer: { score } });
+const outcome = await runStudy(parsed.config, { cwd: project, dryRun: true, scorer: { score } });
 if (outcome.route !== "computer-use" || !outcome.result.ok) {
   throw new Error(`Library dry run failed: ${JSON.stringify(outcome.result)}`);
 }
@@ -49,7 +48,7 @@ const library = await scored(outcome.result.runId);
 const bin = fileURLToPath(new URL("./cli.js", import.meta.resolve("humanish")));
 const { stdout } = await promisify(execFile)(
   process.execPath,
-  [bin, "lab", "run", "lab.yaml", "--dry-run", "--no-open", "--scorer", "scorer.mjs", "--json"],
+  [bin, "run", "study.yaml", "--dry-run", "--no-open", "--scorer", "scorer.mjs", "--json"],
   { cwd: project },
 );
 const cli = await scored(JSON.parse(stdout).runId);

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "humanish",
-  "version": "0.106.1",
-  "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
+  "version": "0.108.0",
+  "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
-    "agent-harness",
     "cli",
-    "persona-simulation",
+    "computer-use",
+    "synthetic-users",
     "ui-testing",
+    "usability-testing",
+    "user-research",
     "ux-research"
   ],
   "homepage": "https://github.com/danielgwilson/humanish#readme",
@@ -23,25 +25,19 @@
     "humanish": "./dist/cli.js"
   },
   "files": [
-    "AGENTS.md",
     "CHANGELOG.md",
     "dist",
+    "docs/README.md",
     "docs/architecture",
-    "docs/assets",
     "docs/contracts",
     "docs/decisions",
-    "docs/goals/current.md",
     "docs/principles",
     "docs/product",
-    "docs/ramp",
-    "docs/release",
-    "docs/roadmap",
     "examples",
     "skills",
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "CONTRIBUTING.md",
     "ARCHITECTURE.md",
     "CONTEXT.md",
     "TELEMETRY.md"
@@ -60,7 +56,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && pnpm --filter humanish-observer build && pnpm --filter humanish-tui build && node scripts/finish-build.mjs",
-    "check": "pnpm format:check && pnpm lint && pnpm knip && pnpm prose:check && pnpm vocabulary:check && pnpm typecheck && pnpm test && pnpm tui:test && pnpm build && pnpm guest-media:startup:proof && pnpm cli:startup:test && pnpm cli:preflight:test && pnpm tui:smoke",
+    "check": "pnpm format:check && pnpm lint && pnpm knip && pnpm prose:check && pnpm vocabulary:check && pnpm site-css:check && pnpm typecheck && pnpm test && pnpm tui:test && pnpm build && pnpm guest-media:startup:proof && pnpm cli:startup:test && pnpm cli:preflight:test && pnpm tui:smoke",
     "cli:startup:test": "node scripts/terminal-startup-exit-proof.mjs",
     "cli:preflight:test": "node scripts/task-route-preflight-proof.mjs",
     "humanish": "tsx src/cli.ts",
@@ -69,7 +65,7 @@
     "public-surface:scan": "node scripts/public-surface-scan.mjs",
     "api:proof": "node scripts/public-api-proof.mjs",
     "release:check": "pnpm check && pnpm api:proof && pnpm public-surface:scan && pnpm skill:check && npm pack --dry-run",
-    "skill:check": "DISABLE_TELEMETRY=1 npx skills add . --list",
+    "skill:check": "DISABLE_TELEMETRY=1 pnpm exec skills add . --list",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit && pnpm --filter humanish-observer typecheck && pnpm --filter humanish-tui typecheck",
     "tui:typecheck": "pnpm --filter humanish-tui typecheck",
@@ -80,7 +76,7 @@
     "docs:generate": "tsx scripts/generate-cli-docs.ts",
     "docs:check": "tsx scripts/generate-cli-docs.ts --check && tsx scripts/check-doc-paths.ts && tsx scripts/check-doc-symbols.ts && tsx scripts/check-doc-comments.ts",
     "observer:browser:proof": "node scripts/observer-browser-proof.mjs",
-    "observer:iframe:proof": "node scripts/observer-iframe-proof.mjs",
+    "observer:iframe:proof": "node --import tsx scripts/observer-iframe-proof.mjs",
     "observer:chrome:proof": "node scripts/observer-chrome-proof.mjs",
     "observer:reliability:proof": "node scripts/observer-reliability-proof.mjs",
     "tui:connections:proof": "python3 scripts/tui-connections-proof.py",
@@ -90,10 +86,12 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=444",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=440",
     "knip": "knip",
-    "prose:check": "node scripts/check-code-prose.mjs --max-issue-refs=371 --max-fix-tags=23 --max-caps=1742",
-    "vocabulary:check": "tsx scripts/check-retired-words.ts --max-lane=188 --max-seat=6 --max-role=52 --max-sim=51 --max-study=287"
+    "prose:check": "node scripts/check-code-prose.mjs",
+    "vocabulary:check": "tsx scripts/check-retired-words.ts",
+    "site-css:check": "node scripts/check-site-css.mjs",
+    "site:hero:proof": "node scripts/site-hero-wrap-proof.mjs"
   },
   "dependencies": {
     "commander": "^15.0.0",
@@ -114,6 +112,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "oxlint-tsgolint": "7.0.2003",
+    "skills": "1.7.0",
     "tsx": "^4.23.15",
     "typescript": "catalog:",
     "vitest": "catalog:"

package/skills/humanish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humanish
-description: Install and configure humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
+description: Synthetic user research for apps, CLIs, and agent-facing product flows. Install and configure the humanish CLI in a JavaScript app. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
 ---
 
 # humanish CLI
@@ -32,9 +32,9 @@ Everything it shows has a machine-readable equivalent, which is what you want:
 
 | Instead of the TUI  | Use                                                                                    |
 | ------------------- | -------------------------------------------------------------------------------------- |
-| browsing labs       | `npx humanish lab list --json`                                                         |
+| browsing studies    | `npx humanish study list --json`                                                       |
 | browsing runs       | `npx humanish runs --json`                                                             |
-| starting a run      | `npx humanish lab run <lab> --json --no-open`                                          |
+| starting a run      | `npx humanish run <study> --json --no-open`                                            |
 | a run's outcome     | `npx humanish review --run <id> --json`                                                |
 | communication setup | `npx humanish comms providers --json` and `npx humanish comms connections list --json` |
 
@@ -51,7 +51,7 @@ authorized credential source), followed by
 and `HUMANISH_STRICT_KEYS=1` still apply. Read installed provider capabilities:
 use `humanish comms check --online --json` for read-only authentication.
 Authentication does not establish mailbox permissions, capacity or delivery.
-`humanish comms configure --lab <path> --json` previews an ignored lab copy;
+`humanish comms configure --study <path> --json` previews an ignored study copy;
 add `--apply --plan-token <digest>` to save the reviewed version. Launch its
 exact returned path, not a basename that could resolve to another manifest.
 
@@ -87,9 +87,9 @@ exact returned path, not a basename that could resolve to another manifest.
 5. Confirm the layout:
    - commit `humanish/` source files;
    - ignore `.humanish/` runtime artifacts;
-   - keep committed labs under `humanish/labs/*.yaml`;
-   - keep private/local labs under ignored `.humanish/labs/*.yaml` or
-     `.humanish/local/labs/*.yaml`;
+   - keep committed studies under `humanish/studies/*.yaml`;
+   - keep private/local studies under ignored `.humanish/studies/*.yaml` or
+     `.humanish/local/studies/*.yaml`;
    - keep `.env.example` commit-safe and value-free;
    - never commit generated run bundles.
 
@@ -109,34 +109,34 @@ Do not pass numeric `maxCostUsd`/`maxOutputTokens` or their CLI flags to the
 account branch. It cannot enforce those ceilings and rejects them. Account dollar
 cost remains unknown even when token usage is reported. There is no fallback to
 an API key or another provider. `analyze --dry-run --provider codex` validates
-local evidence/configuration only; `doctor --lab` checks setup without a model
+local evidence/configuration only; `doctor --study` checks setup without a model
 request. Inspect a failed attempt before explicitly retrying `--provider codex
 --rerun`. Opening Observer never starts analysis.
 
 ## Local browser setup
 
 On Linux x64 with local rootful Docker, KVM and TUN, or a supported M3-or-newer
-Mac with native ARM64 Node and Lima 2.2+, an `app-url` lab can set `execution.target: local` and `actors[0].type: local-agent` with
+Mac with native ARM64 Node and Lima 2.2+, an `app-url` study can set `execution.target: local` and `actor.type: local-agent` with
 `localAgent: codex`. It uses the supported Codex ChatGPT login, not E2B or an
 OpenAI API key. Inference is remote and consumes account quota. Existing hosted
-labs stay hosted; never silently change their execution or billing provider.
+studies stay hosted; never silently change their execution or billing provider.
 
-Use `humanish runtime status --json` and `humanish doctor --lab <path> --json`
+Use `humanish runtime status --json` and `humanish doctor --study <path> --json`
 for read-only setup inspection. `humanish runtime setup` downloads and verifies
 the pinned runtime; a live local run also prepares it automatically. The normal
-`humanish lab run <path>` command and TUI use the same study runner and Observer.
-See [the complete example and limits](../../docs/architecture/local-browser-runtime.md).
+`humanish run <path>` command and TUI use the same study runner and Observer.
+See [the complete example and limits](https://humanish.dev/docs/local-browser).
 
 Local browsers currently require a loopback app URL with an explicit port above
 1023 and use a 960×720 Chromium desktop. For email-gated local apps, start
 `humanish comms catch`, point the app's email sends at it, and declare
-`comms.email.external.catchBaseUrl`. Use `doctor --lab` to check its recipient
+`comms.email.external.catchBaseUrl`. Use `doctor --study` to check its recipient
 routes. This captures app sends without mailbox-provider credentials; it does
 not receive arbitrary internet email. Each participant gets only its assigned
 inbox through the local desktop. Real receiving still needs a supported hosted
-route. See [captured inbox setup](../../docs/architecture/comms-inbox.md#local-browser-studies).
+route. See [captured inbox setup](https://humanish.dev/docs/comms-inbox#local-browser-studies).
 Optional camera and spoken conversation require a separate media
-runtime; follow [participant media](../../docs/architecture/participant-media.md)
+runtime; follow [participant media](https://humanish.dev/docs/participant-media)
 for setup and provider limits. Speech uses the same continuing Codex participant,
 not a second conversation. Do not claim that installing the CLI also installs
 Docker or Lima, or qualifies a machine for arbitrary participant counts.
@@ -144,14 +144,14 @@ Docker or Lima, or qualifies a machine for arbitrary participant counts.
 For continuous desktop playback, independent computer-use participants can opt into
 `execution.desktop.recording: { audio: true }` (`false` for screen-only video).
 Screenshots remain the default. Recording does not enable camera or speech;
-the raw media stays local-only. See [desktop recording](../../docs/architecture/desktop-recording.md)
+the raw media stays local-only. See [desktop recording](https://humanish.dev/docs/desktop-recording)
 for runtime requirements and export limits.
 
 ## Format Stack
 
 When creating or editing humanish files:
 
-- use `.yaml` for human-authored humanish source: labs, personas and scenarios;
+- use `.yaml` for human-authored humanish source: studies, personas and scenarios;
 - use `.mjs` for executable adopter scorers named by `review.scorer.ref`;
 - use `.json` or `.ndjson` for generated machine artifacts, Observer data, run
   bundles, event streams, and synthetic fixtures.
@@ -188,9 +188,9 @@ background: |
 A profile with `background` receives only explicitly declared trait directives.
 Legacy profiles without it retain medium defaults for missing patience and
 technical confidence. Avoid contradictory prose and traits; inspect the compiled
-brief with `humanish lab inspect <lab> --json` before running.
+brief with `humanish study show <study> --json` before running.
 
-For an autonomous participant study, use a computer-use/local-agent lab and write
+For an autonomous participant study, use a computer-use/local-agent study and write
 its `mission` as a believable situation and desired outcome. Supply fixture facts
 needed to act, but do not supply selectors, click sequences, hidden success rules,
 expected defects or recovery tricks. For example: “Saturday's event needs two
@@ -230,42 +230,44 @@ and `waitForSelector`. Supported expectations are `text`, `selectorVisible`,
 values only. Do not write real emails, names, customer data, tickets, logs, or
 tokens into scenario files.
 
-## Authoring Labs
+## Authoring Studies
 
-Create reusable simulation runs as `.yaml` lab manifests:
+Write reusable studies as `.yaml` study files (`humanish.study.v3`):
 
 ```yaml
-schema: humanish.lab.v2
+schema: humanish.study.v3
 id: first-run
 title: First-run synthetic Observer
+route: preview
+mode: dry-run
 subject:
   source: this-repo
-actors:
-  - type: synthetic-persona
-    count: 4
-scenario:
-  mode: dry-run
+actor:
+  type: synthetic-persona
+participants: 4
 defaults:
   open: true
 ```
 
-A lab is a composition (`subject` × `actors` × `execution` × `scenario` ×
-`policies`), not a hardcoded kind; there is no v1 compatibility. Run
-`npx humanish lab inspect <lab>` to see how a manifest parses, including
-warnings for fields the engine does not consume yet.
+A study declares its `route` (`preview`, `computer-use`, `shared-world`, `terminal` or
+`scripted`) and composes `subject`, `actor`, `participants`, `caps`, `execution` and
+`policies` for it; a key the route does not read is a parse error that names the route.
+Run `npx humanish study show <study>` to see how a study file parses. A
+`humanish.lab.v2` file from 0.107 still runs with a warning; `npx humanish migrate`
+rewrites it as v3 under `studies/`.
 
 ### Many actors at once (fan-out, shared worlds, concurrency)
 
-- **Every declared participant runs live at once by default.** A 6-participant
-  roster is 6 simultaneous actors; total sessions and spend are the same either
+- **Every declared participant runs live at once by default.** A 6-entry
+  `participants` list is 6 simultaneous actors; total sessions and spend are the same either
   way, only wall-clock and simultaneity differ. `execution.concurrency` is a
   CAP, not a mode: declare it only to bound simultaneous paid desktops, and
   expect a parse warning when the cap makes participants run in waves (a green
   waved run looks identical to the all-live run you meant, so the harness says
   so up front).
 - **Separate worlds (`per-lane-worlds`) vs one shared world.** A plain
-  multi-participant computer-use lab gives each actor its OWN app instance
-  (independent studies in parallel). Add `subject.topology: shared-world` for N
+  multi-participant computer-use study gives each actor its OWN app instance
+  (independent studies in parallel). Declare `route: shared-world` for N
   actors in ONE world (a lobby, a shared DB, actors seeing each other's
   changes). Shared-world participants run at once; `execution.concurrency` must
   be at least 2 there.
@@ -274,8 +276,8 @@ warnings for fields the engine does not consume yet.
   run looks like idle tiles — another reason to leave the cap out unless you
   need it.
 
-Use committed `humanish/labs/*.yaml` for public-safe, reproducible labs. Use
-ignored `.humanish/labs/*.yaml` or `.humanish/local/labs/*.yaml` for private repo
+Use committed `humanish/studies/*.yaml` for public-safe, reproducible studies. Use
+ignored `.humanish/studies/*.yaml` or `.humanish/local/studies/*.yaml` for private repo
 targets, local-only dogfood, or machine-specific settings. Never commit private
 repo names, stream URLs, credential values, screenshots, logs, source snippets,
 or operational details.
@@ -283,10 +285,10 @@ or operational details.
 Useful commands:
 
 ```bash
-npx humanish lab list
-npx humanish lab inspect first-run
+npx humanish study list
+npx humanish study show first-run
 npx humanish watch first-run
-npx humanish lab run first-run --json --no-open
+npx humanish run first-run --json --no-open
 ```
 
 ### Off-app email verification (comms)
@@ -316,7 +318,7 @@ and model charges are separate. Use `humanish comms recover --json` after an
 interrupted run, then `humanish comms recover --run <id> --apply --json` for its
 privately recorded resources. Never derive deletion authority from run artifacts.
 SMS, participant sending, borrowed inboxes and other providers remain unavailable.
-See `docs/architecture/real-email-receiving.md` for limits and recovery.
+See [real email receiving](https://humanish.dev/docs/email-receiving) for limits and recovery.
 
 The following configuration selects **local capture**:
 
@@ -341,9 +343,9 @@ customize addresses or limit which participants do email:
 
 ```yaml
 recipients:
-  - lane: signup-01 # this lab's REAL participant id: a roster entry's `id`, or the
-    # generated lane-01..lane-NN names when you use `count`. An unknown id
-    # is a hard parse error listing the lab's actual participant ids (a mismatch
+  - lane: signup-01 # this study's REAL participant id: a `participants` entry's `id`,
+    # or the generated lane-01..lane-NN names when you use a count. An unknown id
+    # is a hard parse error listing the study's actual participant ids (a mismatch
     # would silently disable the funnel for that participant, which is how a
     # 6-actor field run lost every inbox at once). Participants you leave out get
     # no inbox and are never told one exists — the parser warns which.
@@ -361,7 +363,8 @@ is rejected because it is not wired there.
 For app-url/operator-provided subjects, run `humanish comms catch` on a reachable
 host, point the app's email sends at that catch, and declare
 `comms.email.external.catchBaseUrl` (plus `inboxBaseUrl` if different). A declared
-`authTokenEnv` is an environment variable name, never a credential value.
+`authTokenEnv` is an environment variable name, never a credential value; its
+token must be at least 16 characters.
 The in-sandbox catch
 needs `python3` (the stock E2B desktop has it).
 Evidence is digest-only (`humanish.comms-thread.v1` — counts and digests, never
@@ -371,8 +374,8 @@ inbox page. See `docs/contracts/schemas.md` for the full `comms:` shape and
 
 ## First Proof Run
 
-Run the no-credentials path first. This proves humanish artifact plumbing, not
-target app behavior:
+Run the no-credentials path first. It is a dry run: humanish writes a synthetic
+run bundle and tests no target app behavior:
 
 ```bash
 npx humanish doctor
@@ -385,7 +388,7 @@ For CI or non-interactive proof:
 
 ```bash
 npx humanish watch --json --no-open
-npx humanish lab run first-run --json --no-open
+npx humanish run first-run --json --no-open
 ```
 
 The feedback command prints a public-safe Markdown draft. It must not call the
@@ -393,31 +396,31 @@ GitHub API, require a token, update Projects, use provider credits, or claim
 product behavior proof from a dry run.
 
 When the target app can run locally, prove a known browser path with a
-scripted-browser lab after starting the app on loopback. The lab replays a
+scripted-browser study after starting the app on loopback. The study replays a
 `browser.steps` scenario (see above) on a desktop surface, plus a mobile one
 with `count: 2`. The scripted steps make no model requests. Post-run analysis
 still runs by default when `OPENAI_API_KEY` is set, with a $3 cap; keep
 `review.analysis: false` to skip it. Copy the shape of
-[`humanish/labs/scripted-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/labs/scripted-demo.yaml)
+[`humanish/studies/scripted-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/studies/scripted-demo.yaml)
 or the example in the
 [lab manifest reference](https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios):
-set `subject.appUrl` to the loopback URL, `scenario.ref` to the scenario id,
-and `scenario.mode: live`. Without `mode: live` the lab is a dry run that opens
+set `subject.appUrl` to the loopback URL, `scenario` to the scenario id,
+and `mode: live`. Without `mode: live` the study is a dry run that opens
 no browser.
 
 ```bash
 # in another terminal, start the target app on 127.0.0.1 or localhost
-npx humanish lab inspect <lab> --json
-npx humanish lab run <lab> --json --no-open
+npx humanish study show <study> --json
+npx humanish run <study> --json --no-open
 npx humanish verify --run latest --json
-npx humanish watch --run latest --detach --no-open --json
+npx humanish observe --run latest --open   # for a person; it serves until Ctrl-C
 ```
 
-Do not use `humanish watch --sims ...` as a substitute for a scripted-browser
-lab. `watch` renders or follows Observer evidence; a live scripted-browser lab
+Do not use `humanish watch --count ...` as a substitute for a scripted-browser
+study. `watch` renders or follows Observer evidence; a live scripted-browser study
 captures desktop and mobile browser evidence against a running app.
 
-## Optional Live E2B Lab
+## Optional Live E2B Study
 
 Live headed E2B desktop participants are optional. Add the substrate dependency only
 when the user explicitly wants live E2B execution:
@@ -437,7 +440,7 @@ Do not paste values into files, prompts, run bundles, issue drafts, or logs.
 Load local values only at invocation time:
 
 ```bash
-npx humanish watch .humanish/labs/local-live.yaml --env-file .humanish/local/provider.env
+npx humanish watch .humanish/studies/local-live.yaml --env-file .humanish/local/provider.env
 ```
 
 When choosing dogfood targets, prefer apps, CLIs, or agent-facing tools with a

package/skills/humanish/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "humanish CLI"
   short_description: "Set up public-safe persona simulation"
-  default_prompt: "Use $humanish to install humanish in this repo, scaffold synthetic personas and scenarios, run the safe Observer proof, and report the public-safe artifacts. If the app can run locally, start it on loopback and run a live scripted-browser lab (see https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios; set `scenario.mode: live` and keep `review.analysis: false`) before rendering Observer with `humanish watch --run latest`; do not treat `watch --sims` as app behavior proof."
+  default_prompt: "Use $humanish to install humanish in this repo, scaffold synthetic personas and scenarios, run the safe Observer proof, and report the public-safe artifacts. If the app can run locally, start it on loopback and run a live scripted study (see https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios; set `mode: live` and keep `review.analysis: false`) before opening the Observer with `humanish observe --run latest`; do not treat `watch --count` as app behavior proof."
 
 policy:
   allow_implicit_invocation: true

package/AGENTS.md

@@ -1,99 +0,0 @@
-# AGENTS.md
-
-humanish runs persona studies: AI participants use a target app, CLI or agent-facing flow on
-hosted or local desktops, and every run leaves a verifiable evidence bundle. Run bundles are the
-source of truth; the Observer is their review surface.
-
-Sub-guides take precedence inside their directories: [observer/](https://github.com/danielgwilson/humanish/blob/main/observer/AGENTS.md),
-[tui/](https://github.com/danielgwilson/humanish/blob/main/tui/AGENTS.md), [site/](https://github.com/danielgwilson/humanish/blob/main/site/AGENTS.md). The reasoning behind the rules below is in
-[docs/principles/engineering.md](docs/principles/engineering.md). [CONTEXT.md](CONTEXT.md) defines
-the domain terms, and [docs/decisions/](docs/decisions/README.md) records the decisions that
-shape the code.
-
-## Commands
-
-Node >= 22.19.0, pnpm 12 (`packageManager` pins the version).
-
-```bash
-pnpm install
-pnpm humanish <command>          # run the CLI from source (tsx src/cli.ts)
-pnpm vitest run tests/<file>     # one test file
-pnpm format                      # oxfmt; run before every commit
-pnpm check                       # the full local gate (below)
-pnpm release:check               # check + API proof + public-surface scan + skill check + pack; CI runs this
-```
-
-`pnpm check` runs format:check, lint (oxlint, type-aware), knip, prose:check, vocabulary:check,
-typecheck, the vitest suite, the TUI tests, build, the startup proofs and a TUI smoke test. After
-changing a CLI option, run `pnpm docs:generate`; CI fails on a stale `site/content/docs/cli.mdx`.
-Observer changes also need `pnpm build` and the four `observer:*:proof` scripts, which CI's observer
-job runs in Chromium. `pnpm api:proof` (after `pnpm build`) installs the packed tarball in a
-temporary project, compares its export names with `tests/golden/public-api.json` and runs
-`examples/`. After an intended export change, run `pnpm api:proof --update` and review the golden
-diff.
-
-Three counts are held to caps in package.json: oxlint warnings (`lint`, `--max-warnings`), comment
-prose (`prose:check`) and the retired words lane, seat, role, sim and study in `src/` identifiers
-(`vocabulary:check`). Each checker fails when a count is above its cap or below it, so the PR that
-reduces a count lowers its cap to the new count; the failure names the flag and the value. CI's
-`caps` workflow fails a PR that raises or removes a cap against the base branch, unless the PR has
-the `raise-cap` label and a `Cap raise:` line in its body that says why.
-
-## Layout
-
-[ARCHITECTURE.md](ARCHITECTURE.md#find-the-code-for-each-part-of-the-system) maps each folder to
-the file to read first. Keep these layout rules:
-
-- `src/index.ts` is the package's only library export surface. `src/cli.ts` is its bin.
-- `src/guest-runtime-main.ts`, `src/guest-runtime-revision.ts` and `src/guest-media-worker.ts`
-  stay at the root of `src/`. `scripts/guest-runtime-package.mjs` and the image recipes in
-  `runtime/` address their `dist/` output by file name. The rest of the guest runtime is in
-  `src/guest/`.
-
-## Conventions
-
-- TypeScript ESM with strict settings. No `any`; narrow `unknown` at the boundary.
-- Keep files under about 700 lines and functions under about 150 (oxlint warns past both). Split
-  when it helps a reader; do not add to `src/routes/computer-use/route.ts` or
-  `src/actors/computer-use/loop.ts` when a smaller module fits.
-- Comments say why the code is the way it is. History, incident narratives, issue archaeology and
-  PR numbers go in the commit message. `TODO(#123)` may link an open issue. No all-caps emphasis.
-  `prose:check` counts violations in `src/`.
-- Tests assert behavior. Do not pin prose in docs or comments with `toContain`. The default test
-  timeout is 20 s. Provider-API fixtures come from captured wire shapes.
-- New dependencies go in the pnpm catalog (`pnpm-workspace.yaml`) when more than one workspace
-  uses them. Stay on the latest release; a comment next to the entry gives the reason for any
-  older pin. knip fails on unused files, dependencies and exports.
-- CLI results are truthful: reject unsupported execution before side effects, and keep useful
-  evidence when a run is interrupted. Documented bundle schemas and artifact paths are contracts.
-
-## Public Boundary
-
-Assume this repository is public.
-
-- Never commit or publish secrets, PII/PHI, private customer data, private source, or raw
-  private transcripts or screenshots. Public examples are synthetic or redacted. Do not copy
-  credential files or secret values into evidence, comments, docs, issues or PRs.
-- Authorized local studies may keep private evidence in gitignored `.humanish/` under the
-  capture and redaction rules. Local capture is not publication permission. See the
-  [invariants](docs/principles/invariants-and-defaults.md) and the
-  [public-readiness standard](docs/release/public-readiness-standard.md).
-- Do not commit `.env*`, `.npmrc`, run bundles, runtime caches or packed tarballs.
-- Naming the owner's other projects, products or domains in public material needs explicit
-  sign-off. Use fictional examples. Named public third-party OSS study subjects are fine.
-
-## Working
-
-- Read the files in [CONTRIBUTING.md's reading order](CONTRIBUTING.md#read-these-in-order), then
-  the current task; read the contract for the boundary you are changing. Historical plans do not
-  authorize work.
-- Keep `main` clean: one worktree and branch per task, reviewable commits, squash merges.
-- Before adding a service, protocol, mode or framework, state the concrete need in the PR.
-  Prefer removing an unnecessary mechanism to documenting around it.
-- Verify in proportion to the change. Runtime changes need an execution check; claims of live
-  behavior need a retained run bundle, since dry runs do not establish live behavior. PRs say
-  what changed, what was checked and what was not.
-- With shipping authority: push, open the PR, address checks, merge when green, fast-forward
-  main and remove the worktree and branch. Releases follow the
-  [release procedure](docs/release/open-source-readiness.md). Stay on `0.x` until the maintainer
-  chooses 1.0; the minor after `0.99.0` is `0.100.0`.