humanish 0.110.2 → 0.110.4

package/dist/study/composition-rules.js

@@ -10,7 +10,7 @@ import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
-import { rosterOf } from "./parse/actors.js";
+import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeOf, scenarioRefOf, declaresSharedWorld, } from "./study-fields.js";
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
     return (thisRepoValidationReason(config) ??
@@ -25,7 +25,7 @@ export function compositionReason(config) {
         (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
         // fails with a precise reason instead of running as independent participants.
-        (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
+        (declaresSharedWorld(config) ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
@@ -39,7 +39,7 @@ function thisRepoValidationReason(config) {
         if (config.execution?.target) {
             return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
-        if (config.scenario?.mode === "live") {
+        if (modeOf(config) === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
         }
     }
@@ -51,21 +51,21 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorStudy with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
+// planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
             return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
         if (!actorResolvesToComputerUse(type)) {
-            return `actors[0].type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
+            return `actor.type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
         if (computerUseParticipantCount(config) > 1) {
-            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set actors[0].count to 1 and drop actors[0].lanes (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
+            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set participants to 1 and drop participants (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
         }
-        if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
+        if (participantList(config) !== undefined) {
+            return "`participants` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
         }
         if (config.policies?.allowPublicTargets === true) {
             return "`policies.allowPublicTargets` does not apply to a local-app subject: it is always a loopback dev server, so there is no public target to allow. Remove the setting.";
@@ -78,18 +78,18 @@ function localAppValidationReason(config) {
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
             // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
                 return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
-            if (!config.scenario?.ref) {
-                return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
+            if (!scenarioRefOf(config)) {
+                return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
             }
-            if ((config.actors[0]?.count ?? 1) > 2) {
-                return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
+            if ((surfaceCount(config) ?? 1) > 2) {
+                return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
                 return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
@@ -106,7 +106,7 @@ function appUrlValidationReason(config) {
                 return "app-url computer-use subjects require `execution.target: local` or `e2b-desktop`.";
             }
             if (!actorResolvesToComputerUse(type)) {
-                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
+                return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
             // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
@@ -116,7 +116,7 @@ function appUrlValidationReason(config) {
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
             if (unsafeTarget !== undefined) {
-                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
+                return "`subject.appUrl` and `participants[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
             }
         }
     }
@@ -125,7 +125,7 @@ function appUrlValidationReason(config) {
 // Scripted-browser actors on any other subject: only a provisioned clone on e2b-desktop.
 function scriptedBrowserValidationReason(config) {
     if (config.subject.source !== "app-url" &&
-        actorResolvesToScriptedBrowser(config.actors[0]?.type)) {
+        actorResolvesToScriptedBrowser(actorOf(config)?.type)) {
         if (config.subject.source !== "clone") {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
@@ -148,14 +148,14 @@ function scriptedBrowserValidationReason(config) {
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
             return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
-        if (!config.scenario?.ref) {
-            return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
+        if (!scenarioRefOf(config)) {
+            return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
         }
-        if ((config.actors[0]?.count ?? 1) > 2) {
-            return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
+        if ((surfaceCount(config) ?? 1) > 2) {
+            return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
-        if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` is not supported on the scripted-browser route yet. Use `actors[0].count` to choose the desktop and mobile surfaces.";
+        if (participantList(config) !== undefined) {
+            return "`participants` is not supported on the scripted-browser route yet. Use `surfaces` to choose the desktop and mobile surfaces.";
         }
         if (config.policies?.redactScreenshots === true) {
             return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
@@ -183,7 +183,7 @@ function scriptedBrowserValidationReason(config) {
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(config.actors[0]?.type)) {
+        actorResolvesToComputerUse(actorOf(config)?.type)) {
         if (!config.subject.serve) {
             return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
@@ -210,8 +210,8 @@ function localTreeValidationReason(config) {
         if (config.execution?.target !== "e2b-desktop") {
             return "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox; there is no local route for a local-tree subject.";
         }
-        if (!actorResolvesToComputerUse(config.actors[0]?.type)) {
-            return `actors[0].type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${config.actors[0]?.type ?? ""}".`;
+        if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
+            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${actorOf(config)?.type ?? ""}".`;
         }
     }
     return null;
@@ -238,7 +238,7 @@ function desktopCliValidationReason(config) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
             return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
-        if (!actorResolvesToComputerUse(config.actors[0]?.type ?? "")) {
+        if (!actorResolvesToComputerUse(actorOf(config)?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
         }
         const install = config.subject.product.install;
@@ -255,15 +255,15 @@ function desktopCliValidationReason(config) {
 // fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
             return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
-            return `actors[0].type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
+            return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
         }
-        if ((config.actors[0]?.count ?? 1) > 1) {
-            return "Terminal fan-out to more than one participant is not supported yet; set actors[0].count to 1.";
+        if ((declaredParticipantCount(config) ?? 1) > 1) {
+            return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }
     else if (config.execution?.target === "e2b-terminal") {
@@ -271,7 +271,7 @@ function terminalValidationReason(config) {
         // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
-    else if (actorResolvesToTerminal(config.actors[0]?.type)) {
+    else if (actorResolvesToTerminal(actorOf(config)?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the
         // terminal agent only studies a declared terminal-product from public surfaces).
         return "terminal actors require `subject.source: terminal-product` (a CLI/product the agent studies from public surfaces); other subjects are not supported on this route.";
@@ -283,7 +283,7 @@ function terminalValidationReason(config) {
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
             return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }

package/dist/study/config.d.ts

@@ -1,4 +1,4 @@
-import { type StudyParseResult } from "./types.js";
+import { type StudyConfig, type StudyParseResult } from "./types.js";
 /** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
 export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
 /**
@@ -10,6 +10,13 @@ export declare function parseStudy(raw: unknown): StudyParseResult;
  * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
  * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
  * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
  */
 export declare function parseStudyDocument(raw: unknown): StudyParseResult;
+/**
+ * The checks that read more than one section of a parsed config, and the defaults they fill:
+ * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
+ * study.
+ */
+export declare function checkStudyConfig(config: StudyConfig): StudyParseResult;

package/dist/study/config.js

@@ -63,7 +63,7 @@ import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
 import { plural } from "../run/text.js";
 /** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
@@ -84,7 +84,7 @@ export function parseStudy(raw) {
  * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
  * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
  * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
  */
 export function parseStudyDocument(raw) {
     if (!isRecord(raw)) {
@@ -190,9 +190,18 @@ function parseV2(raw) {
         return commsResult;
     if (commsResult.value)
         config.comms = commsResult.value;
-    if (config.comms?.email?.smtp && config.subject.topology === "shared-world") {
-        return invalid("SMTP capture is not supported yet for shared-world studies. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world studies.");
-    }
+    return checkStudyConfig(config);
+}
+/**
+ * The checks that read more than one section of a parsed config, and the defaults they fill:
+ * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
+ * study.
+ */
+export function checkStudyConfig(config) {
+    const smtpReason = smtpValidationReason(config);
+    if (smtpReason)
+        return invalid(smtpReason);
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
         return invalid(mediaReason);

package/dist/study/doctor.js

@@ -9,6 +9,7 @@ import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
 import { cli } from "../cli/invocation.js";
+import { actorOf } from "./study-fields.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -151,7 +152,7 @@ export async function studySetupChecks(args) {
         {
             name: "study route",
             ok: true,
-            message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
+            message: `${config.id}: ${actorOf(config)?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
     ];
     if (dryRun)
@@ -246,16 +247,16 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         ];
     }
     if ((route !== "computer-use" && route !== "shared-world") ||
-        config.actors[0]?.type !== "local-agent")
+        actorOf(config)?.type !== "local-agent")
         return [];
-    const choice = config.actors[0]?.localAgent ?? "codex";
+    const choice = actorOf(config)?.localAgent ?? "codex";
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
     // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
-        return [await hostedCodexParticipantCheck(args, config.actors[0])];
+        return [await hostedCodexParticipantCheck(args, actorOf(config))];
     const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {

package/dist/study/init-templates.d.ts

@@ -24,5 +24,5 @@ export declare const humanishScripts: Record<string, string>;
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId): StarterFile[];
+export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId, command?: string): StarterFile[];
 export {};

package/dist/study/init-templates.js

@@ -34,6 +34,44 @@ defaults:
 `,
     };
 }
+/**
+ * The `humanish/README.md` init writes. Its commands start with `command`, the invocation init
+ * chose for this install (src/cli/invocation.ts), as in the section init writes to `AGENTS.md`.
+ */
+function readmeFile(command) {
+    return {
+        path: "humanish/README.md",
+        plane: "source",
+        contents: `# humanish
+
+This directory holds the committed definitions of this app's humanish studies: study files,
+personas and scenarios.
+
+Keep this directory public-safe:
+
+- synthetic personas only;
+- synthetic fixtures only;
+- env var names only, never values;
+- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
+
+Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
+
+Studies:
+
+- committed reusable studies live in humanish/studies/*.yaml;
+- private or machine-local studies live in ignored .humanish/studies/*.yaml or
+  .humanish/local/studies/*.yaml;
+- run a study with \`${command} run <study>\`, or \`${command} watch <study>\` to stay attached;
+- files under humanish/labs/ move there with \`${command} migrate\`.
+
+Format standard:
+
+- human-authored humanish source uses .yaml;
+- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
+- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
+`,
+    };
+}
 /**
  * The flagship live study. A ChatGPT-account Codex participant has no API-dollar price, so preflight
  * refuses a dollar cap on it (HUMANISH_COMPUTER_USE_UNPRICED_CAP); that variant is bounded by the
@@ -113,38 +151,7 @@ defaults:
     };
 }
 export const starterFiles = [
-    {
-        path: "humanish/README.md",
-        plane: "source",
-        contents: `# humanish
-
-This directory holds the committed definitions of this app's humanish studies: study files,
-personas and scenarios.
-
-Keep this directory public-safe:
-
-- synthetic personas only;
-- synthetic fixtures only;
-- env var names only, never values;
-- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
-
-Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
-
-Studies:
-
-- committed reusable studies live in humanish/studies/*.yaml;
-- private or machine-local studies live in ignored .humanish/studies/*.yaml or
-  .humanish/local/studies/*.yaml;
-- run a study with \`humanish run <study>\`, or \`humanish watch <study>\` to stay attached;
-- files under humanish/labs/ move there with \`humanish migrate\`.
-
-Format standard:
-
-- human-authored humanish source uses .yaml;
-- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
-- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
-`,
-    },
+    readmeFile("humanish"),
     {
         path: "humanish/personas/synthetic-new-user.yaml",
         plane: "source",
@@ -317,10 +324,12 @@ export const humanishScripts = {
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent) {
+export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent, command = "humanish") {
     return starterFiles.map((file) => file.path === "humanish/studies/local-browser.yaml"
         ? localBrowserStudy(localBrowser)
         : file.path === "humanish/studies/try-live.yaml"
             ? tryLiveStudy(actor, localAgent)
-            : file);
+            : file.path === "humanish/README.md"
+                ? readmeFile(command)
+                : file);
 }

package/dist/study/init.js

@@ -47,7 +47,7 @@ export async function runInit(options) {
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
     await planAgentsFile(preparedProjectRoot, cwd, plan, humanishCommand());
     const starterActor = starterActorFor(machine);
-    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
+    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine), machine.humanish), options.localBrowser !== undefined, plan);
     await planRuntimeDirectories(preparedProjectRoot, cwd, plan);
     const gitignorePlan = await planGitignore(preparedProjectRoot, cwd);
     plan.changes.push(gitignorePlan.change);

package/dist/study/{convert.d.ts → migrate/convert.d.ts}

@@ -1,4 +1,4 @@
-import { type StudyRoute } from "./routing.js";
+import type { StudyRoute } from "../routing.js";
 /** A key the conversion moved, by its v2 path and its v3 path. */
 export interface MovedKey {
     readonly from: string;

package/dist/study/{convert.js → migrate/convert.js}

@@ -1,16 +1,15 @@
 // Convert a humanish.lab.v2 study file to humanish.study.v3. It edits the parsed YAML document in
 // place and moves each pair node, so the comments on a moved key move with it. The result lists
 // every key it moved and every key it dropped. It refuses a file whose v3 form would parse or plan
-// differently from the v2 source with the dropped keys removed.
+// differently from the v2 source with the dropped keys removed. v2.ts reads the v2 source.
 import { isAlias, isMap, isScalar, isSeq, LineCounter, Pair, parseDocument, Scalar, visit, YAMLMap, YAMLSeq, } from "yaml";
-import { parseStudyDocument } from "./config.js";
-import { focusOf } from "./parse/actors.js";
-import { posInt } from "./parse/values.js";
-import { planStudy } from "./plan.js";
-import { routeOf } from "./routing.js";
-import { V2_SCHEMA, STUDY_SCHEMA } from "./types.js";
-import { inertFieldPaths } from "./warnings.js";
-import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "./field-paths.js";
+import { parseStudy } from "../config.js";
+import { parseStudyV3 } from "../parse/study.js";
+import { posInt } from "../parse/values.js";
+import { planStudy } from "../plan.js";
+import { V2_SCHEMA, STUDY_SCHEMA } from "../types.js";
+import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "../field-paths.js";
+import { checkV2, droppedPaths, v2ShapeReason, v2ToV3Raw } from "./v2.js";
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -36,10 +35,19 @@ export function convertStudyText(text, cwd) {
         return refuse("it is not a YAML mapping.");
     if (raw.schema !== V2_SCHEMA)
         return refuse(`its schema is not ${V2_SCHEMA}.`);
-    const source = parseStudyDocument(raw);
+    // The v2 parser's checks: the sections and the v2-only budget rule, then the checks the formats
+    // share on the v3 form of the file, then the rules on v2 shapes the v3 form cannot hold.
+    const source = checkV2(raw);
     if (!source.ok)
-        return refuse(`it does not parse: ${source.error.message}`);
-    const route = routeOf(source.config);
+        return refuse(`it does not parse: ${source.message}`);
+    const study = source.value;
+    const { route } = study;
+    const view = parseStudyV3(v2ToV3Raw(raw, route), { inert: "report" });
+    if (!view.ok)
+        return refuse(`it does not parse: ${view.error.message}`);
+    const shape = v2ShapeReason(study);
+    if (shape)
+        return refuse(`it does not parse: ${shape}`);
     const actorRaw = Array.isArray(raw.actors) ? raw.actors[0] : undefined;
     if (route === "terminal" && isPlainRecord(actorRaw)) {
         for (const key of ["count", "laneFocus"]) {
@@ -50,7 +58,7 @@ export function convertStudyText(text, cwd) {
     }
     const root = doc.contents;
     const dropped = [];
-    for (const path of droppedPaths(source.config, route, raw)) {
+    for (const path of droppedPaths(study, view.inert ?? [])) {
         const value = readFieldPath(raw, path);
         const pairs = deleteNodeFieldPath(root, path);
         if (value === undefined || pairs.length === 0)
@@ -60,8 +68,7 @@ export function convertStudyText(text, cwd) {
     }
     const moved = [];
     // v2 reads some laneFocus values as no focus at all ({}, a valueless key, valueless fields).
-    const focused = focusOf(source.config.actors[0]) !== undefined;
-    const converted = convertDocument(root, route, focused, moved);
+    const converted = convertDocument(root, route, study.focus !== undefined, moved);
     if (!converted.ok)
         return converted;
     const out = doc.toString({ lineWidth: foldWidth(text), flowCollectionPadding: false });
@@ -69,7 +76,7 @@ export function convertStudyText(text, cwd) {
     const lost = lostComment(text, out, dropped);
     if (lost !== undefined)
         return refuse(`it would lose the comment "${lost}".`);
-    const check = samePlans(raw, dropped.map((key) => key.path), out, cwd);
+    const check = samePlans(raw, route, dropped.map((key) => key.path), out, cwd);
     if (!check.ok)
         return check;
     return { ok: true, conversion: { text: out, route, moved, dropped } };
@@ -105,16 +112,6 @@ function lostComment(source, output, dropped) {
     }
     return undefined;
 }
-// The inert-field table's paths for the route, plus terminal `execution.timeoutMs`, which no
-// terminal code reads. Parents come before their children, so a child under a dropped parent is
-// reported with the parent.
-function droppedPaths(config, route, raw) {
-    const paths = inertFieldPaths(config);
-    if (route === "terminal" && readFieldPath(raw, "execution.timeoutMs") !== undefined)
-        paths.push("execution.timeoutMs");
-    const depth = (path) => path.split(".").length;
-    return [...new Set(paths)].sort((left, right) => depth(left) - depth(right));
-}
 // Folded text is folded again on output. Most of a file's long lines end near the width its author
 // folded at, so the 90th percentile of their lengths stands for it, between 80 and 120.
 function foldWidth(text) {
@@ -406,19 +403,20 @@ function numericCount(pair) {
 function plain(value) {
     return JSON.parse(JSON.stringify(value));
 }
-function samePlans(raw, dropped, text, cwd) {
+// The YAML rewrite against v2ToV3Raw of the source without the dropped keys: two rewrites written
+// separately, which must parse to the same study and plan the same runs.
+function samePlans(raw, route, dropped, text, cwd) {
     const projected = structuredClone(raw);
     for (const path of dropped)
         deletePlainFieldPath(projected, path);
-    const before = parseStudyDocument(projected);
+    const before = parseStudy(v2ToV3Raw(projected, route));
     if (!before.ok) {
         return refuse(`it does not parse once the unread keys are dropped: ${before.error.message}`);
     }
-    const after = parseStudyDocument(parseDocument(text).toJS());
+    const after = parseStudy(parseDocument(text).toJS());
     if (!after.ok)
         return refuse(`its v3 form does not parse: ${after.error.message}`);
-    if (JSON.stringify(plain({ ...after.config, schema: V2_SCHEMA })) !==
-        JSON.stringify(plain(before.config))) {
+    if (JSON.stringify(plain(after.config)) !== JSON.stringify(plain(before.config))) {
         return refuse("its v3 form parses to a different study.");
     }
     for (const dryRun of [true, false]) {

package/dist/study/{migrate.d.ts → migrate/migrate.d.ts}

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "./routing.js";
+import type { StudyRoute } from "../routing.js";
 import { type DroppedKey, type MovedKey } from "./convert.js";
 /** The schema of `humanish migrate --json`. */
 declare const MIGRATE_SCHEMA = "humanish.migrate-result.v1";

package/dist/study/{migrate.js → migrate/migrate.js}

@@ -14,9 +14,9 @@ import { randomUUID } from "node:crypto";
 import { link, lstat, readdir, readFile, realpath, rename, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { parseDocument } from "yaml";
-import { isNodeError } from "../run/type-guards.js";
+import { isNodeError } from "../../run/type-guards.js";
 import { convertStudyText, isStudyV3 } from "./convert.js";
-import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "./files.js";
+import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "../files.js";
 import { assertDirectory, bindDirectory, exists, fileIdentity, NO_HARD_LINKS, removeChecked, removeOwned, restoreName, sameFile, sha256, writeOwned, } from "./owned-files.js";
 /** The schema of `humanish migrate --json`. */
 const MIGRATE_SCHEMA = "humanish.migrate-result.v1";

package/dist/study/{owned-files.js → migrate/owned-files.js}

@@ -6,7 +6,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import path from "node:path";
-import { isNodeError } from "../run/type-guards.js";
+import { isNodeError } from "../../run/type-guards.js";
 export function sha256(bytes) {
     return createHash("sha256").update(bytes).digest("hex");
 }

package/dist/study/migrate/v2.d.ts

@@ -0,0 +1,68 @@
+import { type StudyRoute } from "../routing.js";
+import { type StudyConfig, type StudyParticipantEntry, type StudyScenarioCaps } from "../types.js";
+type Raw = Record<string, unknown>;
+type Read<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+/** `laneFocus`: the steer each of a counted group of participants gets. */
+interface V2Focus {
+    id?: string;
+    label?: string;
+    instruction?: string;
+}
+/** The `scenario` object. */
+interface V2Scenario {
+    ref?: string;
+    mode?: "dry-run" | "live";
+    inline?: Raw;
+    caps?: StudyScenarioCaps;
+}
+/** A v2 file that checkV2 accepted, as the v2 parser reads it. */
+export interface V2Study {
+    readonly route: StudyRoute;
+    /**
+     * The sections that decide the route and that the v2 parser's first cross-section checks read:
+     * subject, the actor without its participant keys, execution, policies and comms.
+     */
+    readonly composition: StudyConfig;
+    readonly count: number | undefined;
+    /** `actors[0].lanes`, or the participants `actors[0].roster` expands into. */
+    readonly entries: readonly StudyParticipantEntry[] | undefined;
+    readonly focus: V2Focus | undefined;
+    readonly executionCaps: StudyScenarioCaps | undefined;
+    readonly scenario: V2Scenario | undefined;
+    readonly personas: boolean;
+    readonly terminalTimeout: boolean;
+}
+/**
+ * Check a humanish.lab.v2 file the way the v2 parser does, up to the checks that read more than
+ * one section, and then the budget rule those checks apply first. Each refusal is that parser's
+ * message.
+ */
+export declare function checkV2(raw: Raw): Read<V2Study>;
+/**
+ * The refusals the v2 parser gives for shapes a v3 file cannot express, once the checks both
+ * formats share have passed on the study without them. A file that also breaks a shared check
+ * gets that check's message.
+ */
+export declare function v2ShapeReason(study: V2Study): string | undefined;
+/**
+ * A v2 file as a plain humanish.study.v3 record, for parseStudyV3 and parseStudy. It reads each key
+ * it moves the way the v2 parser reads it (`count` as a positive integer, `laneFocus` through its
+ * string fields, `roster` groups expanded, `scenario.ref` and `scenario.mode` as strings), and
+ * leaves out every key no v3 file can hold, so it parses whenever the v2 parser would. A caps
+ * block keeps the keys its route reads. A shared world keeps a count or no list, which only
+ * parseStudyV3's report mode takes.
+ */
+export declare function v2ToV3Raw(raw: Raw, route: StudyRoute): Raw;
+/**
+ * The keys migrate drops: the v2-only rows above and `inert`, the fields parseStudyV3 reports the
+ * route does not read, then terminal `execution.timeoutMs`, which no terminal code reads. Parents
+ * come before their children, so a child under a dropped parent is reported with the parent.
+ */
+export declare function droppedPaths(study: V2Study, inert: readonly string[]): string[];
+export {};