humanish 0.107.0 → 0.108.0

package/dist/cli/doctor.d.ts

@@ -2,6 +2,11 @@ import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
 import { type LabSetupCheckArgs } from "../lab/doctor.js";
 declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
+/**
+ * A row's verdict, as the human output prints it. A "note" is advisory: it never fails the run, so
+ * its `ok` is true. "not_checked" goes with `checked: false`.
+ */
+type DoctorStatus = "ok" | "missing" | "not_checked" | "note";
 export interface DoctorResult {
     schema: typeof DOCTOR_SCHEMA;
     ok: boolean;
@@ -9,14 +14,15 @@ export interface DoctorResult {
     checks: Array<{
         name: string;
         ok: boolean;
+        status: DoctorStatus;
         message: string;
         /**
-         * ADDITIVE + OPTIONAL. `false` means the check never ran — the directory could not be read, so
+         * Additive + optional. `false` means the check never ran: the directory could not be read, so
          * there is nothing to report about it either way. Absent means it ran and `ok` is its verdict.
          *
-         * It exists because a failed check and an unrun one used to render identically, and the unrun
-         * rows carried the SUCCESS text: a participant read `missing package.json: package.json is
-         * present and safe to read` off a real screen (labs/tui-self-study.yaml).
+         * It exists so a failed check and an unrun one render differently. Without it an unrun row
+         * shows the success text, such as `missing package.json: package.json is present and safe to
+         * read` (labs/tui-self-study.yaml).
          */
         checked?: boolean;
     }>;
@@ -25,11 +31,15 @@ export interface DoctorResult {
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
  * also requires an e2b release whose background command handle supports sendStdin and closeStdin,
  * which the optional speech transport needs. On older releases the CLI could stay alive minutes
- * past a written result (#581, measured 2026-09-04 on 2.2.3: twelve minutes).
+ * past a written result (measured 2026-09-04 on 2.2.3: twelve minutes).
  */
 export declare const DESKTOP_SDK_FLOOR = "2.3.2";
 /** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
 export declare function desktopSdkAdvisory(version: string | undefined): string | undefined;
+/** A row as a check writes it. Doctor derives `status`; an advisory row sets "note" itself. */
+export type DoctorCheckDraft = Omit<DoctorResult["checks"][number], "status"> & {
+    status?: "note";
+};
 export declare function doctor(cwdInput: string, options?: {
     lab?: string;
     env?: NodeJS.ProcessEnv;

package/dist/cli/doctor.js

@@ -3,8 +3,8 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { probeKeySources, } from "../keys/key-resolution.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
-import { detectLocalAgents, localAgentDoctorMessage, } from "../actors/local-agent/cli.js";
-import { labSetupChecks } from "../lab/doctor.js";
+import { detectLocalAgents, localAgentDoctorMessage, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
+import { labSetupChecks, studiesByRequiredKey } from "../lab/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
 const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
@@ -12,7 +12,7 @@ const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
  * also requires an e2b release whose background command handle supports sendStdin and closeStdin,
  * which the optional speech transport needs. On older releases the CLI could stay alive minutes
- * past a written result (#581, measured 2026-09-04 on 2.2.3: twelve minutes).
+ * past a written result (measured 2026-09-04 on 2.2.3: twelve minutes).
  */
 export const DESKTOP_SDK_FLOOR = "2.3.2";
 /** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
@@ -31,7 +31,7 @@ export function desktopSdkAdvisory(version) {
         (have[0] === floor[0] &&
             (have[1] < floor[1] || (have[1] === floor[1] && have[2] < floor[2])));
     return older
-        ? `@e2b/desktop ${version} is older than ${DESKTOP_SDK_FLOOR}, the supported floor for background command cleanup and stdin handles (older releases could keep the CLI alive minutes past its result, #581). Update with \`npm i -D @e2b/desktop@latest\`.`
+        ? `@e2b/desktop ${version} is older than ${DESKTOP_SDK_FLOOR}, the supported floor for background command cleanup and stdin handles (older releases could keep the CLI alive for minutes after its result). Update with \`npm i -D @e2b/desktop@latest\`.`
         : undefined;
 }
 /** The version of the @e2b/desktop that `import("@e2b/desktop")` resolves to from here, if readable. */
@@ -52,47 +52,46 @@ export async function doctor(cwdInput, options = {}) {
         .then((error) => error === null)
         .catch(() => false);
     if (!cwdOk) {
-        const checks = uncheckedProjectChecks("this directory does not exist, or humanish cannot read it", "not checked — the target directory could not be read");
-        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks };
+        const checks = uncheckedProjectChecks("this directory does not exist, or humanish cannot read it", "not checked: the target directory could not be read");
+        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks: withStatus(checks) };
     }
     let projectRoot;
     try {
         projectRoot = await prepareSelectedOutputDirectory(path.dirname(cwd), cwd);
     }
     catch {
-        const checks = uncheckedProjectChecks("target directory failed containment validation", "not checked — containment validation failed first");
-        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks };
+        const checks = uncheckedProjectChecks("target directory failed containment validation", "not checked: the containment check failed first");
+        return { schema: DOCTOR_SCHEMA, ok: false, cwd, checks: withStatus(checks) };
     }
     const env = options.env ?? process.env;
     const agents = await detectLocalAgents({ ...options.localAgents, env });
     const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.lab, options.keyDeps);
+    const keyPresent = (name) => probes.some((probe) => probe.name === name && probe.source !== null);
     const setup = options.lab
         ? await labSetupChecks({
             cwd,
             lab: options.lab,
             env,
             agents,
-            keyPresent: (name) => probes.some((probe) => probe.name === name && probe.source !== null),
+            keyPresent,
             ...(options.codexParticipantReadiness === undefined
                 ? {}
                 : { codexParticipantReadiness: options.codexParticipantReadiness }),
         })
         : undefined;
+    // Without --lab, each key row names the labs that need it instead of failing.
+    const keyUsers = setup ? undefined : await studiesByRequiredKey(cwd, keyPresent);
     const checks = [
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
         terminalSurfaceCheck(),
-        // The operator's own signed-in coding agent, reported as a CAPABILITY and never a gate: a
-        // machine with none is not broken, it just needs a provider key. This row exists because
-        // "go make an API key" is where most people trying humanish stop, and a developer very often
-        // already has one of these signed in.
-        { name: "local agents", ok: true, message: localAgentDoctorMessage(agents) },
-        ...keyChecks(probes, receivingKey, setup, agents),
+        ...localAgentChecks(agents),
+        ...keyChecks(probes, receivingKey, setup, keyUsers),
         ...(setup?.checks ?? [
             {
                 name: "setup route",
                 ok: true,
-                message: "General capabilities only. Use humanish doctor --lab <lab> for the selected participant's requirements and separate analysis readiness.",
+                message: "General capabilities only. Use humanish doctor --study <study> for the selected participant's requirements and separate analysis readiness.",
             },
         ]),
     ];
@@ -100,9 +99,15 @@ export async function doctor(cwdInput, options = {}) {
         schema: DOCTOR_SCHEMA,
         ok: checks.every((check) => check.ok),
         cwd,
-        checks,
+        checks: withStatus(checks),
     };
 }
+function withStatus(checks) {
+    return checks.map((check) => ({
+        ...check,
+        status: check.ok ? (check.status ?? "ok") : check.checked === false ? "not_checked" : "missing",
+    }));
+}
 /** The rows for a target directory doctor could not open: the failure, then three unrun checks. */
 function uncheckedProjectChecks(targetMessage, reason) {
     return [
@@ -147,23 +152,35 @@ async function projectChecks(projectRoot) {
                 };
             }
         })(),
-        {
-            name: "humanish source",
-            ok: await safeCheck(() => implicitProjectDirectoryExists(projectRoot, "humanish")),
-            message: "committed humanish/ source directory is present and safe to read",
-        },
-        {
-            name: "runtime ignore",
-            ok: await safeCheck(async () => (await readImplicitProjectFile(projectRoot, ".gitignore"))?.includes(".humanish/") ??
-                false),
-            message: ".gitignore safely contains .humanish/",
-        },
+        await sourceCheck(projectRoot),
+        await runtimeIgnoreCheck(projectRoot),
     ];
 }
+// Each row says what it found, and a failing one names the command that fixes it.
+async function sourceCheck(projectRoot) {
+    const ok = await safeCheck(() => implicitProjectDirectoryExists(projectRoot, "humanish"));
+    return {
+        name: "humanish source",
+        ok,
+        message: ok
+            ? "committed humanish/ source directory is present and safe to read"
+            : "no readable humanish/ source directory; run humanish init --yes",
+    };
+}
+async function runtimeIgnoreCheck(projectRoot) {
+    const ok = await safeCheck(async () => (await readImplicitProjectFile(projectRoot, ".gitignore"))?.includes(".humanish/") ?? false);
+    return {
+        name: "runtime ignore",
+        ok,
+        message: ok
+            ? ".gitignore lists .humanish/"
+            : ".gitignore does not list .humanish/; run humanish init --yes",
+    };
+}
 /**
- * The optional peer dep every live browser and terminal route needs (#346). `npx -y humanish` does
- * not pull optional peers, so an adopter's FIRST live run used to fail on it — safely and at $0,
- * but as a burned first impression on the flagship path. Answering it here means the readiness
+ * The optional peer dep every live browser and terminal route needs. `npx -y humanish` does not
+ * pull optional peers, so without this check an adopter's first live run fails on it, safely and at
+ * $0, but as a burned first impression on the flagship path. Answering it here means the readiness
  * command actually answers readiness.
  */
 async function desktopSdkCheck(setup) {
@@ -178,27 +195,30 @@ async function desktopSdkCheck(setup) {
     });
     const version = present ? await installedDesktopSdkVersion() : undefined;
     const advisory = desktopSdkAdvisory(version);
+    // Without --lab nothing selects a desktop route yet, so an absent SDK is advisory.
+    const advisoryOnly = !present && setup === undefined;
     return {
         name: "e2b desktop sdk",
-        ok: present || setup?.desktop === false,
+        ok: present || advisoryOnly || setup?.desktop === false,
+        ...(advisoryOnly ? { status: "note" } : {}),
         message: present
             ? `optional peer @e2b/desktop ${version ?? "(version unread)"} is installed; provider access is not tested${advisory === undefined ? "" : `. ${advisory}`}`
             : setup?.desktop === false
                 ? "optional peer @e2b/desktop is absent; not required by the selected route"
-                : "optional peer @e2b/desktop is NOT installed: dry runs work, but any live desktop participant will fail closed. Install it with `npm i -D @e2b/desktop`.",
+                : "optional peer @e2b/desktop is not installed: dry runs work, but a live run with a desktop participant fails when it starts. Install it with `npm i -D @e2b/desktop`.",
     };
 }
 /**
- * The stakeholder surface (#455). Reported as capability, never as a gate: the TUI is optional,
+ * The stakeholder surface. Reported as capability, never as a gate: the TUI is optional,
  * and `doctor` is itself mostly run by agents through a pipe, where a TTY requirement says
- * nothing about whether the PROJECT is ready. So this row is always ok.
+ * nothing about whether the project is ready. So this row is always ok.
  *
- * WHO IS READING decides the wording, and a real first-contact study
+ * Who is reading decides the wording, and a real first-contact study
  * (labs/first-contact.yaml) is why. An agent evaluating humanish read
  * "`humanish tui` is available in an interactive terminal", correctly concluded it was not in
- * one, and dropped it — then wrote a report FOR A HUMAN that never mentioned the human
+ * one, and dropped it, then wrote a report for a human that never mentioned the human
  * surface at all. Discovery worked; handoff did not. A capability described to a reader who
- * cannot use it has to be phrased as something to PASS ON, or it reads as "not for you" and
+ * cannot use it has to be phrased as something to pass on, or it reads as "not for you" and
  * dies there.
  */
 function terminalSurfaceCheck() {
@@ -207,6 +227,7 @@ function terminalSurfaceCheck() {
     return {
         name: "terminal surface",
         ok: true,
+        ...(supported && bundlePresent ? {} : { status: "note" }),
         message: terminalSurfaceMessage({
             supported,
             bundlePresent,
@@ -237,25 +258,59 @@ async function probeDoctorKeys(cwd, env, lab, keyDeps) {
     return { probes, receivingKey };
 }
 /**
- * Provider-key discovery (#436): which source supplies each live-run key, through the same
+ * The operator's own coding agents, one row each, reported as a capability and never a gate: a
+ * machine with none is not broken, it just needs a provider key. These rows exist because "go make
+ * an API key" is where most people trying humanish stop, and a developer very often already has one
+ * of these signed in. An agent that is installed but not signed in is a note.
+ */
+function localAgentChecks(agents) {
+    if (agents.length === 0)
+        return [{ name: "local agents", ok: true, message: NO_LOCAL_AGENT_MESSAGE }];
+    return agents.map((agent) => ({
+        name: `local agent ${agent.bin}`,
+        ok: true,
+        ...(agent.authStatus === "authenticated" ? {} : { status: "note" }),
+        message: localAgentDoctorMessage(agent),
+    }));
+}
+/** "try-live", "try-live and local-browser", "a, b and c". */
+function studyList(studies) {
+    return studies.length < 2
+        ? studies.join("")
+        : `${studies.slice(0, -1).join(", ")} and ${studies.at(-1)}`;
+}
+/**
+ * Provider-key discovery: which source supplies each live-run key, through the same
  * chain a live command resolves (env/--env-file, project overlay, vendor stores, the
  * humanish user store). Values never appear; sources and fill commands do.
+ *
+ * With --lab, a key the selected route requires fails when missing. Without it, `keyUsers` maps
+ * each key to the project's labs that need it, and a key row never fails: a missing key one of
+ * them needs is a note.
  */
-function keyChecks(probes, receivingKey, setup, agents) {
+function keyChecks(probes, receivingKey, setup, keyUsers) {
     return probes.map((probe) => {
         const present = probe.source !== null;
         const hint = probe.name === receivingKey
             ? `provide ${probe.name} through process env or --env-file`
             : probe.hint;
+        if (!setup) {
+            const users = keyUsers?.get(probe.name) ?? [];
+            const usedBy = users.length > 0 ? `used by ${studyList(users)}` : undefined;
+            return {
+                name: `key ${probe.name}`,
+                ok: true,
+                ...(present || usedBy === undefined ? {} : { status: "note" }),
+                message: present
+                    ? `supplied by ${probe.source}; presence only, validity not tested${usedBy ? `; ${usedBy}` : ""}`
+                    : `missing; ${usedBy ?? "not used by any lab in this project"}; ${hint}`,
+            };
+        }
         // GH_TOKEN is needed only for private clone subjects, so its absence is informational.
-        const required = setup
-            ? setup.keys.includes(probe.name)
-            : probe.name === "E2B_API_KEY" ||
-                (probe.name === "OPENAI_API_KEY" &&
-                    !agents.some((agent) => agent.authStatus === "authenticated"));
+        const required = setup.keys.includes(probe.name);
         // A key the lab is known not to read says so, so a present but unused key does not read as
         // one the run will use.
-        const unused = setup?.reads !== undefined && !setup.reads.has(probe.name);
+        const unused = setup.reads !== undefined && !setup.reads.has(probe.name);
         return {
             name: `key ${probe.name}`,
             ok: present || !required,
@@ -264,8 +319,8 @@ function keyChecks(probes, receivingKey, setup, agents) {
                     ? `present (${probe.source}), not used by this lab`
                     : `supplied by ${probe.source}; presence only, validity not tested`
                 : required
-                    ? `missing from every source — ${hint}`
-                    : `not required for ${setup ? "the selected participant route" : "every route"}; ${hint}`,
+                    ? `missing from every source; ${hint}`
+                    : `not required for the selected participant route; ${hint}`,
         };
     });
 }

package/dist/cli/first-run-path.d.ts

@@ -8,23 +8,23 @@ export interface FirstRunEnvironment {
     /** A sandbox to run the study in. Nothing live happens without it. */
     hasE2bKey: boolean;
     /**
-     * Whether `@e2b/desktop` resolves from this project. It is an OPTIONAL peer — the no-keys path
-     * does not need it — so a fresh `npx humanish` install does not have it, and a live run stops
+     * Whether `@e2b/desktop` resolves from this project. It is an optional peer: the no-keys path
+     * does not need it, so a fresh `npx humanish` install does not have it, and a live run stops
      * with "install this other package first". Found by running the published artifact cold, after
      * two local runs passed because they resolved the peer from the repo's own node_modules.
      */
     hasDesktopSdk: boolean;
     /**
      * Whether humanish itself is installed in this project rather than running from an npx cache.
-     * It changes what advice is TRUE: a one-shot `npx humanish` resolves its optional peer relative
-     * to itself, so "install the peer here" cannot work — humanish has to be installed alongside it.
+     * It changes what advice is true: a one-shot `npx humanish` resolves its optional peer relative
+     * to itself, so "install the peer here" cannot work; humanish has to be installed alongside it.
      */
     installedInProject: boolean;
     /** A provider API key for the model. */
     hasProviderKey: boolean;
     /** The coding agents already signed in locally: Codex, Claude Code, or both. */
     localAgents: readonly SignedInAgent[];
-    /** Host shape only; `doctor --lab local-browser` owns exact read-only readiness. */
+    /** Host shape only; `doctor --study local-browser` owns exact read-only readiness. */
     platform?: NodeJS.Platform;
     arch?: string;
 }
@@ -32,7 +32,7 @@ export type FirstRunActor = "openai-computer-use" | "local-agent";
 /**
  * Which brain the starter live lab should be written for. A machine with a signed-in coding agent
  * and no provider key can still do a real live run; writing the lab for the credential the
- * operator DOESN'T have is how a starter file becomes homework.
+ * operator doesn't have is how a starter file becomes homework.
  */
 export declare function starterActorFor(env: FirstRunEnvironment): FirstRunActor;
 /**
@@ -40,6 +40,8 @@ export declare function starterActorFor(env: FirstRunEnvironment): FirstRunActor
  * refuse to run on a machine where only Claude Code is signed in.
  */
 export declare function starterLocalAgentFor(env: FirstRunEnvironment): LocalAgentId | undefined;
+/** Hosts the local browser lab runs on: Linux x64 and Apple Silicon Macs. */
+export declare function supportsLocalBrowser(platform: NodeJS.Platform | undefined, arch: string | undefined): boolean;
 export interface FirstRunStep {
     /** The exact command to run. */
     command: string;
@@ -47,7 +49,7 @@ export interface FirstRunStep {
     why: string;
 }
 /**
- * The next one or two commands, in order. Deliberately SHORT: a list of twelve options is the same
+ * The next one or two commands, in order. Deliberately short: a list of twelve options is the same
  * as no guidance, and the reader here has just been handed twenty files.
  */
 export declare function firstRunSteps(env: FirstRunEnvironment): FirstRunStep[];
@@ -56,12 +58,12 @@ export declare function firstRunGuidance(env: FirstRunEnvironment): string[];
 /** Lets init recognise its own section without rewriting a file someone else wrote. */
 export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
 /**
- * What the NEXT coding agent needs to know about humanish in this project.
+ * What the next coding agent needs to know about humanish in this project.
  *
- * AGENTS.md is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
+ * `AGENTS.md` is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
  * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
  * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
- * is for. Deliberately SHORT and command-first: an agent acts on commands, not on prose.
+ * is for. Deliberately short and command-first, because an agent acts on the commands it is given.
  */
 export declare function agentsSection(): string;
 export {};

package/dist/cli/first-run-path.js

@@ -1,21 +1,21 @@
-// What a person — or the coding agent setting humanish up for them — should do NEXT.
+// What a person, or the coding agent setting humanish up for them, should do next.
 //
-// WHY: `humanish init` wrote twenty files and stopped. The only lab that could actually run was a
+// Why: `humanish init` wrote twenty files and stopped. The only lab that could actually run was a
 // $0 dry run; the two live ones were templates with `your-org/your-app` in them, so the first live
 // run a newcomer tried could not succeed no matter what credentials they had. Three independent
-// sources reached the same place — a participant in our own TUI study walked to the Start row and
+// sources reached the same place: a participant in our own TUI study walked to the Start row and
 // found a placeholder URL, an adoption review concluded "the funnel is broken at the first live
 // run", and the release-gate participant said, unprompted, "validate one paid live study before
-// committing" (#505).
+// committing".
 //
 // The fix is not more surface. Increasingly the thing running `init` is a coding agent acting for
 // someone, and an agent reads stdout and does what it says. So init ends by naming the next
-// command — and names the one that will actually work ON THIS MACHINE, because a next step that
+// command, and names the one that will actually work on this machine, because a next step that
 // fails is worse than none.
 /**
  * Which brain the starter live lab should be written for. A machine with a signed-in coding agent
  * and no provider key can still do a real live run; writing the lab for the credential the
- * operator DOESN'T have is how a starter file becomes homework.
+ * operator doesn't have is how a starter file becomes homework.
  */
 export function starterActorFor(env) {
     if (!env.hasProviderKey && env.localAgents.length > 0)
@@ -35,29 +35,31 @@ export function starterLocalAgentFor(env) {
 }
 /**
  * How each hint invokes the CLI. \`npx humanish\` works from a project install and from an npx cache;
- * a dev-dependency install puts no \`humanish\` on PATH, so a bare name can reach a stale global one.
+ * a dev-dependency install puts no \`humanish\` on \`PATH\`, so a bare name can reach a stale global one.
  */
 const HUMANISH = "npx humanish";
+/** Hosts the local browser lab runs on: Linux x64 and Apple Silicon Macs. */
+export function supportsLocalBrowser(platform, arch) {
+    return (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
+}
 /**
- * The next one or two commands, in order. Deliberately SHORT: a list of twelve options is the same
+ * The next one or two commands, in order. Deliberately short: a list of twelve options is the same
  * as no guidance, and the reader here has just been handed twenty files.
  */
 export function firstRunSteps(env) {
     const steps = [
         {
             command: `${HUMANISH} run first-run`,
-            why: "an evidence preview: no browser or model runs, no keys, no spend",
+            why: "a dry run: no browser or model runs, no keys, no spend",
         },
     ];
-    const localPlatform = (env.platform === "linux" && env.arch === "x64") ||
-        (env.platform === "darwin" && env.arch === "arm64");
-    if (localPlatform) {
+    if (supportsLocalBrowser(env.platform, env.arch)) {
         const prerequisites = env.platform === "darwin"
             ? "M3-or-newer Mac, native ARM64 Node, Lima 2.2+, and a supported signed-in Codex CLI"
             : "local rootful Docker, KVM, TUN, and a supported signed-in Codex CLI";
         steps.push({
-            command: `${HUMANISH} doctor --lab local-browser`,
-            why: `check the local browser lab (${prerequisites}); no resources or quota used. Run \`${HUMANISH} runtime setup\` to prepare it, then start your app and run \`${HUMANISH} run local-browser\`; no E2B or model API key`,
+            command: `${HUMANISH} doctor --study local-browser`,
+            why: `check the local browser study (${prerequisites}); no resources or quota used. Run \`${HUMANISH} runtime setup\` to prepare it, then start your app and run \`${HUMANISH} run local-browser\`; no E2B or model API key`,
         });
         return steps;
     }
@@ -74,7 +76,7 @@ export function firstRunSteps(env) {
     if (env.hasProviderKey || env.localAgents.length > 0) {
         const brain = env.hasProviderKey
             ? "your provider key"
-            : `${preferredAgent(env)?.label} (already signed in — no API key needed)`;
+            : `${preferredAgent(env)?.label} (already signed in, so no API key is needed)`;
         // Everything the step needs, in one line. Splitting it across two commands means the second
         // one fails, which is the same dead end this guidance exists to remove.
         const command = env.hasDesktopSdk
@@ -86,7 +88,7 @@ export function firstRunSteps(env) {
                     `npm i -D humanish @e2b/desktop && ${HUMANISH} run try-live`;
         steps.push({
             command,
-            why: `a REAL study: one participant drives a real app in a hosted desktop, using ${brain}` +
+            why: `a live study: one participant drives a real app in a hosted desktop, using ${brain}` +
                 (env.hasDesktopSdk ? "" : " (the desktop SDK is an optional peer, so it installs first)") +
                 (!env.hasProviderKey
                     ? "; automatic findings analysis is skipped without OPENAI_API_KEY"
@@ -110,12 +112,12 @@ export function firstRunGuidance(env) {
 /** Lets init recognise its own section without rewriting a file someone else wrote. */
 export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
 /**
- * What the NEXT coding agent needs to know about humanish in this project.
+ * What the next coding agent needs to know about humanish in this project.
  *
- * AGENTS.md is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
+ * `AGENTS.md` is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
  * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
  * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
- * is for. Deliberately SHORT and command-first: an agent acts on commands, not on prose.
+ * is for. Deliberately short and command-first, because an agent acts on the commands it is given.
  */
 export function agentsSection() {
     return [
@@ -125,22 +127,22 @@ export function agentsSection() {
         "This project uses humanish: synthetic participants use the product and leave evidence.",
         "",
         "```bash",
-        "humanish doctor --lab try-live  # requirements for the selected participant and analysis",
-        "humanish lab list --json   # the labs in this project",
-        "humanish run first-run     # evidence preview only: no browser, model, keys, or spend",
-        "humanish doctor --lab local-browser  # local Docker/Firecracker + Codex-account readiness",
+        "humanish doctor --study try-live  # requirements for the selected participant and analysis",
+        "humanish study list --json # the studies in this project",
+        "humanish run first-run     # dry run: no browser, model, keys, or spend",
+        "humanish doctor --study local-browser  # local Docker/Firecracker + Codex-account readiness",
         "humanish run local-browser # your loopback app; no E2B or model API key",
         "humanish run try-live      # demo app study: E2B plus the selected participant's authentication",
         "humanish verify --run latest --json   # is the evidence share-safe",
         "```",
         "",
-        "- Labs are declared in `humanish/labs/*.yaml`. Edit `try-live.yaml`'s `subject` to point at",
-        "  this project's own app once you have seen a run work.",
-        "- Configure the local lab without editing YAML: `humanish init --yes --local-browser",
+        "- Studies are declared in `humanish/studies/*.yaml`. Edit `try-live.yaml`'s `subject` to point",
+        "  at this project's own app once you have seen a run work.",
+        "- Configure the local study without editing YAML: `humanish init --yes --local-browser",
         '  http://127.0.0.1:3000 --local-mission "Complete the primary flow"` on first setup.',
         "- Evidence lands in gitignored `.humanish/runs/`. Never commit it, and never paste raw run",
-        "  bundles into an issue — `humanish feedback issue` produces a redacted, share-safe draft.",
-        "- `humanish tui` is a HUMAN surface and refuses to run in an agent session. Use the `--json`",
+        "  bundles into an issue; `humanish feedback issue` writes a redacted, share-safe draft.",
+        "- `humanish tui` is for people and refuses to run in an agent session. Use the `--json`",
         "  commands above instead, and tell the person you are working for that `humanish tui` exists.",
         "- A live run spends money. `execution.caps.maxUsd` in each lab caps estimated model spend: the run",
         "  stops before its next request once the estimate passes it, so the last request can go over, and",

package/dist/cli/io.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { type TelemetryProperties } from "./telemetry.js";
 import type { RunResult } from "../run/results.js";
@@ -11,6 +11,12 @@ export interface CliIo {
     keyDiscovery?: typeof discoverProviderKeys;
 }
 export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
+export declare const CWD_OPTION_DESCRIPTION = "Project directory.";
+export declare const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
+export declare const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export declare const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
+/** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
+export declare function freePortOption(): Option;
 export interface LabCommandOptions {
     count?: string | undefined;
     cwd: string;
@@ -23,7 +29,7 @@ export interface LabCommandOptions {
     port?: string | undefined;
     rerunFailedFrom?: string | undefined;
     runId?: string | undefined;
-    /** #316: repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
+    /** Repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
     scorer?: string | undefined;
     expose?: boolean | undefined;
     tunnel?: "ngrok" | undefined;
@@ -48,7 +54,7 @@ export declare function applyEnvFileOption(args: {
     discoverKeys?: boolean;
 }): Promise<boolean>;
 /**
- * Provider-key discovery (#436): fill still-missing keys from the documented project overlay, the
+ * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
  * --env-file or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
@@ -63,11 +69,36 @@ export declare function discoverCliKeys(args: {
 }): Promise<void>;
 export declare function parseLabCount(value: string | undefined, fallback: number): number | null;
 export declare function parseParticipantIds(value: string | undefined): string[];
-export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => string): void;
+/** An error as a result carries it. A result with only a message, such as keys or comms, has no code. */
+export interface CliError {
+    code?: string;
+    message: string;
+}
+/**
+ * What a human formatter prints: text for stdout, or stdout lines plus an error that writeResult
+ * prints on stderr through formatCliError. --json output never goes through it.
+ */
+export type HumanOutput = string | {
+    stdout?: string;
+    error?: CliError | undefined;
+};
+/** `<command> failed: <message>`, then `code: <CODE>`, then `next: <command>` when one is known. */
+export declare function formatCliError(command: string, error: CliError): string;
+/** A result whose human output is its message: stdout when it passed, stderr when it failed. */
+export declare function messageOutput(value: {
+    ok: boolean;
+    message: string;
+}): HumanOutput;
+/** A failed result's human output: its error on stderr and nothing on stdout. */
+export declare function humanError(error: CliError | undefined): HumanOutput;
+/** Prints a human formatter's output: text to stdout, an error to stderr through formatCliError. */
+export declare function writeHuman(command: Command, io: CliIo, human: HumanOutput): void;
+export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => HumanOutput): void;
 export declare function noteRunFacts(command: Command, facts: TelemetryProperties): void;
 /** Exported for tests: the facts writeResult read off a command's result document. */
 export declare function runFactsFor(command: Command): TelemetryProperties;
-export declare function formatRunHuman(result: RunResult): string;
+/** A run result, or the preview route's study result: they differ only in `schema`. */
+export declare function formatRunHuman(result: Omit<RunResult, "schema">): HumanOutput;
 export declare function parsePositiveInteger(value: string): number | null;
 export declare function parseTimeoutMs(value: string): number | null;
 export declare function parseObserverPort(value: string): number | null;
@@ -81,6 +112,10 @@ export declare function candidateOption(options: {
     analysis?: string;
     finding?: string;
 };
-export declare function collectRepeated(value: string, previous: string[]): string[];
+export declare function collectRepeated(value: string, previous?: string[]): string[];
 export declare function wantsJson(command: Command): boolean;
+export declare function analysisOutcomeText(analysis: {
+    state: string;
+    reason: string | null;
+}): string;
 export declare function automaticAnalysisEnvelope<T>(result: T): T;