humanish 0.106.1 → 0.108.0

package/dist/cli/commands/runs.js

@@ -1,146 +1,60 @@
+import path from "node:path";
 import { Command, Option } from "commander";
+import { shellQuote } from "../../substrates/shell.js";
 import { computeStats, formatStatsHuman } from "../../run/stats.js";
 import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../feedback/export.js";
 import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
-import { runDryRun } from "../../run/dry-run.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
-import { runLabCommand } from "./lab-run.js";
-import { applyEnvFileOption, formatRunHuman, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
-const SCRIPTED_BROWSER_DOCS_URL = "https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios";
+import { addRunOptions, handleRun } from "./run-command.js";
+import { oldStudyOption, studyOptionValue } from "../deprecations.js";
+import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 export function registerRunCommand(parent, io) {
-    parent
+    addRunOptions(parent
         .command("run")
-        .argument("[lab]", "Optional lab id or .yaml path.")
-        .description("Run a lab (or a synthetic dry-run bundle). The everyday command.")
-        .summary("Run a persona/scenario simulation or dry-run bundle.")
-        .option("--dry-run", "Generate contract proof without browser, keys, or provider spend.")
-        // `humanish run <lab>` and `humanish lab run <lab>` are the SAME operation on the same
-        // dispatcher, but this one used to forward four options while its sibling forwarded all of
-        // them — so `humanish run first-run --no-open` failed while `lab run` accepted it. A
-        // participant hit exactly that and filed it as a documentation mismatch. Same command, same
-        // flags (CLIG: "be consistent across subcommands").
-        .option("--open", "Open the observer in the default browser.")
-        .option("--no-open", "Render without opening a browser.")
-        .option("--detach", "Render/open once and exit without an attached watch server.")
-        .option("--port <port>", "Local observer server port when following.", "0")
-        .option("--sims <count>", "Simulation count. A dry run accepts any positive count.")
-        // Agents with an older installed skill still send --app-url. Accepting it hidden lets the
-        // refusal name the replacement; commander's bare unknown-option error names nothing. Delete
-        // after 0.106.x.
-        .addOption(new Option("--app-url <url>").hideHelp())
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load a local env file for this run without persisting values.")
-        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
-        .action(async (lab, options, command) => {
-        if (options.appUrl !== undefined) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: options.cwd,
-                warnings: [],
-                error: {
-                    code: "HUMANISH_APP_URL_REMOVED",
-                    message: `--app-url was removed. To drive an app on a loopback URL, write a scripted-browser lab and run \`humanish run <lab>\`: ${SCRIPTED_BROWSER_DOCS_URL}`,
-                },
-            };
-            writeResult(command, io, result, formatRunHuman);
-            io.setExitCode(2);
-            return;
-        }
-        if (!(await applyEnvFileOption({
-            command,
-            cwd: options.cwd,
-            envFile: options.envFile,
-            io,
-            // runLabCommand discovers keys for a live lab; the lab-less preview needs none.
-            discoverKeys: false,
-        }))) {
-            return;
-        }
-        if (lab) {
-            await runLabCommand({
-                command,
-                io,
-                lab,
-                mode: "run",
-                // Forwarded wholesale, exactly as `lab run` does. Cherry-picking a subset here is what
-                // made the two commands disagree in the first place.
-                options: options,
-            });
-            return;
-        }
-        const participantCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
-        if (options.sims !== undefined && participantCount === null) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: options.cwd,
-                warnings: [],
-                error: {
-                    code: "HUMANISH_INVALID_SIM_COUNT",
-                    message: "--sims must be a positive integer.",
-                },
-            };
-            writeResult(command, io, result, formatRunHuman);
-            io.setExitCode(2);
-            return;
-        }
-        const result = await runDryRun({
-            cwd: options.cwd,
-            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
-            ...(options.runId === undefined ? {} : { runId: options.runId }),
-            ...(participantCount === undefined || participantCount === null
-                ? {}
-                : { simCount: participantCount }),
-            // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
-            // produced it (#597). A render failure is a warning on the result.
-            observer: { open: false },
-        });
-        writeResult(command, io, result, formatRunHuman);
-        io.setExitCode(result.ok ? 0 : 2);
-    });
+        .argument("[study]", "Optional study id or .yaml path.")
+        .description("Run a study, as a dry run or with live participants. This is the everyday command.")
+        .summary("Run a study, as a dry run or with live participants.")).action((study, options, command) => handleRun(io, study, options, command));
 }
 export function registerVerifyCommand(parent, io) {
     parent
         .command("verify")
-        .description("Validate a run bundle and public-safety gates.")
-        .summary("Validate a run bundle and public-safety gates.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Check a run's evidence and share safety.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--verbose", "Print every check, passing ones included.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const result = await verifyRun(options.cwd, options.run);
-        writeResult(command, io, result, formatVerifyHuman);
+        writeResult(command, io, result, (value) => options.verbose ? formatVerifyVerbose(value) : formatVerifyHuman(value));
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
 export function registerCleanupCommand(parent, io) {
     parent
         .command("cleanup")
-        .description("Inspect recorded resource evidence and write cleanup.json; stored ids do not authorize provider mutation.")
-        .summary("Write a resource cleanup inspection receipt.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Check a run's recorded resources and write cleanup.json. It stops nothing; humanish reclaim stops leftover sandboxes.")
+        .summary("Check that a run's resources were stopped.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const result = await cleanupRun(options.cwd, options.run);
-        writeResult(command, io, result, formatCleanupHuman);
+        writeResult(command, io, result, (value) => formatCleanupHuman(value, options.cwd));
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
 export function registerReviewCommand(parent, io) {
     parent
         .command("review")
-        .description("Build a review packet from verified run evidence.")
+        .description("Show a run's review: verdict, summary and gaps.")
         .summary("Build a review packet from verified run evidence.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const result = await readReview(options.cwd, options.run);
-        writeResult(command, io, result, (value) => `${JSON.stringify(value, null, 2)}\n`);
+        writeResult(command, io, result, formatReviewHuman);
         io.setExitCode("ok" in result && result.ok === false ? 2 : 0);
     });
 }
@@ -148,16 +62,16 @@ export function registerExportCommand(parent, io) {
     parent
         .command("export")
         .description("Export a run as self-contained Observer HTML, or a separately verified redacted bundle workspace. HTML requires share_ready unless --local-only; bundle format requires --redact-screenshots and preserves the original.")
-        .summary("Export Observer HTML or a redacted bundle workspace.")
-        .option("--run <id>", "Run id or 'latest'.", "latest")
+        .summary("Export a run as an Observer page or redacted bundle.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--format <format>", "Output format; bundle creates a new standalone workspace.")
         .choices(["html", "bundle"])
         .default("html"))
         .option("--redact-screenshots", "Bundle only: blur PNG screenshots in a verified copy; keep original evidence unchanged.")
         .option("--out <path>", "HTML file or new bundle workspace. Default: .humanish/exports/<runId>.html or <runId>-redacted/.")
-        .option("--local-only", "Export a bundle that is not share_ready, with a LOCAL ONLY banner in the file.")
-        .option("--max-bytes <n>", "Refuse an export larger than this.", String(DEFAULT_EXPORT_MAX_BYTES))
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--local-only", 'Export a bundle that is not share_ready, with a "Local only" banner in the file.')
+        .addOption(new Option("--max-bytes <n>", "Refuse an export larger than this many bytes.").default(String(DEFAULT_EXPORT_MAX_BYTES), `${DEFAULT_EXPORT_MAX_BYTES / 1024 / 1024} MB`))
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const maxBytes = options.format === "bundle"
@@ -182,14 +96,16 @@ export function registerStatsCommand(parent, io) {
     parent
         .command("stats")
         .description("Cost, outcome, and duration roll-ups across run history. Estimates stay labelled; unknown costs count as unknown.")
-        .summary("Roll up cost, outcomes, and durations across runs.")
-        .option("--lab <id>", "Only runs from this lab id.")
+        .summary("Show cost, outcomes and durations across runs.")
+        .option("--study <id>", "Only runs of this study id.")
+        .addOption(oldStudyOption("id"))
         .option("--since <date>", "Only runs that started on or after this ISO date or datetime.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
+        const study = studyOptionValue(command, io, options);
         const result = await computeStats(options.cwd, {
-            ...(options.lab === undefined ? {} : { lab: options.lab }),
+            ...(study === undefined ? {} : { lab: study }),
             ...(options.since === undefined ? {} : { since: options.since }),
         });
         writeResult(command, io, result, formatStatsHuman);
@@ -199,9 +115,8 @@ export function registerStatsCommand(parent, io) {
 export function registerRunsCommand(parent, io) {
     parent
         .command("runs")
-        .description("List local humanish runs and latest pointers.")
-        .summary("List local humanish runs and latest pointers.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("List this project's runs and which one is latest.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const result = await listRuns(options.cwd);
@@ -253,10 +168,10 @@ export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
         .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment.")
-        .summary("Reclaim an interrupted run's sandboxes by recorded id.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--run <id>", "Run id, or 'latest'.", "latest")
-        .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish lab preflight` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
+        .summary("Stop an interrupted run's leftover sandboxes.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const result = options.preflight
@@ -274,36 +189,122 @@ function formatReclaimHuman(result) {
     }
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);
-    if (result.error)
-        lines.push(`  error: ${result.error.message}`);
-    return lines.join("\n");
+    const stdout = lines.join("\n");
+    return result.error === undefined ? stdout : { stdout: `${stdout}\n`, error: result.error };
+}
+const REVIEW_VERDICTS = {
+    // A dry run, or a live run with no participant result; review's result does not carry the mode.
+    contract_proof_only: "no verdict; no product behavior was tested",
+    pass: "pass",
+    fail: "fail",
+    blocked: "blocked",
+    timed_out: "timed out",
+};
+/** A run's review: its verdict, summary and gaps, and where review.json is. */
+function formatReviewHuman(result) {
+    if (!("verdict" in result)) {
+        // A run that did not pass verify has no review to show; verify says why.
+        const error = result.error ?? {
+            code: "HUMANISH_INVALID_RUN_BUNDLE",
+            message: "Run bundle failed verification.",
+        };
+        return error.code === "HUMANISH_INVALID_RUN_BUNDLE"
+            ? {
+                error: {
+                    ...error,
+                    message: `${error.message} humanish verify --run ${result.run} shows why.`,
+                },
+            }
+            : humanError(error);
+    }
+    return ([
+        `humanish review ${result.runId}: ${REVIEW_VERDICTS[result.verdict]}`,
+        "",
+        result.summary,
+        ...(result.gaps.length === 0 ? [] : ["", "gaps:", ...result.gaps.map((gap) => `- ${gap}`)]),
+        "",
+        `review: ${result.path}`,
+    ].join("\n") + "\n");
+}
+/** The run id verify read, from the bundle path, so `latest` prints as the id it points at. */
+function verifiedRunId(result) {
+    return result.bundlePath === undefined
+        ? result.run
+        : path.basename(path.dirname(result.bundlePath));
 }
+/** Share-safety reasons, except VERIFY_FAILED, which the failing checks above it already say. */
+function shareSafetyLines(result) {
+    return result.shareSafety.reasons
+        .filter((reason) => reason.code !== "VERIFY_FAILED")
+        .map((reason) => `share-safety: ${reason.code}: ${reason.message}`);
+}
+/**
+ * One line for a pass. A failure lists only the failing checks. `--verbose` prints every check.
+ * A run that does not exist prints only that.
+ */
 function formatVerifyHuman(result) {
+    if (result.error?.code === "HUMANISH_RUN_NOT_FOUND")
+        return humanError(result.error);
+    const runId = verifiedRunId(result);
+    const total = result.checks.length;
+    const failed = result.checks.filter((check) => !check.ok);
+    const lines = result.ok
+        ? [`verified ${runId} · ${result.shareSafety.status} · ${total} checks passed`]
+        : [
+            `verify failed: ${runId} · ${result.shareSafety.status} · ${failed.length} of ${total} checks failed`,
+            ...failed.map((check) => `- ${check.message}`),
+        ];
+    lines.push(...shareSafetyLines(result), ...result.warnings.map((warning) => `warning: ${warning}`));
+    const cwdFlag = result.cwd === process.cwd() ? "" : ` --cwd ${result.cwd}`;
+    if (!result.ok)
+        lines.push(`every check: humanish verify --run ${runId}${cwdFlag} --verbose`);
+    return `${lines.join("\n")}\n`;
+}
+function formatVerifyVerbose(result) {
+    if (result.error?.code === "HUMANISH_RUN_NOT_FOUND")
+        return humanError(result.error);
     return ([
         `humanish verify ${result.ok ? "passed" : "failed"}`,
-        `run: ${result.run}`,
+        `run: ${verifiedRunId(result)}`,
         `share-safety: ${result.shareSafety.status}`,
         ...result.shareSafety.reasons.map((reason) => `share-safety reason: ${reason.code}: ${reason.message}`),
         ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
 }
-function formatCleanupHuman(result) {
-    if (!result.ok && result.error) {
-        return `${result.error.code}: ${result.error.message}\n`;
-    }
+/** A command-line argument, single-quoted only when the shell would split or expand it. */
+function shellArg(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
+}
+/**
+ * Cleanup only reads evidence and never stops a sandbox. A failed resource is an E2B sandbox not
+ * recorded as stopped, which reclaim can stop from the run's sandbox receipts, so the last line
+ * names it. A skipped resource is a provider reclaim does not handle, so it gets no line. `cwd` is
+ * the --cwd the command was given, since cleanup's result masks it.
+ */
+function reclaimPointer(result, cwd) {
+    if (result.runId === undefined || result.summary.failed === 0)
+        return [];
+    const cwdFlag = cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`;
+    return [
+        `To stop leftover sandboxes, run humanish reclaim --run ${shellArg(result.runId)}${cwdFlag}.`,
+    ];
+}
+function formatCleanupHuman(result, cwd) {
+    if (!result.ok && result.error)
+        return humanError(result.error);
     return ([
         `humanish cleanup ${result.ok ? "passed" : "failed"}`,
         `run: ${result.runId ?? result.run}`,
         `resources: already-clean ${result.summary.alreadyClean}, skipped ${result.summary.skipped}, failed ${result.summary.failed}`,
         ...(result.cleanupPath ? [`cleanup: ${result.cleanupPath}`] : []),
         ...result.warnings.map((warning) => `warning: ${warning}`),
+        ...reclaimPointer(result, cwd),
     ].join("\n") + "\n");
 }
 function formatRunsHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     if (result.runs.length === 0) {
         return `No humanish runs found in ${result.cwd}\n`;
     }

package/dist/cli/commands/setup.d.ts

@@ -3,9 +3,9 @@ import { type CliIo } from "../io.js";
 export declare function registerInitCommand(parent: Command, io: CliIo): void;
 export declare function registerDoctorCommand(parent: Command, io: CliIo): void;
 /**
- * `humanish telemetry status|enable|disable` — the opt-out the convention requires, plus a `status`
+ * `humanish telemetry status|enable|disable`: the opt-out the convention requires, plus a `status`
  * that prints the exact document that would be sent. "You can read what we collect" is what makes
- * default-on honest rather than merely lawful.
+ * default-on collection checkable by the person it describes.
  */
 export declare function registerTelemetryCommand(parent: Command, io: CliIo): void;
 export declare function registerKeysCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/setup.js

@@ -4,17 +4,18 @@ import { promptSecret } from "../secret-prompt.js";
 import { runInit } from "../../lab/init.js";
 import { buildPayload, disabledByEnvironment, readTelemetryState, telemetryStatePath, writeTelemetryState, } from "../telemetry.js";
 import { doctor } from "../doctor.js";
-import { applyEnvFileOption, CLI_VERSION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, } from "../io.js";
+import { oldStudyOption, studyOptionValue } from "../deprecations.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, formatCliError, } from "../io.js";
 export function registerInitCommand(parent, io) {
     parent
         .command("init")
         .description("Set up committed humanish/ source files and ignored .humanish/ runtime state.")
-        .summary("Set up humanish/ source and .humanish/ runtime state.")
+        .summary("Set up starter studies and personas in this project.")
         .option("--dry-run", "Print planned changes without writing files.")
         .option("--yes", "Apply safe generated changes without prompting.")
         .option("--local-browser <url>", "Set the local-browser starter to this loopback app URL (explicit port above 1023).")
         .option("--local-mission <text>", "Set the local-browser participant mission.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const initOptions = {
@@ -47,25 +48,27 @@ export function registerDoctorCommand(parent, io) {
     parent
         .command("doctor")
         .description("Explain project readiness and missing humanish setup.")
-        .summary("Explain project readiness and missing setup.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--lab <lab>", "Check the selected lab's desktop, participant authentication and separate analysis requirements; no provider calls.")
-        .option("--env-file <path>", "Load a local env file for these setup checks without printing values.")
+        .summary("Check what this project and machine need for a run.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--study <study>", "Check the study's desktop, participant authentication and separate analysis requirements; no provider calls.")
+        .addOption(oldStudyOption("study"))
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
+        const study = studyOptionValue(command, io, options);
         if (options.envFile &&
             !(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
             return;
-        const result = await doctor(options.cwd, options.lab ? { lab: options.lab } : {});
+        const result = await doctor(options.cwd, study ? { lab: study } : {});
         writeResult(command, io, result, formatDoctorHuman);
         // Behavioral change: was exit 1, every other structured command uses 2.
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
 /**
- * `humanish telemetry status|enable|disable` — the opt-out the convention requires, plus a `status`
+ * `humanish telemetry status|enable|disable`: the opt-out the convention requires, plus a `status`
  * that prints the exact document that would be sent. "You can read what we collect" is what makes
- * default-on honest rather than merely lawful.
+ * default-on collection checkable by the person it describes.
  */
 export function registerTelemetryCommand(parent, io) {
     const telemetry = parent
@@ -83,8 +86,8 @@ export function registerTelemetryCommand(parent, io) {
             anonymousId: state.anonymousId,
             version: CLI_VERSION,
             properties: {
-                command: "lab run",
-                lab: "try-live",
+                command: "run",
+                study: "try-live",
                 mode: "live",
                 outcome: "incomplete",
                 brain: "provider-key",
@@ -110,7 +113,7 @@ export function registerTelemetryCommand(parent, io) {
                 `telemetry: ${result.enabled ? "on" : "off"}${envOff ? " (DO_NOT_TRACK / HUMANISH_TELEMETRY_DISABLED)" : ""}`,
                 `state: ${result.statePath}`,
                 "",
-                "a complete example of what is sent — there are no other fields:",
+                "every field that is sent, with example values:",
                 JSON.stringify(sample, null, 2),
                 "",
                 "never sent: labs you wrote, subjects, personas, missions, paths, run evidence, key names or values.",
@@ -139,6 +142,8 @@ export function registerTelemetryCommand(parent, io) {
 }
 const KEYS_RESULT_SCHEMA = "humanish.keys-result.v1";
 function formatKeysHuman(result) {
+    if (!result.ok)
+        return { error: { message: result.message } };
     const lines = [
         `humanish keys ${result.ok ? "ok" : "failed"}`,
         `store: ${result.store}`,
@@ -165,7 +170,7 @@ export function registerKeysCommand(parent, io) {
     const keys = parent
         .command("keys")
         .description("Manage the humanish user-level key store used by provider-key discovery.")
-        .summary("Manage the user-level provider key store.");
+        .summary("Store and manage your provider keys.");
     keys
         .command("set")
         .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME.")
@@ -254,7 +259,7 @@ export function registerKeysCommand(parent, io) {
     });
     keys
         .command("list")
-        .description("List the NAMES stored in the user store. Values are never printed.")
+        .description("List the key names in the user store. Values are never printed.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (_options, command) => {
         const storePath = userKeyStorePath(process.env);
@@ -277,10 +282,10 @@ function formatDoctorHuman(result) {
     return ([
         `humanish doctor ${result.ok ? "ok" : "needs setup"}`,
         `cwd: ${result.cwd}`,
-        // "missing" is a VERDICT, and a row that never ran has none. A participant reading doctor on a
+        // "missing" is a verdict, and a row that never ran has none. A participant reading doctor on a
         // fresh desktop got `- missing package.json: package.json is present and safe to read`, which
         // contradicts itself in eleven words (labs/tui-self-study.yaml).
-        ...result.checks.map((check) => `- ${check.ok ? "ok" : check.checked === false ? "not checked" : "missing"} ${check.name}: ${check.message}`),
+        ...result.checks.map((check) => `- ${check.status.replace("_", " ")} ${check.name}: ${check.message}`),
     ].join("\n") + "\n");
 }
 function formatInitHuman(result) {
@@ -307,14 +312,14 @@ function formatInitHuman(result) {
     if (result.warnings.length > 0) {
         lines.push("", "warnings:", ...result.warnings.map((warning) => `- ${warning}`));
     }
-    if (result.error) {
-        lines.push("", `${result.error.code}: ${result.error.message}`);
-    }
+    // init writes a refused plan to stderr, so the error goes there in the shared shape.
+    if (result.error)
+        lines.push("", formatCliError("humanish init", result.error).trimEnd());
     if (result.mode === "needs-confirmation") {
         lines.push("", "Run with --dry-run --json to inspect or --yes to apply.");
     }
     else if (result.ok && result.nextSteps !== undefined) {
-        // Twenty files and no next step is where the funnel died (#505). Increasingly the reader here
+        // Twenty files and no next step is where the funnel died. Increasingly the reader here
         // is a coding agent doing setup for someone, and an agent does what stdout tells it to.
         lines.push(...result.nextSteps);
     }

package/dist/cli/commands/study.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerStudyCommands(parent: Command, io: CliIo): void;