humanish 0.107.0 → 0.109.0

package/dist/cli/io.js

@@ -3,10 +3,11 @@ import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { loadEnvFile } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
+import { withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
@@ -17,11 +18,19 @@ function readCliVersion() {
         : "0.0.0";
 }
 export const CLI_VERSION = readCliVersion();
-// Shared so the ~20 leaf commands that declare their own --json flag cannot drift
-// from each other in wording.
+// One text per shared flag, so the same flag reads the same on every command.
+// tests/cli/shared-options.test.ts walks the program and holds every use to these.
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
-// Transcode ONLY for a terminal. A pipe carries bytes to another program — mangling those would
-// corrupt a JSON payload for a reader that handles UTF-8 perfectly well — while a TTY carries them
+export const CWD_OPTION_DESCRIPTION = "Project directory.";
+export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
+export const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export 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 function freePortOption() {
+    return new Option("--port <port>", PORT_OPTION_DESCRIPTION).default("0", "a free port");
+}
+// Transcode only for a terminal. A pipe carries bytes to another program, and mangling those would
+// corrupt a JSON payload for a reader that handles UTF-8 perfectly well, while a TTY carries them
 // to a font, through a locale that may not decode them. See src/routes/terminal/encoding.ts for what a
 // participant actually read back off the screen.
 const forStream = (stream, text) => stream.isTTY === true ? forTerminal(text) : text;
@@ -37,7 +46,7 @@ export const defaultIo = {
 // of the invocation (a fresh object every createProgram() call) rather than a
 // module-level boolean, so tests that construct multiple `createProgram()`
 // instances in the same process never see one instance's writes bleed into
-// another's, and nothing needs explicit cleanup -- the entry is released once
+// another's, and nothing needs explicit cleanup: the entry is released once
 // that Command tree is garbage collected.
 const invocationEnvelopeWritten = new WeakSet();
 function rootCommandOf(command) {
@@ -77,7 +86,7 @@ export async function applyEnvFileOption(args) {
     return true;
 }
 /**
- * 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.
@@ -97,7 +106,7 @@ export async function discoverCliKeys(args) {
         // Discovery must never break a command; a rung that fails to read is a miss, not an error.
     }
 }
-export function parseLabCount(value, fallback) {
+export function parseStudyCount(value, fallback) {
     return value === undefined ? fallback : parsePositiveInteger(value);
 }
 export function parseParticipantIds(value) {
@@ -115,21 +124,60 @@ export function parseParticipantIds(value) {
     }
     return participantIds;
 }
-// Exported so tests/cli/program.test.ts can drive the command-boundary catch-all's
-// post-write guard (invocationEnvelopeAlreadyWritten above) through the same
-// funnel every real command uses, without duplicating its stdout-vs-formatHuman
-// branching. Not re-exported from src/index.ts; this stays an internal seam.
+/**
+ * The command to run next, by code. A code is listed only when its messages do not already name a
+ * command: the run-not-found and missing-study messages do.
+ */
+const NEXT_COMMAND = {
+    HUMANISH_STUDY_NOT_FOUND: "humanish study list",
+};
+/** `<command> failed: <message>`, then `code: <CODE>`, then `next: <command>` when one is known. */
+export function formatCliError(command, error) {
+    const next = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    return ([
+        `${command} failed: ${error.message}`,
+        ...(error.code === undefined ? [] : [`code: ${error.code}`]),
+        ...(next === undefined ? [] : [`next: ${next}`]),
+    ].join("\n") + "\n");
+}
+/** A result whose human output is its message: stdout when it passed, stderr when it failed. */
+export function messageOutput(value) {
+    return value.ok ? `${value.message}\n` : { error: { message: value.message } };
+}
+/** A failed result's human output: its error on stderr and nothing on stdout. */
+export function humanError(error) {
+    return { error: error ?? { message: "the command failed without a recorded error" } };
+}
+/** "humanish study show": the command's path as a person types it. */
+function commandLabel(command) {
+    const names = [];
+    for (let current = command; current !== null; current = current.parent)
+        names.unshift(current.name());
+    return names.join(" ");
+}
+/** Prints a human formatter's output: text to stdout, an error to stderr through formatCliError. */
+export function writeHuman(command, io, human) {
+    if (typeof human === "string") {
+        io.writeOut(human);
+        return;
+    }
+    if (human.stdout)
+        io.writeOut(human.stdout);
+    if (human.error)
+        io.writeErr(formatCliError(commandLabel(command), human.error));
+}
 export function writeResult(command, io, result, formatHuman) {
     const output = automaticAnalysisEnvelope(result);
     if (wantsJson(command)) {
-        io.writeOut(`${JSON.stringify(output, null, 2)}\n`);
+        // Queued warnings are on stderr already; a JSON caller gets them in warnings[] as well.
+        io.writeOut(`${JSON.stringify(withQueuedWarnings(command, output), null, 2)}\n`);
     }
     else {
-        io.writeOut(formatHuman(output));
+        writeHuman(command, io, formatHuman(output));
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
             if (analysis)
-                io.writeOut(`analysis: ${analysis.state}${analysis.reason ? ` (${analysis.reason})` : ""}\n`);
+                io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
             if (rejected)
                 io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
@@ -139,7 +187,7 @@ export function writeResult(command, io, result, formatHuman) {
     }
     markInvocationEnvelopeWritten(command);
     // Every backend's result passes through here, so this is where a study's facts get read for
-    // telemetry — not in each backend, which is how they went unreported for two releases.
+    // telemetry. Reading them in each route instead is how they went unreported for two releases.
     noteRunFacts(command, deriveRunFacts(result));
 }
 const runFactsByCommand = new WeakMap();
@@ -152,10 +200,10 @@ export function noteRunFacts(command, facts) {
 export function runFactsFor(command) {
     return { ...runFactsByCommand.get(command) };
 }
+/** A run result, or the preview route's study result: they differ only in `schema`. */
 export function formatRunHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         `humanish run ${result.mode}`,
         `run: ${result.runId}`,
@@ -166,9 +214,8 @@ export function formatRunHuman(result) {
     ].join("\n") + "\n");
 }
 function formatEnvFileHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish env-file loaded",
         `env-file: ${result.envFile}`,
@@ -205,7 +252,7 @@ export function candidateOption(options) {
         ...(options.finding === undefined ? {} : { finding: options.finding }),
     };
 }
-export function collectRepeated(value, previous) {
+export function collectRepeated(value, previous = []) {
     return [...previous, value];
 }
 export function wantsJson(command) {
@@ -218,6 +265,34 @@ export function wantsJson(command) {
     }
     return false;
 }
+/** What the automatic analysis did, in words; JSON output keeps the reason code. */
+const ANALYSIS_REASON_TEXT = {
+    AUTOMATIC_ANALYSIS_DRY_RUN: "skipped for dry runs",
+    AUTOMATIC_ANALYSIS_KEY_MISSING: "skipped because OPENAI_API_KEY is not set",
+    AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE: "skipped because no participant left evidence",
+    AUTOMATIC_ANALYSIS_ACTOR_CANCELLED: "skipped because the run stopped before its participants finished",
+    AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",
+    AUTOMATIC_ANALYSIS_ALREADY_REQUESTED: "skipped because this run's analysis was already requested",
+    AUTOMATIC_ANALYSIS_BUSY: "skipped because another analysis is running",
+    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "not started because its configuration or question was refused",
+    AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "not started because the run's cleanup was not confirmed",
+    AUTOMATIC_ANALYSIS_REUSED: "complete, reusing an earlier analysis of the same evidence",
+    AUTOMATIC_ANALYSIS_LIMITATIONS: "partial, because it covered only part of the evidence",
+    AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED: "partial, because it went over its estimated cost or output",
+    AUTOMATIC_ANALYSIS_FAILED: "failed",
+    AUTOMATIC_ANALYSIS_CANCELLED: "cancelled",
+    AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE: "failed because the Codex analyst could not run",
+    AUTOMATIC_ANALYSIS_PUBLICATION_FAILED: "failed because the report could not be saved",
+    AUTOMATIC_ANALYSIS_SOURCE_CHANGED: "failed because the run's evidence changed during analysis",
+    AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "outcome unknown: a cancellation could not be recorded",
+    AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE: "outcome unknown: analysis storage is unavailable",
+    AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN: "outcome unknown",
+};
+export function analysisOutcomeText(analysis) {
+    if (analysis.reason === null)
+        return analysis.state;
+    return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
+}
 /** Preserve the run's own result while making requested post-processing failures machine-visible. */
 function overBudgetAnalysisHint(result) {
     const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;

package/dist/cli/observer-follow.d.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import type { ObserverResult, ObserverServer } from "../observer/render.js";
 import type { ExposureRequest } from "../observer/exposure.js";
-import { type CliIo, type LabCommandOptions } from "./io.js";
+import { type CliIo, type StudyCommandOptions, type HumanOutput } from "./io.js";
 /** How a command shows an Observer, decided before the run it shows starts. */
 export interface ObserverPlan {
     port: number;
@@ -31,7 +31,7 @@ export declare function showObserver(args: {
     rendered: ObserverResult;
 }): Promise<void>;
 export declare function withObserverServer(rendered: ObserverResult, server: ObserverServer): ObserverResult;
-export declare function formatObserverHuman(result: ObserverResult): string;
+export declare function formatObserverHuman(result: ObserverResult): HumanOutput;
 export type WatchStopSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 interface WatchSignalTarget {
     once(event: WatchStopSignal, listener: () => void): unknown;
@@ -52,5 +52,5 @@ export declare function watchExposeRequested(o: {
     allowDomain?: string[] | undefined;
     publicUrl?: string | undefined;
 }): boolean;
-export declare function exposureRequestFromOptions(options: LabCommandOptions): ExposureRequest;
+export declare function exposureRequestFromOptions(options: StudyCommandOptions): ExposureRequest;
 export {};

package/dist/cli/observer-follow.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { serveObserver } from "../observer/render.js";
-import { formatRunHuman, parseObserverPort, wantsJson, writeResult, } from "./io.js";
+import { formatRunHuman, parseObserverPort, wantsJson, writeResult, humanError, } from "./io.js";
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
  * code 2 and returns null, so a caller refuses before starting a run.
@@ -64,9 +64,8 @@ export function withObserverServer(rendered, server) {
     };
 }
 export function formatObserverHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish observer rendered",
         `run: ${result.run}`,
@@ -134,8 +133,8 @@ export function exitCodeForSignal(signal) {
     }
 }
 // True when any tunnel-edge exposure flag is present (not --safe, which is an orthogonal filter).
-// Used to refuse exposure on the non-lab watch path and on non-CUA backends, where there is no live
-// desktop to stream.
+// Callers refuse exposure with it on the watch path without a study and on non-computer-use routes, where
+// there is no live desktop to stream.
 export function watchExposeRequested(o) {
     return (o.expose === true ||
         o.tunnel !== undefined ||
@@ -145,7 +144,7 @@ export function watchExposeRequested(o) {
         (o.allowDomain?.length ?? 0) > 0 ||
         o.publicUrl !== undefined);
 }
-// Map LabCommandOptions onto the shared exposure validator input.
+// Map StudyCommandOptions onto the shared exposure validator input.
 export function exposureRequestFromOptions(options) {
     return {
         expose: options.expose === true,

package/dist/cli/orientation.d.ts

@@ -3,14 +3,14 @@ export interface OrientationState {
     schema: typeof ORIENTATION_SCHEMA;
     /** Whether this project has a committed `humanish/` source plane. */
     initialized: boolean;
-    /** Committed + gitignored lab manifests discovered in this project. */
-    labCount: number;
-    /** Ids of a few labs worth naming in a suggestion. */
-    labIds: string[];
+    /** Committed and gitignored study files found in this project. */
+    studyCount: number;
+    /** Ids of a few studies worth naming in a suggestion. */
+    studyIds: string[];
     /** Runs already on disk, and the most recent one if there is one. */
     runCount: number;
     latestRunId?: string;
-    /** The commands that make sense from HERE, most useful first. */
+    /** The commands that make sense from here, most useful first. */
     nextCommands: OrientationCommand[];
 }
 interface OrientationCommand {
@@ -19,9 +19,12 @@ interface OrientationCommand {
 }
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
- * a provider — bare invocation must not be able to spend money or mutate a repo.
+ * a provider: bare invocation must not be able to spend money or mutate a repo.
  */
-export declare function readOrientation(cwd: string): Promise<OrientationState>;
+export declare function readOrientation(cwd: string, host?: {
+    platform: NodeJS.Platform;
+    arch: string;
+}): Promise<OrientationState>;
 /**
  * The human rendering. Says where you are before it says what to do, because "what should I run"
  * has no answer that is true in every project.

package/dist/cli/orientation.js

@@ -1,9 +1,9 @@
-// What `humanish` says when you run it with no arguments (#367).
+// What `humanish` says when you run it with no arguments.
 //
-// It used to print commander's help: sixteen subcommands before any value, identical whether you
+// Commander's help would print sixteen subcommands before any value, identical whether you
 // had never run the tool or had a finished study sitting on disk. That is a poor first contact for
-// a human, and it is worse for a coding agent, which needs to know WHERE IT IS before it can choose
-// a command — help is a menu, not an orientation.
+// a human, and it is worse for a coding agent, which needs to know where it is before it can choose
+// a command; help is a menu, not an orientation.
 //
 // So bare invocation answers three questions instead: what is this, what state is this project in,
 // and what should I run next. The answer is derived from the project rather than fixed, so it is
@@ -12,96 +12,138 @@
 // Both audiences are served by the same data (docs/principles/three-roles.md). A human on a
 // terminal gets prose and an offer to set things up; an agent gets the same facts as stable text,
 // or as JSON with `--json`. Neither is a special case of the other bolted on afterwards.
-import { listLabManifests } from "../lab/discover.js";
+import { listStudyManifests } from "../study/discover.js";
 import { listRuns } from "../run/stored-runs.js";
+import { plural } from "../run/text.js";
+import { supportsLocalBrowser } from "./first-run-path.js";
+import { PRODUCT_SENTENCE } from "./product-sentence.js";
 export const ORIENTATION_SCHEMA = "humanish.orientation.v1";
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
- * a provider — bare invocation must not be able to spend money or mutate a repo.
+ * a provider: bare invocation must not be able to spend money or mutate a repo.
  */
-export async function readOrientation(cwd) {
-    const [labs, runs] = await Promise.all([
-        listLabManifests(cwd).catch(() => undefined),
+export async function readOrientation(cwd, host = process) {
+    const [found, runs] = await Promise.all([
+        listStudyManifests(cwd).catch(() => undefined),
         listRuns(cwd).catch(() => undefined),
     ]);
-    const labIds = (labs?.labs ?? [])
-        .map((lab) => lab.id)
+    const studyIds = (found?.studies ?? [])
+        .map((study) => study.id)
         .filter((id) => typeof id === "string");
     const runIds = (runs?.runs ?? [])
         .map((run) => run.runId)
         .filter((id) => typeof id === "string");
     const latest = typeof runs?.latest === "string" ? runs.latest : runIds[0];
-    const initialized = (labs?.labs ?? []).some((lab) => lab.origin === "committed") || labIds.length > 0;
+    const retiredFiles = found?.retired ?? [];
+    const retired = {
+        v2: retiredFiles.filter((file) => file.code === "HUMANISH_STUDY_V2_UNSUPPORTED").length,
+        moved: retiredFiles.filter((file) => file.code === "HUMANISH_STUDY_RETIRED_DIRECTORY").length,
+    };
+    const initialized = (found?.studies ?? []).some((study) => study.origin === "committed") ||
+        studyIds.length > 0 ||
+        retiredFiles.length > 0;
     return {
         schema: ORIENTATION_SCHEMA,
         initialized,
-        labCount: labIds.length,
-        labIds: labIds.slice(0, 3),
+        studyCount: studyIds.length,
+        studyIds: studyIds.slice(0, 3),
         runCount: runIds.length,
         ...(latest === undefined ? {} : { latestRunId: latest }),
-        nextCommands: nextCommandsFor({ initialized, labIds, hasRun: runIds.length > 0 }),
+        nextCommands: nextCommandsFor({
+            initialized,
+            studyIds,
+            retired,
+            hasRun: runIds.length > 0,
+            host,
+        }),
     };
 }
 /**
  * The two or three commands worth running from this state. Deliberately short: a list of everything
- * is what bare invocation used to print, and it is why nobody read it.
+ * is commander's help, which nobody reads.
  */
 function nextCommandsFor(args) {
+    const { v2, moved } = args.retired;
+    const fixes = [
+        ...(v2 === 0
+            ? []
+            : [
+                {
+                    command: "humanish migrate --dry-run",
+                    why: `${plural(v2, "study file")} ${v2 === 1 ? "uses" : "use"} humanish.lab.v2, which humanish no longer reads; this lists the conversion, and humanish migrate writes it`,
+                },
+            ]),
+        ...(moved === 0
+            ? []
+            : [
+                {
+                    command: "humanish study list",
+                    why: `${plural(moved, "study file")} ${moved === 1 ? "is" : "are"} in a labs/ directory, which humanish no longer reads; this names each one and the studies/ directory to move it to`,
+                },
+            ]),
+    ];
+    // A fix that is already `humanish study list` replaces the plain suggestion of the same command.
+    const named = new Set(fixes.map((fix) => fix.command));
+    return [...fixes, ...nextCommandsForStudies(args).filter((next) => !named.has(next.command))];
+}
+function nextCommandsForStudies(args) {
+    const dryRun = {
+        command: "humanish run first-run",
+        why: "a dry run: no browser or model runs, no keys, no spend",
+    };
     if (!args.initialized) {
         return [
-            { command: "humanish init", why: "create humanish/ with a starter lab and persona" },
             {
-                command: "humanish run first-run",
-                why: "a synthetic run with no keys and no spend, to see the shape of the evidence",
+                command: "humanish init --yes",
+                why: "write starter studies, personas and an AGENTS.md (--dry-run lists every file first)",
             },
+            dryRun,
         ];
     }
-    const suggestedLab = args.labIds[0];
-    const commands = [
+    // The starter live study this host can run. The other starter studies are templates whose subject
+    // still names your-org/your-app, so they are never suggested.
+    const liveStudy = (supportsLocalBrowser(args.host.platform, args.host.arch)
+        ? ["local-browser", "try-live"]
+        : ["try-live"]).find((id) => args.studyIds.includes(id));
+    if (!args.hasRun) {
+        return [
+            dryRun,
+            liveStudy === undefined
+                ? { command: "humanish study list", why: "see the studies this project declares" }
+                : {
+                    command: `humanish doctor --study ${liveStudy}`,
+                    why: `check what the ${liveStudy} study still needs before a live run`,
+                },
+        ];
+    }
+    return [
+        ...(liveStudy === undefined
+            ? []
+            : [{ command: `humanish run ${liveStudy}`, why: "run a real participant against an app" }]),
         {
-            command: suggestedLab ? `humanish watch ${suggestedLab}` : "humanish watch",
-            why: "run a lab and open the Observer while it goes",
-        },
-    ];
-    if (args.hasRun) {
-        commands.push({
             command: "humanish verify --run latest",
             why: "check the last run's evidence and public-safety gates",
-        });
-        commands.push({
-            command: "humanish observe --run latest",
-            why: "reopen the last run's Observer",
-        });
-    }
-    else {
-        commands.push({ command: "humanish lab list", why: "see the labs this project declares" });
-        commands.push({
-            command: "humanish doctor",
-            why: "check what this project still needs before a live run",
-        });
-    }
-    return commands;
+        },
+        { command: "humanish observe --run latest", why: "reopen the last run's Observer" },
+    ];
 }
 /**
  * The human rendering. Says where you are before it says what to do, because "what should I run"
  * has no answer that is true in every project.
  */
 export function formatOrientationHuman(state) {
-    const lines = [
-        "humanish — run realistic synthetic personas against your app and keep the evidence.",
-        "",
-    ];
+    const lines = [`humanish: ${PRODUCT_SENTENCE}`, ""];
     if (!state.initialized) {
         lines.push("This project is not set up yet.");
     }
     else {
-        const labs = state.labCount === 1 ? "1 lab" : `${state.labCount} labs`;
+        const studies = state.studyCount === 1 ? "1 study" : `${state.studyCount} studies`;
         const runs = state.runCount === 0
             ? "no runs yet"
             : state.runCount === 1
                 ? "1 run"
                 : `${state.runCount} runs`;
-        lines.push(`This project has ${labs} and ${runs}${state.latestRunId ? ` (latest: ${state.latestRunId})` : ""}.`);
+        lines.push(`This project has ${studies} and ${runs}${state.latestRunId ? ` (latest: ${state.latestRunId})` : ""}.`);
     }
     lines.push("");
     for (const next of state.nextCommands) {

package/dist/cli/product-sentence.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
+ * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
+ * equal.
+ */
+export declare const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/product-sentence.js

@@ -0,0 +1,6 @@
+/**
+ * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
+ * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
+ * equal.
+ */
+export const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/program.d.ts

@@ -4,12 +4,17 @@ import { type CliIo } from "./io.js";
 /**
  * Enrich commander's flag rejections with where the flag actually lives. A bare "unknown option"
  * is accurate and unhelpful in the same way `no labs here yet` was: it reports a fact about this
- * command and says nothing the reader can act on. Silence is preserved when no sibling has it —
+ * command and says nothing the reader can act on. Silence is preserved when no sibling has it:
  * inventing a suggestion would be worse than none.
  */
 export declare function withSiblingFlagHint(text: string, root: Command): string;
 /** Drop the literal `--` that `pnpm <script> -- <args>` puts before the CLI's own arguments. */
 export declare function normalizeCliArgv(argv: string[]): string[];
+/**
+ * The root help's examples, in the order a newcomer runs them. Each passes on a freshly
+ * initialized project (tests/cli/root-help-examples.test.ts).
+ */
+export declare const ROOT_HELP_EXAMPLES: readonly ["humanish init --yes", "humanish run first-run", "humanish observe --run latest --open", "humanish doctor --study try-live", "humanish run try-live", "humanish verify --json"];
 export declare function createProgram(io?: Partial<CliIo> & {
     tuiRuntime?: Partial<TuiRuntime>;
 }): Command;