humanish 0.106.1 → 0.108.0

package/dist/lab/init-templates.js

@@ -4,29 +4,30 @@ export const DEFAULT_LOCAL_BROWSER_STARTER = {
 };
 function localBrowserLab(starter = DEFAULT_LOCAL_BROWSER_STARTER) {
     return {
-        path: "humanish/labs/local-browser.yaml",
+        path: "humanish/studies/local-browser.yaml",
         plane: "source",
-        contents: `schema: humanish.lab.v2
+        contents: `schema: humanish.study.v3
 id: local-browser
 title: Local browser · your app · Codex account
 description: >-
-  Run a Codex-account participant in an isolated local browser against your loopback app—no E2B
-  or OpenAI API key. Inference is remote and uses account quota. Before the first live run, use
-  humanish doctor --lab local-browser to check the supported Codex login and local runtime.
+  Runs one participant on your Codex account in an isolated local browser against your loopback
+  app. Needs no E2B or OpenAI API key: inference is remote and uses your Codex account quota.
+  Before the first live run, check the Codex login and the local runtime with humanish doctor
+  --study local-browser.
+route: computer-use
+mode: live
 subject:
   source: app-url
   appUrl: ${JSON.stringify(starter.appUrl)}
-actors:
-  - type: local-agent
-    localAgent: codex
-    persona: synthetic-new-user
-    mission: ${JSON.stringify(starter.mission)}
+actor:
+  type: local-agent
+  localAgent: codex
+  persona: synthetic-new-user
+  mission: ${JSON.stringify(starter.mission)}
 execution:
   target: local
   concurrency: 1
   timeoutMs: 120000
-scenario:
-  mode: live
 defaults:
   open: true
 `,
@@ -34,51 +35,53 @@ defaults:
 }
 /**
  * The flagship live lab. A ChatGPT-account Codex participant has no API-dollar price, so preflight
- * refuses a dollar cap on it (HUMANISH_CUA_LAB_UNPRICED_CAP); that variant is bounded by the
+ * refuses a dollar cap on it (HUMANISH_COMPUTER_USE_UNPRICED_CAP); that variant is bounded by the
  * session timeout instead of a cap it could never enforce.
  */
 function tryLiveLab(actor, localAgent = "codex") {
     const account = actor === "local-agent";
-    const cost = account
-        ? `  WHAT IT COSTS: one participant, one small task, a few E2B desktop minutes and your Codex
-  account's usage. Account usage has no dollar price humanish can enforce, so the ten-minute
-  session limit below bounds the run.`
-        : `  WHAT IT COSTS: one participant, one small task, and a $2 cap on estimated model spend. The
-  run stops before its next model request once the estimate passes $2, so the last request can take
-  it slightly over. Hosted desktop time is billed separately.`;
+    const needs = account
+        ? `  Needs E2B_API_KEY and the coding agent signed in on this machine. Cost: one small task, a few
+  E2B desktop minutes and the agent's account usage. humanish cannot put a dollar cap on account
+  usage, so the ten-minute session limit below bounds the run.`
+        : `  Needs E2B_API_KEY and OPENAI_API_KEY. Cost: one small task with a $2 cap on estimated model
+  spend. The run stops before its next model request once the estimate passes $2, so the last
+  request can go slightly over, and hosted desktop time is billed separately.`;
     const participant = account
-        ? `  # Your machine has a coding agent signed in, so this lab uses it: no provider API key,
-  # only E2B. To use a provider key instead, swap to \`type: openai-computer-use\` and add
-  # execution.caps.maxUsd.
-  - type: local-agent
-    localAgent: ${localAgent}`
-        : `  - type: openai-computer-use
-    # Bounds each model reply. Under the cap below it also bounds what a stalled or lost request
-    # can cost, so the run can retry it instead of stopping.
-    maxOutputTokens: 8192`;
-    const bound = account
+        ? `# Your machine has a coding agent signed in, so this study uses it: no provider API key, only
+# E2B. To use a provider key instead, swap to \`type: openai-computer-use\` and add caps.maxUsd.
+actor:
+  type: local-agent
+  localAgent: ${localAgent}`
+        : `actor:
+  type: openai-computer-use
+  # Bounds each model reply. Under the cap below it also bounds what a stalled or lost request
+  # can cost, so the run can retry it instead of stopping.
+  maxOutputTokens: 8192`;
+    const caps = account
+        ? ""
+        : `caps:
+  maxUsd: 2 # estimated model spend; the run stops before its next request once it passes this
+`;
+    const timeout = account
         ? "  timeoutMs: 600000 # bounds the run; a dollar cap cannot be enforced on account usage"
-        : `  timeoutMs: 600000
-  caps:
-    maxUsd: 2 # estimated model spend; the run stops before its next request once it passes this`;
+        : "  timeoutMs: 600000";
     return {
-        path: "humanish/labs/try-live.yaml",
+        path: "humanish/studies/try-live.yaml",
         plane: "source",
-        contents: `schema: humanish.lab.v2
+        contents: `schema: humanish.study.v3
 id: try-live
-title: Your first REAL study — one participant, a real app, a hosted desktop
+title: "Your first live study: one participant on a demo app"
 description: >-
-  This lab runs live out of the box, on purpose. Every other starter file here is a template you
-  have to fill in first, and a first live run that cannot succeed is where most people stop.
-  THE SUBJECT IS A DEMO, NOT YOUR APP: it clones drawDB, a real public open-source diagram editor,
-  and serves it inside the sandbox. That is what makes this runnable with nothing to configure.
-  Once you have watched it work, point subject at your own app (see humanish/labs/cua-browser.yaml
-  for the shape) — that is the study you actually want.
-${cost}
-  WHAT A GOOD RESULT LOOKS LIKE: not necessarily a pass. A participant who gets stuck and says so
-  is the most useful thing this tool produces — humanish will refuse to call that a credible pass,
-  on purpose, and the friction they describe is the finding. A first run that ends in "I could not
-  do it, and here is where I got lost" worked exactly as intended.
+  Runs one participant live on drawDB, a public open-source diagram editor that humanish clones
+  and serves in a hosted desktop, so it runs with nothing to configure. The app under study is
+  that demo, not yours. The other starter studies need your app's details first.
+${needs}
+  A participant who gets stuck and says where is a useful result: humanish does not count that
+  run as a pass, and the friction the participant describes is the finding. To study your own
+  app, change subject; humanish/studies/cua-browser.yaml shows the shape.
+route: computer-use
+mode: live # the other starter studies start as dry runs
 subject:
   source: clone
   repos:
@@ -86,22 +89,19 @@ subject:
   clone:
     depth: 1
   serve:
-    # Plain npm — humanish provides the Node runtime the stock desktop image does not ship.
+    # Plain npm: humanish provides the Node runtime that the stock desktop image lacks.
     install: npm install --no-audit --no-fund
     build: npm run build
     start: npx vite preview --host 127.0.0.1 --port 3000
     url: http://127.0.0.1:3000/
-actors:
 ${participant}
-    persona: synthetic-new-user
-    mission: >-
-      You have never seen this diagram tool before. Add two tables and give them meaningful names,
-      then stop and say what you did, what confused you, and where you hesitated.
-execution:
+  persona: synthetic-new-user
+  mission: >-
+    You have never seen this diagram tool before. Add two tables and give them meaningful names,
+    then stop and say what you did, what confused you, and where you hesitated.
+${caps}execution:
   target: e2b-desktop
-${bound}
-scenario:
-  mode: live # the point of this lab — the others start as dry-run
+${timeout}
 defaults:
   open: true
 `,
@@ -113,7 +113,8 @@ export const starterFiles = [
         plane: "source",
         contents: `# humanish
 
-This directory is the committed source of persona simulation intent for this app.
+This directory holds the committed definitions of this app's humanish studies: study files,
+personas and scenarios.
 
 Keep this directory public-safe:
 
@@ -124,11 +125,13 @@ Keep this directory public-safe:
 
 Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
 
-Labs:
+Studies:
 
-- committed reusable labs live in humanish/labs/*.yaml;
-- private or machine-local labs live in ignored .humanish/labs/*.yaml or .humanish/local/labs/*.yaml;
-- run a lab with \`humanish watch <lab>\` or \`humanish lab run <lab>\`.
+- 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:
 
@@ -207,19 +210,21 @@ steps:
 `,
     },
     {
-        path: "humanish/labs/first-run.yaml",
+        path: "humanish/studies/first-run.yaml",
         plane: "source",
-        contents: `schema: humanish.lab.v2
+        contents: `schema: humanish.study.v3
 id: first-run
 title: First-run synthetic Observer
-description: Public-safe starter lab that generates a synthetic run bundle and Observer without provider spend.
+description: >-
+  Does a dry run: writes a synthetic run bundle and Observer for four participants. Needs no browser,
+  model or keys, and costs nothing. Run it with humanish run first-run.
+route: preview
+mode: dry-run
 subject:
   source: this-repo
-actors:
-  - type: synthetic-persona
-    count: 4
-scenario:
-  mode: dry-run
+actor:
+  type: synthetic-persona
+participants: 4
 defaults:
   open: true
 `,
@@ -227,19 +232,21 @@ defaults:
     tryLiveLab("openai-computer-use"),
     localBrowserLab(),
     {
-        path: "humanish/labs/cua-browser.yaml",
+        path: "humanish/studies/cua-browser.yaml",
         plane: "source",
-        contents: `schema: humanish.lab.v2
+        contents: `schema: humanish.study.v3
 id: cua-browser
-title: Computer-use browser lab
+title: Computer-use browser study
 description: >-
-  A registered computer-use actor drives your app in a hosted desktop browser and emits an
-  evidence bundle into gitignored .humanish/. Screenshots are full-fidelity (raw) by default;
-  set policies.redactScreenshots: true to blur at capture for a share-as-is bundle. Typed
-  text is recorded as length only. Dry-run by default; switch scenario.mode to live (with
-  OPENAI_API_KEY + E2B_API_KEY via --env-file) for a real session. The clone subject below
-  serves your repo INSIDE the sandbox; declared subject env NAMES are provisioned from
-  --env-file (values are never persisted).
+  A computer-use participant drives your app in a hosted desktop browser and writes its evidence
+  to gitignored .humanish/. Starts as a dry run. For a live session, set mode to live
+  and pass OPENAI_API_KEY and E2B_API_KEY with --env-file. The clone subject below serves your
+  repo inside the sandbox, and the env names declared under subject get their values from
+  --env-file without the values being saved. Screenshots keep full fidelity by default; set
+  policies.redactScreenshots: true to blur them at capture for a bundle you can share as is.
+  Typed text is recorded as its length only.
+route: computer-use
+mode: dry-run
 subject:
   source: clone
   repos: [your-org/your-app]
@@ -251,7 +258,7 @@ subject:
     # installTimeoutMs: 1200000   # bump for monorepo-scale installs/builds (default 600000)
     # buildTimeoutMs: 1800000
   # env: [DATABASE_URL]
-  # state:                        # the subject's STATE story (recorded as provenance):
+  # state:                        # the subject's state, recorded as provenance:
   #   seed:                       # ordered, bounded seed/migration/fixture steps (commands are
   #     - name: db-up             # author-trusted; evidence records sha256 digests, never text)
   #       command: sudo service postgresql start && pg_isready -t 30
@@ -259,104 +266,97 @@ subject:
   #     - name: db-migrate
   #       command: pnpm prisma migrate deploy
   #       timeoutMs: 300000       # per-step budget (default 300000)
-  #     - name: admin-user        # after-ready steps run against the RUNNING app
+  #     - name: admin-user        # after-ready steps run against the running app
   #       command: curl -sf -X POST http://127.0.0.1:3000/api/test/bootstrap-admin
   #       when: after-ready
-  #   # Or point at a shared DB you do NOT control — recorded as UNPINNED in provenance;
+  #   # Or point at a shared DB you do not control; provenance records it as unpinned.
   #   # each name must also be declared in subject.env:
   #   # external: [DATABASE_URL]
   # clone:
-  #   keep: true                  # leave the sandbox up on FAILURE so you can debug install/boot
+  #   keep: true                  # keep the sandbox after a failure to debug install or boot
   # Alternative: drive a deployment you own (Vercel preview, staging) instead of a clone:
   # source: app-url
   # appUrl: https://your-preview.vercel.app/
-actors:
-  - type: openai-computer-use
-    persona: first-time-visitor
-    mission: >-
-      Explore the app as a brand-new user trying to complete its primary flow. Note anything
-      confusing. Stop when the flow completes or you are stuck.
+actor:
+  type: openai-computer-use
+  persona: synthetic-new-user
+  mission: >-
+    Explore the app as a brand-new user trying to complete its primary flow. Note anything
+    confusing. Stop when the flow completes or you are stuck.
 execution:
   target: e2b-desktop
-  # 20 minutes: a session should end because the participant finished, not because a timer fired,
-  # so this is as long as the substrate allows rather than as long as seems reasonable. This route
-  # clones, installs, builds and serves the subject before the actor starts, so the sandbox deadline
-  # is this budget PLUS 40 minutes of provisioning and teardown headroom — and a sandbox may not
-  # live longer than 60. Raising this above 20 minutes fails the run closed before it starts; raise
-  # execution.desktop.sandboxTimeoutMs deliberately if you need more.
-  # Spend protection belongs to the dollar caps, not the clock.
+  # 20 minutes, the longest this route allows, so a session ends when the participant finishes.
+  # The route clones, installs, builds and serves the subject before the participant starts, so
+  # the sandbox deadline is this budget plus 40 minutes of provisioning and teardown, and a sandbox
+  # lives at most 60 minutes. A value above 20 minutes fails the run before it starts; raise
+  # execution.desktop.sandboxTimeoutMs if you need more. The dollar caps limit spend.
   timeoutMs: 1200000
   desktop:
     device: desktop             # mobile | small-mobile | narrow-mobile | tablet | desktop | wide
     # browser: chrome            # default | chrome | chromium | firefox; concrete values fail closed
     # Presets size the physical screen; Chrome's window width has a ~500px minimum.
     # For mobile presets, opt into CSS viewport, touch, DPR and mobile user-agent emulation:
-    # fidelity: { mobileEmulation: true } # Chrome/Chromium only; desktop/tablet lanes unchanged
+    # fidelity: { mobileEmulation: true } # Chrome/Chromium only; desktop and tablet are unchanged
     # The bundle records measured screen, page viewport and emulation fidelity separately.
-scenario:
-  mode: dry-run
 # policies:
-#   redactScreenshots: true       # blur persisted frames (default off — full fidelity for local use)
+#   redactScreenshots: true       # blur saved frames (off by default: full fidelity for local use)
 #   allowPublicTargets: true      # required to drive a non-loopback app-url (a deployment you own)
 defaults:
   open: true
 `,
     },
     {
-        path: "humanish/labs/lobby-trivia-3player.yaml",
+        path: "humanish/studies/lobby-trivia-3player.yaml",
         plane: "source",
-        contents: `schema: humanish.lab.v2
+        contents: `schema: humanish.study.v3
 id: lobby-trivia-3player
-title: External-public shared world (N mobile personas share ONE public app at once)
+title: "Shared world on a public app: three mobile participants in one lobby"
 description: >-
-  A worked example of the EXTERNAL-PUBLIC shared-world route (#164 phase 2): N mobile-LAYOUT
-  personas play the SAME multiplayer lobby on a REAL public deployment AT ONCE. The public site is
-  the shared plane DIRECTLY — NO clone, NO getHost, NO subject sandbox, NO seed. A host-first barrier
-  extracts the shared-session code from the host seat's CDP-observed URL and threads it into the
-  follower join missions (followers go through the real Join flow). Dry-run (the default) emits ONE
-  external-public evidence bundle at $0. A live run needs OPENAI_API_KEY + E2B_API_KEY and
-  scenario.mode: live. Point appUrl + publicTarget at a public deployment YOU own/operate.
-  MOBILE FIDELITY: by default Chrome's physical window has a 500px minimum width, no touch
-  emulation and desktop DPR/user-agent behavior. Set execution.desktop.fidelity.mobileEmulation to true
-  to request the mobile preset's CSS viewport, touch, DPR and mobile user agent on Chrome/Chromium.
-  The bundle records measured geometry and emulation fidelity. HONESTY: attribution stays
-  shared-world, but every strength claim degrades honestly — provenance external-public (not seeded),
-  NO synthetic attestation (you cannot claim synthetic on a real site), NO authoritative shared-state
-  proof, concurrency by temporal co-occupancy + observed lobby convergence.
+  A worked example of the external-public shared-world route: three participants on mobile layouts
+  play the same multiplayer lobby on a public deployment at the same time. The public site is the
+  shared plane, so there is no clone, subject sandbox or seed. The host participant creates the
+  lobby, humanish reads the session code from the host's page URL, and the other participants get
+  it in their missions and join through the app's own join flow. Starts as a dry run, which writes
+  one evidence bundle at no cost. A live run needs OPENAI_API_KEY, E2B_API_KEY and mode: live. Point appUrl and publicTarget at a public deployment you own or operate. Mobile layout:
+  Chrome's physical window is at least 500px wide and has no touch emulation, desktop pixel ratio
+  and a desktop user agent. Set execution.desktop.fidelity.mobileEmulation to true to request the
+  preset's CSS viewport, touch, pixel ratio and mobile user agent on Chrome or Chromium; the bundle
+  records the measured geometry and emulation fidelity. A run on a public site proves less than a
+  provisioned one: its provenance is external-public, it carries no synthetic-data attestation and
+  no authoritative shared-state proof, and concurrency rests on overlapping sessions and every
+  participant reaching the same lobby.
+route: shared-world
+mode: dry-run # a live run opens three mobile-layout desktops against the public app
 subject:
-  source: app-url # the real public deployment IS the shared plane (no clone, no getHost)
-  topology: shared-world # the declared override of the per-lane-worlds default
-  appUrl: https://your-public-app.example/ # a deployment YOU own/operate
-  publicTarget: # REQUIRED ownership attestation (the honest analog of exposure: synthetic)
+  source: app-url # the public deployment is the shared plane: no clone and no getHost
+  appUrl: https://your-public-app.example/ # a deployment you own or operate
+  publicTarget: # required: your attestation that you own or operate this deployment
     owner: your-org/your-app
     authorized: true
 policies:
-  allowPublicTargets: true # REQUIRED: the shared plane is a real non-loopback public deployment
-actors:
-  - type: openai-computer-use
-    mission: You are one of several users on the same shared session at once. Play your role, then stop.
-    lanes: # the roster (>=2) with EXACTLY ONE host: true seat
-      - id: host
-        host: true # the designated host seat that creates the shared session
-        device: mobile # 414x896 preset; physical window width floors to 500 (see emulation above)
-        instruction: Create a shared lobby, wait for the others to join, then start and play.
-      - id: player-2
-        device: mobile
-        instruction: Join the lobby you're told the code for, then play.
-      - id: player-3
-        device: small-mobile
-        instruction: Join the lobby you're told the code for, then play.
+  allowPublicTargets: true # required: the shared plane is a public, non-loopback deployment
+actor:
+  type: openai-computer-use
+  mission: You are one of several users on the same shared session at once. Play your role, then stop.
+participants: # at least two participants, exactly one with host: true
+  - id: host
+    host: true # this participant creates the shared session
+    device: mobile # 414x896 preset; physical window width floors to 500 (see emulation above)
+    instruction: Create a shared lobby, wait for the others to join, then start and play.
+  - id: player-2
+    device: mobile
+    instruction: Join the lobby you're told the code for, then play.
+  - id: player-3
+    device: small-mobile
+    instruction: Join the lobby you're told the code for, then play.
 execution:
   target: e2b-desktop
-  # PER-SEAT session budget; also caps the host-first handoff deadline. Budget for the WHOLE arc:
-  # seat provisioning + shared-session assembly + actual play. A first live run of the worked
-  # example died at 120000 with every seat expiring mid game and zero mission actions taken.
+  # Each participant's session budget, which also bounds the host's handoff deadline. It has to
+  # cover provisioning, joining the shared session and play; 420000 ms (7 minutes) does.
   timeoutMs: 420000
-  concurrency: 3 # all 3 seats live at once (the default when omitted); lower only to cap paid desktops
+  concurrency: 3 # all three participants at once, the default; lower it only to limit paid desktops
   # desktop:
   #   fidelity: { mobileEmulation: true } # opt into mobile CSS viewport, touch, DPR and user agent
-scenario:
-  mode: dry-run # default; the live path opens N real mobile-layout seats against the public app
 defaults:
   open: true
 `,
@@ -388,8 +388,8 @@ export const runtimeDirectories = [
     { path: ".humanish/cache", plane: "runtime" },
     { path: ".humanish/tmp", plane: "runtime" },
     { path: ".humanish/logs", plane: "runtime" },
-    { path: ".humanish/labs", plane: "runtime" },
-    { path: ".humanish/local/labs", plane: "runtime" },
+    { path: ".humanish/studies", plane: "runtime" },
+    { path: ".humanish/local/studies", plane: "runtime" },
     { path: ".humanish/local/personas", plane: "runtime" },
 ];
 export const humanishScripts = {
@@ -408,9 +408,9 @@ export const humanishScripts = {
  * 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) {
-    return starterFiles.map((file) => file.path === "humanish/labs/local-browser.yaml"
+    return starterFiles.map((file) => file.path === "humanish/studies/local-browser.yaml"
         ? localBrowserLab(localBrowser)
-        : file.path === "humanish/labs/try-live.yaml"
+        : file.path === "humanish/studies/try-live.yaml"
             ? tryLiveLab(actor, localAgent)
             : file);
 }

package/dist/lab/init.d.ts

@@ -26,7 +26,7 @@ export interface InitResult {
     changes: InitChange[];
     warnings: string[];
     /**
-     * The next one or two commands, already resolved against THIS machine's credentials. Present on
+     * The next one or two commands, already resolved against this machine's credentials. Present on
      * an applied init; absent on a dry-run or a failure, where there is no "next" yet.
      */
     nextSteps?: string[];

package/dist/lab/init.js

@@ -8,6 +8,7 @@ import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory,
 import { validateCwd } from "../run/project.js";
 import { pathExists, readTextIfExists, validateInitProjectPaths } from "./init-paths.js";
 import { planGitignore, planPackageJson } from "./init-plan.js";
+import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "../study/files.js";
 const INIT_RESPONSE_SCHEMA = "humanish.init-result.v1";
 export async function runInit(options) {
     const requestedCwd = path.resolve(options.cwd);
@@ -39,7 +40,7 @@ export async function runInit(options) {
     await planAgentsFile(preparedProjectRoot, cwd, plan);
     // The starter live lab is written for the brain this machine can actually use. Shipping it as
     // openai-computer-use on a machine with no provider key but a signed-in Codex would hand someone
-    // a file that asks for a credential they were just told they do not need (#505).
+    // a file that asks for a credential they were just told they do not need.
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
     const starterActor = starterActorFor(machine);
     await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
@@ -77,16 +78,16 @@ export async function runInit(options) {
         cwd: requestedCwd,
         changes: plan.changes,
         warnings: plan.warnings,
-        // Resolved against THIS machine, because a next step that cannot work is worse than none.
+        // Resolved against this machine, because a next step that cannot work is worse than none.
         ...(mode === "applied" ? { nextSteps: firstRunGuidance(machine) } : {}),
     };
 }
-// Leave instructions for the NEXT agent. AGENTS.md is the cross-vendor convention (agents.md) —
-// Codex, Claude Code, Cursor, Aider and others read it — and increasingly the thing that runs
+// Leave instructions for the next agent. `AGENTS.md` is the cross-vendor convention (agents.md);
+// Codex, Claude Code, Cursor, Aider and others read it, and increasingly the thing that runs
 // `humanish init` is a coding agent doing setup on someone's behalf. Without this, the agent
 // that arrives tomorrow finds a humanish/ directory and no idea what to do with it.
 //
-// APPEND-ONLY and idempotent: an existing AGENTS.md is a file someone wrote, so humanish adds its
+// Append-only and idempotent: an existing `AGENTS.md` is a file someone wrote, so humanish adds its
 // own section once and never rewrites theirs.
 async function planAgentsFile(preparedProjectRoot, cwd, plan) {
     const agentsPath = "AGENTS.md";
@@ -136,10 +137,22 @@ async function planStarterFiles(preparedProjectRoot, cwd, files, localBrowserReq
         const existing = await readTextIfExists(preparedProjectRoot, file.path);
         if (existing !== null &&
             localBrowserRequested &&
-            file.path === "humanish/labs/local-browser.yaml") {
-            plan.warnings.push("Skipped --local-browser/--local-mission: humanish/labs/local-browser.yaml already exists and init never overwrites it.");
+            file.path === "humanish/studies/local-browser.yaml") {
+            plan.warnings.push("Skipped --local-browser/--local-mission: humanish/studies/local-browser.yaml already exists and init never overwrites it.");
         }
-        if (existing === null) {
+        const others = existing === null ? await otherStudyFilesFor(preparedProjectRoot, file.path) : [];
+        if (others.length > 0) {
+            const stem = studyFileStem(path.basename(file.path));
+            plan.changes.push({
+                path: file.path,
+                action: "skip",
+                target: file.plane,
+                reason: `${others.join(", ")} already uses the name ${stem}`,
+            });
+            const legacy = others.some((other) => other.split(path.sep).includes("labs"));
+            plan.warnings.push(`Skipped ${file.path}: ${others.join(", ")} already uses the name ${stem}, and a second file with that name would make \`run ${stem}\` fail.${legacy ? " Run humanish migrate to move it to a studies/ directory." : ""}`);
+        }
+        else if (existing === null) {
             plan.changes.push({
                 path: file.path,
                 action: "create",
@@ -172,6 +185,25 @@ async function planStarterFiles(preparedProjectRoot, cwd, files, localBrowserReq
         }
     }
 }
+/**
+ * The study files that already use a starter study's name in any study directory, other than the
+ * starter's own path. An unsafe path counts as present, so init skips the starter rather than
+ * failing.
+ */
+async function otherStudyFilesFor(preparedProjectRoot, relativePath) {
+    const stem = studyFileStem(path.basename(relativePath));
+    const inStudyDirectory = STUDY_DIRECTORIES.some((directory) => directory.relativeDir === path.dirname(relativePath));
+    if (stem === undefined || !inStudyDirectory)
+        return [];
+    return otherStudyFiles(stem, async (candidate) => {
+        try {
+            return (await readTextIfExists(preparedProjectRoot, candidate)) !== null;
+        }
+        catch {
+            return true;
+        }
+    }, relativePath);
+}
 /** Create each ignored runtime directory that is missing. */
 async function planRuntimeDirectories(preparedProjectRoot, cwd, plan) {
     for (const directory of runtimeDirectories) {
@@ -254,7 +286,7 @@ async function firstRunEnvironment(env, cwd) {
     const present = (name) => keys.some((key) => key.name === name && key.source !== null);
     let hasDesktopSdk = false;
     try {
-        // Resolution from the PROJECT, not from wherever humanish itself lives.
+        // Resolution starts from the project, wherever humanish itself is installed.
         const { createRequire } = await import("node:module");
         createRequire(path.join(process.cwd(), "package.json")).resolve("@e2b/desktop");
         hasDesktopSdk = true;

package/dist/lab/keys.d.ts

@@ -1,2 +1,4 @@
 /** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
 export declare function findUnknownLabKey(raw: unknown): string | undefined;
+/** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
+export declare function findUnknownStudyKey(raw: unknown): string | undefined;