humanish 0.110.1 → 0.110.3

package/dist/cli/commands/study-run.js

@@ -94,7 +94,7 @@ export async function runStudyCommand(args) {
     // checks (keys, runtime auth, subject env, the local agent, caps) refuse this machine, all before
     // the scorer loads, so none imports the scorer's host code. The scripted route's checks and the
     // run-id claim still come after it; the scripted route takes no scorer.
-    const routeRun = routeRunFor(route, { ...args, config });
+    const routeRun = ROUTE_RUNS[route]({ ...args, config });
     if (routeRun === undefined)
         return;
     // Every route's runStudyWith options carry the study's provenance, from here only.
@@ -155,24 +155,14 @@ function announcedKeyNames(config, options) {
     const planned = planStudy(config, { cwd: options.cwd, dryRun: false });
     return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
-/** The route's CLI setup. Undefined when the setup has already written its own result. */
-function routeRunFor(route, args) {
-    switch (route) {
-        case "preview":
-            return previewRouteRun(args);
-        case "computer-use":
-            return computerUseRouteRun(args);
-        case "scripted":
-            return scriptedRouteRun(args);
-        case "terminal":
-            return terminalRouteRun(args);
-        case "shared-world":
-            return sharedWorldRouteRun(args);
-        default:
-            // Compile-time exhaustiveness: a future route must be handled here, not silently no-op.
-            throw new Error(`Unhandled study route: ${String(route)}`);
-    }
-}
+/** Each route's CLI setup. It returns undefined when it has already written its own result. */
+const ROUTE_RUNS = {
+    preview: previewRouteRun,
+    "computer-use": computerUseRouteRun,
+    scripted: scriptedRouteRun,
+    terminal: terminalRouteRun,
+    "shared-world": sharedWorldRouteRun,
+};
 function studyRerunFlagsRequested(options) {
     return options.rerunFailedFrom !== undefined || options.participants !== undefined;
 }

package/dist/cli/commands/watch.js

@@ -5,7 +5,8 @@ import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
 import { addRunOptions, studyOnlyFlags } from "./run-command.js";
 import { applyEnvFileOption, collectRepeated, dotenvPathOf, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
-import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
+import { followDecision, followObserver, formatObserverHuman, unattendedObserverWarning, watchExposeRequested, } from "../observer-follow.js";
+import { cli } from "../invocation.js";
 export function registerWatchCommand(parent, io) {
     // A run's flags come from addRunOptions, the helper `run` uses, so the two cannot drift.
     addRunOptions(parent
@@ -23,6 +24,7 @@ export function registerWatchCommand(parent, io) {
         .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated)
         .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated)
         .option("--public-url <origin>", "Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.")
+        .addOption(new Option("--serve", "Serve the Observer and stay attached until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the result and an exit.").conflicts(["detach", "json"]))
         // Hidden: watch rejects --safe with a pointer to the library filter and to edge auth, which
         // a bare "unknown option" would lose.
         .addOption(new Option("--safe").hideHelp())
@@ -37,7 +39,7 @@ export function registerWatchCommand(parent, io) {
         "Watch a live computer-use run from your phone through an authenticated tunnel:",
         "  humanish watch my-browser-study --expose --tunnel ngrok --oauth google --allow-email you@example.com",
         "",
-        "Agent/CI path:",
+        "Agent/CI path (without an interactive terminal, watch prints the result and exits):",
         "  humanish watch --json --no-open",
         "",
         "Saved runs:",
@@ -84,7 +86,7 @@ async function handleWatch(io, named, parsed, command) {
     if (watchExposeRequested(options)) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "--expose/--tunnel/--oauth apply only to a live computer-use run; to expose finished evidence use `humanish observe --all --expose`.",
+            message: `--expose/--tunnel/--oauth apply only to a live computer-use run; to expose finished evidence use \`${cli("observe --all --expose")}\`.`,
         });
         return;
     }
@@ -107,7 +109,12 @@ async function handleWatch(io, named, parsed, command) {
         : options.open === true
             ? true
             : !wantsMachine && process.stdout.isTTY === true;
-    const wantsFollow = !wantsMachine && options.detach !== true;
+    const decision = followDecision({
+        wantsMachine,
+        detach: options.detach,
+        serve: options.serve,
+    });
+    const wantsFollow = decision.follow;
     const staticOpen = wantsFollow ? false : shouldOpen;
     const rendered = await renderWatchEvidence(io, command, options, target.requestedParticipantCount, staticOpen);
     if (rendered === undefined)
@@ -116,6 +123,7 @@ async function handleWatch(io, named, parsed, command) {
         follow: wantsFollow,
         open: shouldOpen,
         port: target.port,
+        unattended: decision.unattended,
     });
 }
 function refuseWatch(command, io, cwd, refusal) {
@@ -174,6 +182,8 @@ async function renderWatchEvidence(io, command, options, requestedParticipantCou
 async function reportWatch(io, command, rendered, serve) {
     let server = null;
     let result = rendered;
+    if (rendered.ok && serve.unattended)
+        result = { ...rendered, warnings: [...rendered.warnings, unattendedObserverWarning("watch")] };
     if (rendered.ok && serve.follow) {
         server = await serveObserver(rendered, { open: serve.open, port: serve.port });
         result = {

package/dist/cli/doctor.js

@@ -5,11 +5,12 @@ import path from "node:path";
 import { probeKeySources, } from "../keys/key-resolution.js";
 import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
-import { detectLocalAgents, localAgentDoctorMessage, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
+import { detectLocalAgents, localAgentDoctorMessage, localAgentReady, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
 import { leftoverClaudeTranscripts } from "../actors/local-agent/claude-participant.js";
 import { studySetupChecks, studiesByRequiredKey, } from "../study/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
+import { cli } from "./invocation.js";
 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
@@ -100,7 +101,7 @@ export async function doctor(cwdInput, options = {}) {
             {
                 name: "setup route",
                 ok: true,
-                message: "General capabilities only. Use humanish doctor --study <study> for the selected participant's requirements and separate analysis readiness.",
+                message: `General capabilities only. Use ${cli("doctor --study <study>")} for the selected participant's requirements and separate analysis readiness.`,
             },
         ]),
     ];
@@ -173,7 +174,7 @@ async function sourceCheck(projectRoot) {
         ok,
         message: ok
             ? "committed humanish/ source directory is present and safe to read"
-            : "no readable humanish/ source directory; run humanish init --yes",
+            : `no readable humanish/ source directory; run ${cli("init --yes")}`,
     };
 }
 async function runtimeIgnoreCheck(projectRoot) {
@@ -183,7 +184,7 @@ async function runtimeIgnoreCheck(projectRoot) {
         ok,
         message: ok
             ? ".gitignore lists .humanish/"
-            : ".gitignore does not list .humanish/; run humanish init --yes",
+            : `.gitignore does not list .humanish/; run ${cli("init --yes")}`,
     };
 }
 /**
@@ -271,7 +272,9 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
  * 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.
+ * of these signed in. An agent that cannot run participants (not signed in under the participant's
+ * environment, sign-in unknown, or a Claude Code below the floor) is a note; `--study` fails on it
+ * when the study selects that agent.
  */
 function localAgentChecks(agents) {
     if (agents.length === 0)
@@ -279,7 +282,7 @@ function localAgentChecks(agents) {
     return agents.map((agent) => ({
         name: `local agent ${agent.bin}`,
         ok: true,
-        ...(agent.authStatus === "authenticated" ? {} : { status: "note" }),
+        ...(localAgentReady(agent) ? {} : { status: "note" }),
         message: localAgentDoctorMessage(agent),
     }));
 }

package/dist/cli/findings.d.ts

@@ -75,6 +75,11 @@ interface FindingsSource {
     loaded: LoadedAnalysis;
     /** ` --cwd <dir>` when the commands this view names need it, or "". */
     cwdFlag: string;
+    /**
+     * The project-relative path of the run's study file when that file sets `review.analysis:
+     * false`, read when the view is built. Undefined when it does not, or cannot be read.
+     */
+    analysisOffIn?: string;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;

package/dist/cli/findings.js

@@ -7,9 +7,12 @@ import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
+import { studyProvenanceOf } from "../run/study-provenance.js";
+import { resolveStudyManifest } from "../study/discover.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText, wantsJson } from "./io.js";
+import { cli } from "./invocation.js";
 export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 function cwdFlag(cwd) {
@@ -18,7 +21,7 @@ function cwdFlag(cwd) {
     return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
 }
 function analyzeCommand(source, provider) {
-    const run = `humanish analyze --run ${source.runId}${source.cwdFlag}`;
+    const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
     return provider === "codex"
         ? `${run} --provider codex`
         : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
@@ -132,10 +135,10 @@ export function analysisFindings(source) {
         };
     }
     if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
-        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. humanish analyze show --run ${source.runId}${source.cwdFlag} --json prints the raw record.`, null);
+        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
     const job = loaded.automatic;
     if (job?.state === "queued" || job?.state === "running")
-        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", `humanish review --run ${source.runId}${source.cwdFlag}`);
+        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
     if (analysis && analysis.result === null)
         return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
     if (job?.state === "failed" || job?.state === "cancelled") {
@@ -149,9 +152,24 @@ export function analysisFindings(source) {
             : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
     }
     if (job !== undefined || loaded.state === "invalid")
-        return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", `humanish analyze list --run ${source.runId}${source.cwdFlag}`);
+        return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", cli(`analyze list --run ${source.runId}${source.cwdFlag}`));
+    if (source.analysisOffIn !== undefined)
+        return withoutFindings(source, "skipped", "AUTOMATIC_ANALYSIS_DISABLED", `Analysis is turned off in this run's study (review.analysis: false in ${source.analysisOffIn}), so none ran after the run. To analyze this run anyway, run the next command.`, analyzeCommand(source, undefined));
     return withoutFindings(source, "none", null, "No analysis has run for this run.", analyzeCommand(source, undefined));
 }
+/**
+ * The run's study file, project-relative, when it still names the same study and sets
+ * `review.analysis: false`. A study that turns analysis off leaves no analysis record, so the file
+ * is the only place that says why a live run has none.
+ */
+async function studyAnalysisOff(cwd, study) {
+    if (study?.path === undefined)
+        return undefined;
+    const resolved = await resolveStudyManifest(cwd, study.path).catch(() => null);
+    if (!resolved?.ok || resolved.config.id !== study.id)
+        return undefined;
+    return resolved.config.review?.analysis === false ? study.path : undefined;
+}
 /**
  * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
  * defaults to. Null when the run is missing or its storage is unsafe.
@@ -162,12 +180,16 @@ export async function readRunAnalysis(cwd, run, analysisId) {
     if (!prepared)
         return null;
     const bundle = await loadRunBundlePrepared(physical, prepared).catch(() => null);
+    const analysisOffIn = bundle?.bundle.mode === "live"
+        ? await studyAnalysisOff(physical, studyProvenanceOf(bundle.bundle))
+        : undefined;
     return {
         runId: runIdOf(prepared),
         mode: bundle?.bundle.mode,
         runRoot: prepared.relativeRunRoot,
         loaded: await loadAnalysis(prepared, analysisId),
         cwdFlag: cwdFlag(cwd),
+        ...(analysisOffIn === undefined ? {} : { analysisOffIn }),
     };
 }
 /** The view of a run that could not be found. */
@@ -179,7 +201,7 @@ export function missingRunFindings(cwd, run) {
         warnings: ["ANALYSIS_RUN_NOT_FOUND"],
     };
     const flag = cwdFlag(cwd);
-    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, `humanish runs${flag}`);
+    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, cli(`runs${flag}`));
 }
 /** The findings of a run's selected analysis, or why it has none. */
 export async function readRunFindings(cwd, run, analysisId) {
@@ -307,7 +329,7 @@ export async function writeRunFindings(command, io, cwd, result) {
         return;
     try {
         const view = await readRunFindings(cwd, result.runId, analysisId);
-        const full = `humanish review --run ${view.runId}${cwdFlag(cwd)}`;
+        const full = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
         io.writeOut(`${formatFindingsSummary(view, full).join("\n")}\n`);
     }
     catch {

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

@@ -25,10 +25,25 @@ export interface FirstRunEnvironment {
     hasProviderKey: boolean;
     /** The coding agents already signed in locally: Codex, Claude Code, or both. */
     localAgents: readonly SignedInAgent[];
-    /** Host shape only; `doctor --study local-browser` owns exact read-only readiness. */
+    /**
+     * init's quick read of this host for a local browser study: Linux x64 with `/dev/kvm`,
+     * `/dev/net/tun` and Docker,
+     * or an M3-or-newer Mac. Undefined when it was not read. `doctor --study local-browser` owns the
+     * full check.
+     */
+    localBrowserHost?: LocalBrowserHost;
+    /** Host shape only, for the prerequisites a local step names. */
     platform?: NodeJS.Platform;
-    arch?: string;
+    /** How a suggested command invokes humanish; `npx humanish` when unset. */
+    humanish?: string;
 }
+/** Whether this host passed init's quick checks for a local browser study, and why not. */
+export type LocalBrowserHost = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 export type FirstRunActor = "openai-computer-use" | "local-agent";
 /**
  * Which brain the starter live study should be written for. A machine with a signed-in coding agent
@@ -41,7 +56,7 @@ 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 that run local browser studies: Linux x64 and Apple Silicon Macs. */
+/** Host shapes the local browser route is built for: 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. */
@@ -50,14 +65,18 @@ export interface FirstRunStep {
     why: string;
 }
 /**
- * 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.
+ * The next two or three commands, in order: the dry run, the hosted try-live study when keys or a
+ * signed-in agent allow it, and the local browser study where this host passed its quick checks.
+ * Deliberately short: a list of twelve options is the same as no guidance, and the reader here has
+ * just been handed a directory of new files.
  */
 export declare function firstRunSteps(env: FirstRunEnvironment): FirstRunStep[];
 /** The block init prints after its changes. */
 export declare function firstRunGuidance(env: FirstRunEnvironment): string[];
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
+/** Starts humanish's section of `AGENTS.md`, on its heading line. */
 export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/** Ends humanish's section, so init can replace the section and nothing after it. */
+export declare const AGENTS_SECTION_END_MARKER = "<!-- /humanish:agents-guide -->";
 /**
  * What the next coding agent needs to know about humanish in this project.
  *
@@ -65,6 +84,7 @@ export declare const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
  * 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, because an agent acts on the commands it is given.
+ * Commands use `humanish`, the prefix init chose for where humanish is installed.
  */
-export declare function agentsSection(): string;
+export declare function agentsSection(humanish?: string): string;
 export {};

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

@@ -33,87 +33,111 @@ function preferredAgent(env) {
 export function starterLocalAgentFor(env) {
     return starterActorFor(env) === "local-agent" ? preferredAgent(env)?.id : undefined;
 }
-/**
- * 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.
- */
-const HUMANISH = "npx humanish";
-/** Hosts that run local browser studies: Linux x64 and Apple Silicon Macs. */
+/** Host shapes the local browser route is built for: 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
- * as no guidance, and the reader here has just been handed twenty files.
+ * The next two or three commands, in order: the dry run, the hosted try-live study when keys or a
+ * signed-in agent allow it, and the local browser study where this host passed its quick checks.
+ * Deliberately short: a list of twelve options is the same as no guidance, and the reader here has
+ * just been handed a directory of new files.
  */
 export function firstRunSteps(env) {
+    const humanish = env.humanish ?? "npx humanish";
     const steps = [
         {
-            command: `${HUMANISH} run first-run`,
+            command: `${humanish} run first-run`,
             why: "a dry run: no browser or model runs, no keys, no spend",
         },
     ];
-    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 --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;
+    const local = localBrowserStep(env, humanish);
+    const hostedRunnable = env.hasE2bKey && (env.hasProviderKey || env.localAgents.length > 0);
+    if (hostedRunnable) {
+        steps.push(hostedStep(env, humanish, ""));
+        if (local !== undefined)
+            steps.push(local);
     }
-    const localUnavailable = env.platform === undefined
-        ? ""
-        : " Local browsers are unavailable on this host; they support Linux x64 or M3-or-newer Apple Silicon Macs.";
-    if (!env.hasE2bKey) {
-        steps.push({
-            command: `${HUMANISH} keys set e2b`,
-            why: `the hosted starter needs an E2B desktop.${localUnavailable}`,
-        });
-        return steps;
+    else if (local !== undefined) {
+        steps.push(local);
     }
-    if (env.hasProviderKey || env.localAgents.length > 0) {
-        const brain = env.hasProviderKey
-            ? "your provider key"
-            : `${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.
-        if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
-            steps.push({
-                command: `${HUMANISH} doctor`,
-                why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
-            });
-            return steps;
-        }
-        const command = env.hasDesktopSdk
-            ? `${HUMANISH} run try-live`
-            : `${env.desktopPeerCommand} && ${HUMANISH} run try-live`;
-        steps.push({
-            command,
-            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"
-                    : "") +
-                localUnavailable,
-        });
-        return steps;
+    else {
+        steps.push(hostedStep(env, humanish, localUnavailableNote(env)));
     }
-    steps.push({
-        command: `${HUMANISH} keys set openai`,
-        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent" +
-            localUnavailable,
-    });
     return steps;
 }
+/** The local browser step, where the host passed init's checks and Codex is signed in. */
+function localBrowserStep(env, humanish) {
+    if (env.localBrowserHost?.ok !== true)
+        return undefined;
+    if (!env.localAgents.some((agent) => agent.id === "codex"))
+        return undefined;
+    const prerequisites = env.platform === "darwin"
+        ? "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";
+    return {
+        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`,
+    };
+}
+/** Why the local route is not offered, appended to a key step so the reader knows it was considered. */
+function localUnavailableNote(env) {
+    const host = env.localBrowserHost;
+    if (host === undefined)
+        return "";
+    if (!host.ok)
+        return ` Local browser studies are unavailable on this host: ${host.reason}.`;
+    return " A local browser study also runs on this host once Codex is signed in (`codex login`).";
+}
+/** The hosted try-live step, or the key or setup step it still needs. */
+function hostedStep(env, humanish, note) {
+    if (!env.hasE2bKey) {
+        return {
+            command: `${humanish} keys set e2b`,
+            why: `the hosted starter needs an E2B desktop.${note}`,
+        };
+    }
+    if (!env.hasProviderKey && env.localAgents.length === 0) {
+        return {
+            command: `${humanish} keys set openai`,
+            why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent." +
+                note,
+        };
+    }
+    const brain = env.hasProviderKey
+        ? "your provider key"
+        : `${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.
+    if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
+        return {
+            command: `${humanish} doctor`,
+            why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
+        };
+    }
+    // After the peer install, humanish is a dependency of this project, where `npx humanish` finds it.
+    const command = env.hasDesktopSdk
+        ? `${humanish} run try-live`
+        : `${env.desktopPeerCommand} && npx humanish run try-live`;
+    return {
+        command,
+        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"
+                : "") +
+            note,
+    };
+}
 /** The block init prints after its changes. */
 export function firstRunGuidance(env) {
     const steps = firstRunSteps(env);
     return ["", "next:", ...steps.flatMap((step) => [`  ${step.command}`, `      ${step.why}`])];
 }
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
+/** Starts humanish's section of `AGENTS.md`, on its heading line. */
 export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
+/** Ends humanish's section, so init can replace the section and nothing after it. */
+export const AGENTS_SECTION_END_MARKER = "<!-- /humanish:agents-guide -->";
 /**
  * What the next coding agent needs to know about humanish in this project.
  *
@@ -121,8 +145,23 @@ export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
  * 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, because an agent acts on the commands it is given.
+ * Commands use `humanish`, the prefix init chose for where humanish is installed.
  */
-export function agentsSection() {
+export function agentsSection(humanish = "npx humanish") {
+    const commands = [
+        ["study list --json", "the studies in this project"],
+        ["run first-run --no-open", "dry run: no browser, model, keys, or spend"],
+        ["doctor --study try-live", "what the hosted starter study still needs"],
+        [
+            "run try-live --no-open",
+            "demo app study: E2B plus the selected participant's authentication",
+        ],
+        ["doctor --study local-browser", "local Docker/Firecracker + Codex-account readiness"],
+        ["run local-browser --no-open", "your loopback app; no E2B or model API key"],
+        ["verify --run <id> --json", "is the evidence share-safe"],
+        ["review --run <id>", "the run's outcome and its analysis findings"],
+    ];
+    const width = Math.max(...commands.map(([command]) => command.length));
     return [
         "",
         `## humanish ${AGENTS_SECTION_MARKER}`,
@@ -130,30 +169,28 @@ export function agentsSection() {
         "This project uses humanish: synthetic participants use the product and leave evidence.",
         "",
         "```bash",
-        "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",
-        "humanish review --run <id>  # the run's outcome and its analysis findings",
+        ...commands.map(([command, why]) => `${humanish} ${command.padEnd(width)}  # ${why}`),
         "```",
         "",
-        "- After a live run, run `humanish review --run <id>` (or `--json`) and report its findings to the",
-        "  person you are working for: each one's title, impact, confidence, recovery and cited captures.",
-        "  When it shows no findings, report its message and the command it names.",
+        `- After a live run, run \`${humanish} review --run <id>\` (or \`--json\`) and report its findings`,
+        "  to the person you are working for: each one's title, impact, confidence, recovery and cited",
+        "  captures. When it shows no findings, report its message and the command it names. Every run",
+        "  prints its id; `latest` moves with each run, dry runs included.",
         "- 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",
+        `- 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` 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.",
+        `  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 commands`,
+        "  above instead, and tell the person you are working for that the TUI exists.",
         "- A live run spends money. `caps.maxUsd` in each study caps estimated model spend: the run",
         "  stops before its next request once the estimate passes it, so the last request can go over, and",
         "  hosted desktop time is billed on top. Do not raise it without asking the person you are working for.",
+        `- \`${humanish} init --yes\` rewrites this section, between its two markers, to match the installed`,
+        "  humanish. Write your own notes outside it.",
+        "",
+        AGENTS_SECTION_END_MARKER,
         "",
     ].join("\n");
 }

package/dist/cli/invocation.d.ts

@@ -0,0 +1,7 @@
+import { type HumanishInstall } from "../substrates/e2b/peer-install.js";
+/** The prefix for a suggested command, by install. */
+export declare function invocationFor(install: HumanishInstall, version: string): string;
+/** How this process's suggested commands invoke humanish, read once per process. */
+export declare function humanishCommand(): string;
+/** A suggested command: `cli("review --run x")` is `npx humanish review --run x` in a project. */
+export declare function cli(rest: string): string;

package/dist/cli/invocation.js

@@ -0,0 +1,32 @@
+// How the commands humanish suggests should invoke humanish, chosen from where the running copy is
+// installed. A dev-dependency install puts no `humanish` on `PATH`, so a bare name there reaches a
+// stale global install when one exists, or nothing. `npx humanish` with no version, run where no
+// project declares humanish, also resolves a global install before it fetches one. A one-shot run
+// therefore names its own version, so the next command runs the same CLI.
+import { humanishInstall } from "../substrates/e2b/peer-install.js";
+import { CLI_VERSION } from "./version.js";
+/** The prefix for a suggested command, by install. */
+export function invocationFor(install, version) {
+    switch (install.kind) {
+        case "project":
+        case "other":
+            return "npx humanish";
+        case "one-shot":
+            return `npx humanish@${version}`;
+        // A global install is on `PATH`. A source checkout runs through a link or `pnpm humanish`, and
+        // keeping the bare name there keeps test output the same on every machine.
+        case "global":
+        case "checkout":
+            return "humanish";
+    }
+}
+let cached;
+/** How this process's suggested commands invoke humanish, read once per process. */
+export function humanishCommand() {
+    cached ??= invocationFor(humanishInstall(), CLI_VERSION);
+    return cached;
+}
+/** A suggested command: `cli("review --run x")` is `npx humanish review --run x` in a project. */
+export function cli(rest) {
+    return `${humanishCommand()} ${rest}`;
+}