turnzero 0.18.2-next.1 → 0.18.3-next.1

package/dist/turnzero-cloud.mjs

@@ -200,6 +200,7 @@ var LOCAL_RUN_SETTING = Object.freeze({
 });
 var RETIRED_PLATFORM_CREDENTIAL_SETTING = "TURNZERO_CLOUD_TOKEN";
 var LOCAL_RUN_ENVIRONMENT = "local";
+var REMINT_FILE_INSTRUCTION_TAIL = " from it in the development environment file now.";
 var LOCAL_RUN_CREDENTIAL_SETTINGS = Object.freeze([LOCAL_RUN_SETTING.platformCredential, LOCAL_RUN_SETTING.databaseConnection]);
 var ENVIRONMENT_FILE_NAME = ".env";
 var provisionBareLineOf = (call) => commandLineOf(call.origin, PROVISION_SUBCOMMAND, {
@@ -504,15 +505,21 @@ var planeObjectOf = (text) => {
     return null;
   }
 };
+var platformMarked = (text) => {
+  const version = planeObjectOf(text)?.contract_version;
+  return typeof version === "number" && Number.isInteger(version) && version > 0;
+};
 var redirected = (answer) => answer.type === "opaqueredirect" || answer.status >= 300 && answer.status <= 399;
 var answeredHow = (status) => status >= 100 ? `HTTP ${status}` : "with a redirect";
 var ANSWER_KINDS = Object.freeze(["refused", "failed"]);
 var answerLineOf = (act, kind, status, error) => `${act} ${kind} (HTTP ${status}): ${error}`;
+var PLATFORM_FAILURE_STATUS = 500;
+var notThePlatformLine = (act, status) => `The ${act} was answered HTTP ${status}, not by the platform.`;
+var markedRefusalOf = (status, text) => status < PLATFORM_FAILURE_STATUS && !platformMarked(text) ? null : planeRefusalOf(text);
 var refusalLines = (act, status, refusal) => [
   answerLineOf(act, "refused", status, refusal.error),
   ...refusal.detail !== null ? [oneLine(refusal.detail)] : []
 ];
-var PLATFORM_FAILURE_STATUS = 500;
 var failureLines = (act, status, said) => said === null ? [`The ${act} was answered HTTP ${status}, a failure of the platform's or of a server between.`] : [answerLineOf(act, "failed", status, said.error), ...said.detail !== null ? [oneLine(said.detail)] : []];
 var HEALTH_READ_PATH = "/healthz";
 var PLANE_CHECK_BOUND_SECONDS = 10;
@@ -812,7 +819,8 @@ var CREDENTIAL_SOURCES = Object.freeze(["standard_input", "minted_token_variable
 var credentialPlaces = (declared) => declared.places ?? `the command reads the grant from its standard input, as the line ${declared.call} answers pipes it in${declared.mintedToken ? `, and otherwise a minted token from ${MINTED_TOKEN_VARIABLE} where it is set, or this computer's token for the platform's address from its credential file, which login and authorize write` : declared.computerToken === true ? `, and otherwise this computer's token for the platform's address from its credential file, which login and authorize write, and never a minted token from ${MINTED_TOKEN_VARIABLE}` : ""}.`;
 var unsetVariableWayOn = (declared) => `To run a line you wrote yourself under this computer's token, unset ${MINTED_TOKEN_VARIABLE} and run it again; or pipe ${declared.aGrant}.`;
 var grantWaysOn = (declared) => `Pipe ${declared.aGrant}, as the line ${declared.call} answers pipes it, or, where you wrote the line yourself, pipe nothing to run it under this computer's token.`;
-var emptyGrantRefusal = (declared) => `The ${declared.grant} piped to the command was empty, so nothing was sent and nothing was started. ${grantWaysOn(declared)}`;
+var emptyGrantRefusal = (declared) => emptyPipeRefusal(declared, grantWaysOn(declared));
+var emptyPipeRefusal = (declared, wayOn) => `The ${declared.grant} piped to the command was empty, so nothing was sent and nothing was started. ${wayOn}`;
 var unendedReadRefusal = (declared, reading, nothingArrived = false) => unendedReadSentence(
   declared.grant,
   reading,
@@ -828,7 +836,9 @@ async function readCredential(io2, declared, again, line = { named: void 0, clos
     const unended = unendedReadingOf(read3);
     if (unended !== null) return { refusal: unendedReadRefusal(declared, unended, read3.bytes === 0) };
     const grant = read3.text.trim();
-    if (declared.computerToken === true && grant === "" && read3.bytes > 0) return { refusal: emptyGrantRefusal(declared) };
+    if (declared.emptyPipeRefused === true && grant === "" && read3.bytes > 0) {
+      return { refusal: declared.computerToken === true ? emptyGrantRefusal(declared) : emptyPipeRefusal(declared, again) };
+    }
     if (grant !== "") {
       if (!UPLOAD_GRANT_FORM.test(grant)) {
         return { refusal: `What the command read as its ${declared.grant} is not ${declared.aGrant}, so nothing was sent and nothing was started. ${again}` };
@@ -1107,7 +1117,7 @@ async function revokeUnder(io2, origin, token2, id, userAgent) {
   if (answered.status >= 200 && answered.status <= 299) {
     return revokedRowOf(planeObjectOf(answered.text), id) ? { revoked: true } : { lines: [`${REVOKE_TOKEN_ACTION} was answered HTTP ${answered.status} with no revocation of token ${id} the command can read.`], known: false };
   }
-  const refusal = planeRefusalOf(answered.text);
+  const refusal = markedRefusalOf(answered.status, answered.text);
   if (refusal === null) return { lines: [`${REVOKE_TOKEN_ACTION} was answered HTTP ${answered.status}, not by the platform.`], known: false };
   if (NO_LONGER_SERVES.includes(answered.status)) return { ended: true };
   return { lines: refusalLines(REVOKE_TOKEN_ACTION, answered.status, refusal), known: true };
@@ -1155,8 +1165,8 @@ async function readAccountUnder(io2, origin, token2, userAgent) {
     const account = accountOf(planeObjectOf(answered.text));
     return account !== null ? { account } : { lines: [`The ${ACCOUNT_READ_ACT} was answered HTTP ${answered.status} with no account the command can read.`], refused: false };
   }
-  const refusal = planeRefusalOf(answered.text);
-  if (refusal === null) return { lines: [`The ${ACCOUNT_READ_ACT} was answered HTTP ${answered.status}, not by the platform.`], refused: false };
+  const refusal = markedRefusalOf(answered.status, answered.text);
+  if (refusal === null) return { lines: [notThePlatformLine(ACCOUNT_READ_ACT, answered.status)], refused: false };
   return { lines: refusalLines(ACCOUNT_READ_ACT, answered.status, refusal), refused: true };
 }
 var whoamiLineFor = (io2, origin) => printedLineOf(io2, commandLineOf(origin, WHOAMI_SUBCOMMAND, origin !== DEFAULT_COMMAND_ORIGIN ? { origin } : {}), origin);
@@ -1225,9 +1235,9 @@ async function completeAct(io2, origin, kind, code, userAgent, say, deliver = ()
     const answer = planeObjectOf(answered.text);
     if (answer !== null && typeof answer.value === "string") io2.hide(answer.value, REDACTED_TOKEN);
     if (answered.status < 200 || answered.status > 299) {
-      const refusal = planeRefusalOf(answered.text);
+      const refusal = markedRefusalOf(answered.status, answered.text);
       if (refusal === null) {
-        say(`The exchange was answered HTTP ${answered.status}, not by the platform.`);
+        say(notThePlatformLine(EXCHANGE_ACT, answered.status));
         say(unknown);
         return COMMAND_STATUS.unknown;
       }
@@ -1573,6 +1583,79 @@ function strFromU8(dat, latin1) {
   }
 }
 
+// src/session_free_paths.ts
+var SESSION_FREE_SIGN_IN_PREFIX = "/__account/";
+var SESSION_FREE_ROUTER_PREFIX = "/__router/";
+
+// src/client_files.ts
+var MiB = 1024 * 1024;
+var CLIENT_FOLDER = "client/";
+var CLIENT_FILES_MAX = 2e3;
+var CLIENT_FILE_MAX_BYTES = 25 * MiB;
+var CLIENT_FILES_TOTAL_MAX_BYTES = 50 * MiB;
+var CLIENT_NAME_MAX_CHARS = 512;
+var CLIENT_NAME_MAX_SEGMENTS = 32;
+var PRUNE_FILE_DELETE_BUDGET_MS = 20 * 6e4;
+var INDEX_CACHE_BYTES = 32 * MiB;
+var CONTENT_CACHE_BYTES = 128 * MiB;
+var CONTENT_CACHE_FILE_MAX_BYTES = 1 * MiB;
+var SHELL_FILES = Object.freeze([
+  { name: "index.html", paths: ["/", "/index.html"] },
+  { name: "app.js", paths: ["/app.js"] },
+  { name: "styles.css", paths: ["/styles.css"] }
+]);
+var SHELL_NAMES = new Set(SHELL_FILES.map((file) => file.name));
+var SHELL_PATHS = new Set(SHELL_FILES.flatMap((file) => file.paths));
+var CLIENT_CONTENT_TYPES = Object.freeze({
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".wasm": "application/wasm",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  ".webmanifest": "application/manifest+json",
+  ".pdf": "application/pdf",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".oga": "audio/ogg",
+  ".wav": "audio/wav",
+  ".m4a": "audio/mp4",
+  ".flac": "audio/flac",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogv": "video/ogg"
+});
+var RESERVED_TOP_FOLDERS = Object.freeze([SESSION_FREE_SIGN_IN_PREFIX, SESSION_FREE_ROUTER_PREFIX].map((prefix) => prefix.replace(/^\/|\/$/g, "").toLowerCase()));
+var ADMITTED_SEGMENT = /^[A-Za-z0-9\-_.~]+$/;
+function admittedClientName(path) {
+  if (!isClientPath(path)) return null;
+  const name = path.slice(CLIENT_FOLDER.length);
+  if (name.length > CLIENT_NAME_MAX_CHARS) return null;
+  const segments = name.split("/");
+  if (segments.length > CLIENT_NAME_MAX_SEGMENTS) return null;
+  for (const segment of segments) {
+    if (!ADMITTED_SEGMENT.test(segment) || segment.startsWith(".") || segment.endsWith(".")) return null;
+  }
+  if (RESERVED_TOP_FOLDERS.includes(segments[0].toLowerCase())) return null;
+  return name;
+}
+var isClientPath = (path) => path.startsWith(CLIENT_FOLDER) && path.length > CLIENT_FOLDER.length;
+
 // src/turnzero_cloud_command/export_download.ts
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, relative as relative2, resolve as resolve2 } from "node:path";
 
@@ -2218,7 +2301,7 @@ var readHealthPath = (path, entries) => {
   return answer("absent");
 };
 var shownHealthPath = (path) => shownNoteName(bareHealthPath(path));
-var healthLineOf = (path) => `${WARNING_LINE_HEAD}${MANIFEST_FILE} names the health path ${shownHealthPath(path)}, and no other file of the zip holds its last segment, package files and documentation set aside. A deploy waits for that path to answer 200, so check that the application serves it. A route built in another form is not seen here.`;
+var healthLineOf = (path) => `${WARNING_LINE_HEAD}${MANIFEST_FILE} names the health path ${shownHealthPath(path)}, and no other file of the zip holds its last segment, package files and documentation set aside. A deploy waits for that path to answer 200 three times in a row, so check that the application serves it. A route built in another form is not seen here.`;
 var CREDENTIAL_FILE_NAMES = Object.freeze(["id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", ".netrc", ".pgpass", ".htpasswd", "credentials.json"]);
 var CLIENT_SECRET_OPENING = "client_secret";
 var CLIENT_SECRET_ENDING = ".json";
@@ -2292,11 +2375,14 @@ var DeployRefusal = class extends Error {
    *  row's outcome, a failed gate's `gate`, its evidence (PLD-L0-59;
    *  PLD-L0-63); onto the wire, an `upload_hash_mismatch`'s
    *  `received_sha256` and `expected_sha256` (deploy_upload.ts's readUpload;
-   *  PLD-L0-86), which the upload form's read throws before any row; empty
-   *  for every other refusal. Never `error` or `detail` themselves — failRun
-   *  keeps those two first. The wire mapping (main.ts's actRefusal) reads
-   *  status, code, and detail, and the two hashes for that one refusal
-   *  alone; a refusal thrown after the 202 reaches the row, not the wire. */
+   *  PLD-L0-86), which the upload form's read throws before any row, and a
+   *  `deploy_files_too_large`'s `limit`, the cap it met (deploy_files.ts's
+   *  tooLarge; #4418; MAPI-26); empty for every other refusal. Never
+   *  `error` or `detail` themselves — failRun keeps those two first. The
+   *  wire mapping (main.ts's actRefusal) reads status, code, and detail, the
+   *  two hashes for `upload_hash_mismatch` alone, and `limit` for
+   *  `deploy_files_too_large` alone; a refusal thrown after the 202 reaches
+   *  the row, not the wire. */
   members;
   /** The fields the control plane's `version failed` line carries beside
    *  the refusal for the operator alone (MAPI-10), never the row's or the
@@ -2584,7 +2670,7 @@ var isRecord = (value) => typeof value === "object" && value !== null && !Array.
 var ROOT_FILE_MAX_BYTES = 1024 * 1024;
 var MEMBER_FILE_MAX_BYTES = 64 * 1024;
 var MEMBER_FILES_READ_MAX = 50;
-var WINDOWS_ZIP_COMMAND = "tar.exe -a -c -f app.zip --exclude node_modules --exclude .env --exclude '.env.*' --exclude .git -C app .";
+var WINDOWS_ZIP_COMMAND = "tar.exe -a -c -f app.zip --exclude node_modules --exclude .env --exclude '.env.*' --exclude .git --exclude .claude --exclude .mcp.json --exclude .codex --exclude .cursor --exclude .gemini --exclude .continue --exclude .roo --exclude .kiro --exclude .amazonq --exclude .aider.conf.yml -C app .";
 function readArtifact(bytes) {
   const stored = [];
   const names = [];
@@ -2766,11 +2852,48 @@ function manifestCopyDepthRefusal(reading) {
     throw new DeployRefusal(400, "artifact_layout_invalid", `The zip's manifest.json nests deeper than the ${MANIFEST_COPY_DEPTH_MAX} levels the deploy reads: the platform reads the manifest submit_manifest recorded, so flatten the zip's copy or leave it out, and deploy again (PLD-L0-63).`);
   }
 }
+function clientReadingOf(records) {
+  const admitted = /* @__PURE__ */ new Map();
+  const skipped = [];
+  const skippedSeen = /* @__PURE__ */ new Set();
+  for (const record of records) {
+    const { path, folder } = entryNameOf(record.name);
+    if (folder || !isClientPath(path)) continue;
+    const name = admittedClientName(path);
+    if (name !== null) admitted.set(name, record);
+    else if (!skippedSeen.has(path)) {
+      skippedSeen.add(path);
+      skipped.push(path);
+    }
+  }
+  return { admitted, skipped };
+}
+function clientBoundRefusal(reading) {
+  const cite = " (SVC-L0-26).";
+  if (reading.admitted.size > CLIENT_FILES_MAX) {
+    return `The zip's client/ folder holds ${reading.admitted.size} files the publish admits, more than the ${CLIENT_FILES_MAX} files one version publishes: ship fewer client files, and deploy again${cite}`;
+  }
+  let total = 0;
+  for (const [name, record] of reading.admitted) {
+    const declared = declaredBytesOf(record);
+    if (declared > CLIENT_FILE_MAX_BYTES) {
+      return `The zip's client file ${shownEntry(`${CLIENT_FOLDER}${name}`)} declares ${declared} bytes, more than the 25 MiB (${CLIENT_FILE_MAX_BYTES} bytes) one client file holds: keep long media in a storage area, and deploy again${cite}`;
+    }
+    total += declared;
+  }
+  if (total > CLIENT_FILES_TOTAL_MAX_BYTES) {
+    return `The zip's client files declare ${total} bytes in all, more than the 50 MiB (${CLIENT_FILES_TOTAL_MAX_BYTES} bytes) one version's client files hold: keep large media in a storage area, and deploy again${cite}`;
+  }
+  return null;
+}
 function checkArtifact(bytes) {
   const reading = readArtifact(bytes);
   const packageJson = artifactLayoutOf(reading);
   manifestCopyDepthRefusal(reading);
-  return { reading, packageJson };
+  const client = clientReadingOf(reading.records);
+  const bounded = clientBoundRefusal(client);
+  if (bounded !== null) throw new DeployRefusal(400, "artifact_layout_invalid", bounded);
+  return { reading, packageJson, client };
 }
 function healthPathReadingOf(bytes, reading, recorded) {
   const path = isRecord(recorded) && typeof recorded.health === "string" ? recorded.health : null;
@@ -3292,7 +3415,7 @@ async function prepareDeploy(io2, options, zipSha256Value, bearer, userAgent, re
     return nothingStarted;
   }
   if (answered.status < 200 || answered.status > 299) {
-    const refusal = planeRefusalOf(answered.text);
+    const refusal = markedRefusalOf(answered.status, answered.text);
     if (refusal === null) {
       io2.print(prepareNotThePlatform(answered.status));
       io2.print(PREPARE_AGAIN);
@@ -3496,7 +3619,7 @@ async function deploy(named, io2, flags = /* @__PURE__ */ new Set()) {
     return PROGRESS_EXIT_STATUS.refused;
   }
   const answer = planeObjectOf(started.text);
-  if (answer === null) {
+  if (answer === null || (started.status < 200 || started.status > 299) && !platformMarked(started.text)) {
     io2.print(`The start was answered HTTP ${started.status}, not by the platform, so the deploy may have started.`);
     io2.print(stop);
     return PROGRESS_EXIT_STATUS.refused;
@@ -3543,8 +3666,8 @@ async function deploy(named, io2, flags = /* @__PURE__ */ new Set()) {
       return PROGRESS_EXIT_STATUS.refused;
     }
     if (read2.status !== 200 || !read2.type.startsWith("text/plain")) {
-      const refusal = planeRefusalOf(read2.text);
-      const said = refusal !== null ? refusalLines(PROGRESS_READ_ACT, read2.status, refusal) : [`The progress read was answered HTTP ${read2.status}, not by the platform.`];
+      const refusal = markedRefusalOf(read2.status, read2.text);
+      const said = refusal !== null ? refusalLines(PROGRESS_READ_ACT, read2.status, refusal) : [notThePlatformLine(PROGRESS_READ_ACT, read2.status)];
       for (const line of said) io2.print(line);
       io2.print(stop);
       return PROGRESS_EXIT_STATUS.refused;
@@ -3713,7 +3836,7 @@ async function callCheck(io2, options, bearer, userAgent, refused = () => null)
     return nothingChecked;
   }
   if (answered.status < 200 || answered.status > 299) {
-    const refusal = planeRefusalOf(answered.text);
+    const refusal = markedRefusalOf(answered.status, answered.text);
     if (refusal === null) {
       io2.print(checkNotThePlatform(answered.status));
       io2.print(CHECK_AGAIN);
@@ -3828,7 +3951,7 @@ var CHECK_ROW = Object.freeze({
   note: [
     `A check is one line, which carries no credential: run the line your tool's ${CHECK_ACTION} call answers, or ${CHECK_SUBCOMMAND} ${CHECK_OPTION.application} <application id>, from the application's folder, before a first deploy and after each fix. It reads its credential and the platform's address as ${DEPLOY_SUBCOMMAND} does, builds the zip ${DEPLOY_SUBCOMMAND} builds, and sends the platform the application alone, no byte of the zip and no hash. It uploads nothing and starts nothing.`,
     `After its zip line, ${CHECK_SUBCOMMAND} prints the further lines ${DEPLOY_SUBCOMMAND} prints, leaving out the health warning where the platform says the deploy would be a first one, since a refused: line then reads the recorded health path. Then it prints one refused: line for each refusal the platform answered for the application's state, then one for each refusal of the zip by the deploy's own checks, a line naming submit_manifest where the zip's manifest.json names another health path, and a last checked: line counting the refusals.`,
-    `A check is no admission: a later deploy reads every check again, since a deploy in flight, the day's deploys, and the hosting cell's room can change between the two.`
+    `A passing check does not guarantee the deploy is accepted: a deploy in flight, the day's deploys, and the hosting cell's room can change before the deploy, which makes every check again.`
   ],
   afterOwnError: CHECK_AFTER_OWN_ERROR,
   run: (call, io2) => check(call.named, io2)
@@ -4026,7 +4149,8 @@ var SECRET_CREDENTIAL = Object.freeze({
   aGrant: "a secret grant",
   call: "the store_secret or rotate_secret call",
   mintedToken: false,
-  computerToken: true
+  computerToken: true,
+  emptyPipeRefused: true
 });
 var freshLineSteps = (act) => `${SECRET_ACTION[act]} from your tool with the name and its scope, naming no value, and run the line it answers as given.`;
 var secretAgain = (act) => `Call ${freshLineSteps(act)}`;
@@ -4176,7 +4300,7 @@ async function secret(call, io2) {
   }
   const answer = planeObjectOf(answered.text);
   if (answered.status < 200 || answered.status > 299) {
-    const refusal = planeRefusalOf(answered.text);
+    const refusal = markedRefusalOf(answered.status, answered.text);
     if (refusal === null) {
       io2.print(`${action} was answered HTTP ${answered.status}, not by the platform.`);
       io2.print(unknown);
@@ -4394,10 +4518,12 @@ var RUN_OPTIONS = Object.freeze([
   }
 ]);
 var NO_APPLICATION_STARTED = "No application was started.";
+var RUN_STEP_BACKGROUND = "The line runs until the application ends, so start it as a background process and read its lines";
 var PORT_FORM = /^[1-9][0-9]{0,4}$/;
 var isPortNumber = (value) => PORT_FORM.test(value) && Number(value) <= 65535;
 var RUN_BACKGROUND_SENTENCE = "The command runs until the application ends, so a tool starts it as a background process and reads its lines.";
-var startingLineOf = (folder) => `Starting npm start in ${folder}. ${RUN_BACKGROUND_SENTENCE}`;
+var stopSentenceOf = (processId, onWindows2 = NPM_NEEDS_SHELL) => `To stop it, send it an interrupt or run ${onWindows2 ? `taskkill /T /F /PID ${processId}` : `kill ${processId}`}, which ends the application with the command.`;
+var startingLineOf = (folder, processId, onWindows2 = NPM_NEEDS_SHELL) => `Starting npm start in ${folder}; the command's process id is ${processId}. ${RUN_BACKGROUND_SENTENCE} ${stopSentenceOf(processId, onWindows2)}`;
 var PORT_SOURCE_WORDS = Object.freeze({
   option: RUN_OPTION.port,
   file: "the environment file",
@@ -4557,7 +4683,7 @@ async function localRun(call, io2) {
   }
   const { env, overridden } = applicationEnvironmentOf(io2.env, read2.settings, options.port);
   for (const [text, shown2] of hiddenTextsOf(Object.entries(env))) io2.hide(text, shown2);
-  io2.print(startingLineOf(options.folder));
+  io2.print(startingLineOf(options.folder, io2.processId ?? process.pid, io2.windows ?? NPM_NEEDS_SHELL));
   if (file.text === null) io2.print(`No environment file stands at ${options.envFile}, so the application receives the shell's environment alone.`);
   else if (read2.settings.length === 0) io2.print(`${options.envFile} sets no setting.`);
   else io2.print(`${options.envFile} sets ${read2.settings.length} setting(s): ${read2.settings.map(([name]) => name).join(", ")}.`);
@@ -4796,7 +4922,7 @@ var readOf = async (io2, origin, userAgent, body, what) => {
   }
   const answer = planeObjectOf(text);
   if (status >= 200 && status <= 299 && answer !== null) return { answer };
-  const refusal = planeRefusalOf(text);
+  const refusal = markedRefusalOf(status, text);
   if (refusal === null) return { lines: [`${LIBRARY_READ_ACTION} was answered HTTP ${status}, not by the platform. ${NOTHING_WRITTEN2}`] };
   return { lines: [...refusalLines(LIBRARY_READ_ACTION, status, refusal), NOTHING_WRITTEN2] };
 };
@@ -5800,6 +5926,7 @@ var PROVISION_CREDENTIAL = Object.freeze({
   aGrant: "a secret grant",
   call: "the submit_manifest call naming local_run",
   mintedToken: true,
+  emptyPipeRefused: true,
   bare: `with nothing piped and neither token, it keeps a verifier and prints the challenge and the submit_manifest call naming local_run and ${CODE_CHALLENGE_MEMBER}, and a grant piped is presented with that verifier`
 });
 var NOTHING_REMINTED = "Nothing was re-minted, and the environment file is as it stood.";
@@ -5835,7 +5962,19 @@ var outsideApplicationFolder = (io2, envFile) => APPLICATION_FOLDER_MARKS.every(
     return false;
   }
 });
+var PROVISION_NEXT_HEAD = "next: ";
+var nextRunLineOf = (io2, origin, envFile) => machineLineOf(
+  commandLineOf(origin, RUN_SUBCOMMAND, {
+    ...origin !== DEFAULT_COMMAND_ORIGIN ? { origin } : {},
+    ...envFile !== void 0 ? { quoted: [[RUN_OPTION.envFile, envFile]] } : {}
+  }),
+  { windows: onWindows(io2), npx: ranThroughNpx(io2) },
+  origin
+);
+var provisionNextLineOf = (line) => `${PROVISION_NEXT_HEAD}start the application on this machine. ${RUN_STEP_BACKGROUND}: ${line}`;
 var charactersOf = (value) => `<${value.length} characters>`;
+var REMINT_FILE_INSTRUCTION = new RegExp(`: set [A-Z][A-Z0-9_]*${REMINT_FILE_INSTRUCTION_TAIL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+var writtenDetailOf = (detail, setting, envFile) => detail.replace(REMINT_FILE_INSTRUCTION, () => `, and this run wrote it into ${setting} in ${envFile}.`);
 var transportText = (error) => {
   const oneLine2 = (text) => text.replace(/\s+/g, " ").trim();
   const message = error instanceof Error ? error.message : String(error);
@@ -5899,7 +6038,7 @@ async function remint(io2, origin, credential, userAgent, application, name, ver
   }
   const answer = planeObjectOf(text);
   if (status < 200 || status > 299) {
-    const refusal = planeRefusalOf(text);
+    const refusal = markedRefusalOf(status, text);
     if (refusal === null) return { kind: "unknown", lines: [`${PROVISION_ACTION} was answered HTTP ${status}, not by the platform.`] };
     return { kind: "refused", error: refusal.error, action: answer?.action, lines: refusalLines(PROVISION_ACTION, status, refusal) };
   }
@@ -6003,7 +6142,7 @@ async function provision(call, io2) {
       io2.print(older);
       return COMMAND_STATUS.nothing_started;
     }
-    return await remintAndWrite(io2, sent, agent.userAgent, { ...read2, verifier, again }, standing.text, reminted);
+    return await remintAndWrite(io2, sent, agent.userAgent, { ...read2, verifier, again, next: nextRunLineOf(io2, sent.origin, namedEnvFile) }, standing.text, reminted);
   } finally {
     release();
     dropWritingFile(io2, options.envFile);
@@ -6113,22 +6252,24 @@ async function remintAndWrite(io2, { application, envFile, origin }, userAgent,
   if (facts !== null && url !== null) {
     io2.print(`${envFile}: ${facts.setting}=${charactersOf(url)}, ${limit !== null ? `${LOCAL_RUN_SETTING.databaseConnectionLimit}=${limit}, ` : ""}${plain}`);
     io2.print(`development database: ${oneLine(facts.roleName)} on ${facts.host}, database ${oneLine(facts.dbName)}${limit === null ? "" : `, a client pool of at most ${limit} ${limit === 1 ? "connection" : "connections"} per process`}`);
-    if (database.kind === "answered" && typeof database.answer.detail === "string") io2.print(oneLine(database.answer.detail));
+    if (database.kind === "answered" && typeof database.answer.detail === "string") io2.print(oneLine(writtenDetailOf(database.answer.detail, facts.setting, envFile)));
   } else {
     io2.print(`${envFile}: ${plain}`);
     io2.print(
       `no development database stands for ${application}: ${LOCAL_RUN_SETTING.databaseConnection} and ${LOCAL_RUN_SETTING.databaseConnectionLimit} were not written; submit_manifest with the database kind provisions one.`
     );
   }
-  if (typeof platform.answer.detail === "string") io2.print(oneLine(platform.answer.detail));
+  if (typeof platform.answer.detail === "string") io2.print(oneLine(writtenDetailOf(platform.answer.detail, LOCAL_RUN_SETTING.platformCredential, envFile)));
   if (outsideApplicationFolder(io2, envFile)) io2.print(outsideApplicationWarningOf(dirname5(envFile)));
   if (facts !== null && limitCarried !== null) {
     const cause = limitMember ? "the plan's database-connection-limit holds no usable quantity, which platform staff set with set_plan_quota" : "the platform that answered serves no such member yet";
     io2.print(
       `${envFile} holds ${facts.setting} and the platform settings this run re-minted, and no ${LOCAL_RUN_SETTING.databaseConnectionLimit}: ${PROVISION_ACTION}'s development_database answer carried ${limitCarried}, where the pool's maximum is a positive integer, so ${cause}. Until that changes the application's pool holds one connection; once it has, ${againSteps(read2.kind, read2.again)}.`
     );
+    io2.print(provisionNextLineOf(read2.next));
     return COMMAND_STATUS.failed;
   }
+  io2.print(provisionNextLineOf(read2.next));
   return COMMAND_STATUS.done;
 }
 var PROVISION_ROW = Object.freeze({
@@ -6151,7 +6292,7 @@ var PROVISION_ROW = Object.freeze({
   },
   note: [
     `Run ${PROVISION_BARE_LINE_WORDS} from the folder the application runs in. With nothing piped and no token for the address, it prints a challenge and the submit_manifest call naming local_run and ${CODE_CHALLENGE_MEMBER}; your tool makes that call and runs the line it answers once, as given, before its grant expires, which presents the grant with this computer's verifier. On a computer logged in, the bare line re-mints at once.`,
-    `Each run revokes the development credentials the application had before it. A deployed development environment holds the revoked values until it restarts, so call restart_application on development afterwards. Its redeploy takes both re-minted credentials from custody, the connection string and the platform credential, and spends no deploy of the day. ${PROVISION_SUBCOMMAND} writes no ${PORT_SETTING}: ${RUN_SUBCOMMAND} sets it from ${RUN_OPTION.port}.`
+    `Each run revokes the development credentials the application had before it. A deployed development environment holds the revoked values until it restarts, so the line's last re-mint restarts it where development serves a version. Its redeploy takes both re-minted credentials from custody, the connection string and the platform credential, and does not count toward the day's deploys. Where a deploy of development is still in flight, the re-mint's answer names restart_application on development, and your tool calls it once that deploy ends. ${PROVISION_SUBCOMMAND} writes no ${PORT_SETTING}: ${RUN_SUBCOMMAND} sets it from ${RUN_OPTION.port}.`
   ],
   afterOwnError: provisionAfterOwnError,
   run: provision
@@ -6178,7 +6319,7 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "",
       "Turn Zero Cloud serves its rules to a coding tool through its MCP server, `turnzero-cloud`, and they change with the platform, so none is repeated here.",
       "",
-      `- Where the server is not connected, connect it first. The platform's page "Connect your tool" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect Claude Code or Codex" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill.",
       "",
       "## What you run here",
@@ -6341,9 +6482,9 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "      }",
       "      send(404, { error: 'not_found' });",
       "    } catch (error) {",
-      "      const refused = error instanceof SyntaxError || error?.code === '23514';",
-      "      if (!refused) console.error(error);",
-      "      send(refused ? 400 : 500, { error: refused ? 'invalid_note' : 'internal' });",
+      "      const refused = error instanceof SyntaxError ? 'invalid_json' : error?.code === '23514' ? 'invalid_note' : null;",
+      "      if (refused === null) console.error(error);",
+      "      send(refused === null ? 500 : 400, { error: refused ?? 'internal' });",
       "    }",
       "  });",
       "}",
@@ -6423,6 +6564,17 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "  assert.deepEqual(await response.json(), { error: 'invalid_note' });",
       "  assert.deepEqual(await (await fetch(`${base}/notes`)).json(), []);",
       "});",
+      "",
+      "test('POST /notes answers 400 invalid_json for a body that is not JSON, and GET /notes returns no row', async () => {",
+      "  const response = await fetch(`${base}/notes`, {",
+      "    method: 'POST',",
+      "    headers: { 'content-type': 'application/json' },",
+      "    body: '{',",
+      "  });",
+      "  assert.equal(response.status, 400);",
+      "  assert.deepEqual(await response.json(), { error: 'invalid_json' });",
+      "  assert.deepEqual(await (await fetch(`${base}/notes`)).json(), []);",
+      "});",
       ""
     ].join("\n")]
   ]),
@@ -6444,7 +6596,7 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "",
       "Turn Zero Cloud serves its rules to a coding tool through its MCP server, `turnzero-cloud`, and they change with the platform, so none is repeated here.",
       "",
-      `- Where the server is not connected, connect it first. The platform's page "Connect your tool" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect Claude Code or Codex" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill.",
       "",
       "## What you run here",
@@ -6563,7 +6715,7 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "",
       "Turn Zero Cloud serves its rules to a coding tool through its MCP server, `turnzero-cloud`, and they change with the platform, so none is repeated here.",
       "",
-      `- Where the server is not connected, connect it first. The platform's page "Connect your tool" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect Claude Code or Codex" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill, and before you change its schedule, the server's `schedule` skill.",
       "",
       "## What you run here",
@@ -6769,7 +6921,7 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "",
       "Turn Zero Cloud serves its rules to a coding tool through its MCP server, `turnzero-cloud`, and they change with the platform, so none is repeated here.",
       "",
-      `- Where the server is not connected, connect it first. The platform's page "Connect your tool" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect Claude Code or Codex" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill, and before you change its sign-in or its AI call, the server's `add-sign-in` or `use-ai-allowance` skill.",
       "",
       "## What you run here",
@@ -7235,9 +7387,9 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "      }",
       "      send(404, { error: 'not_found' });",
       "    } catch (error) {",
-      "      const refused = error instanceof SyntaxError || error?.code === '23514';",
-      "      if (!refused) console.error(error);",
-      "      send(refused ? 400 : 500, { error: refused ? 'invalid_note' : 'internal' });",
+      "      const refused = error instanceof SyntaxError ? 'invalid_json' : error?.code === '23514' ? 'invalid_note' : null;",
+      "      if (refused === null) console.error(error);",
+      "      send(refused === null ? 500 : 400, { error: refused ?? 'internal' });",
       "    }",
       "  });",
       "}",
@@ -7406,6 +7558,17 @@ var SCAFFOLD_TEMPLATE_FILES = Object.freeze({
       "  assert.deepEqual(await (await fetch(`${base}/api/notes`, { headers: signedIn(sam) })).json(), []);",
       "});",
       "",
+      "test('POST /api/notes answers 400 invalid_json for a body that is not JSON, and GET /api/notes returns no row', async () => {",
+      "  const response = await fetch(`${base}/api/notes`, {",
+      "    method: 'POST',",
+      "    headers: { 'content-type': 'application/json', ...signedIn(sam) },",
+      "    body: '{',",
+      "  });",
+      "  assert.equal(response.status, 400);",
+      "  assert.deepEqual(await response.json(), { error: 'invalid_json' });",
+      "  assert.deepEqual(await (await fetch(`${base}/api/notes`, { headers: signedIn(sam) })).json(), []);",
+      "});",
+      "",
       "test('POST /api/ask answers under the AI allowance, and answers 503 naming why the model gave no answer: the allowance drawn, no key in place, or the provider out of capacity', async () => {",
       "  ai.prime({ text: 'Lunch is at noon.', usage: { input: 40, output: 12 } });",
       "  const ask = (question) =>",
@@ -7446,7 +7609,6 @@ var WEB_OPEN_STEP = "Open the address the deploy answers in a browser and sign i
 var SUBMIT_NO_SETTING_STEP = `Call submit_manifest from your tool with the application and its manifest, ${APPLICATION_FOLDER}/${APPLICATION_MANIFEST}, naming no local_run, since the service reads no setting.`;
 var provisionStepLineOf = (origin, windows) => machineLineOf(provisionBareLineOf({ origin, application: "<application id>" }), windows, origin);
 var provisionStepOf = (origin, windows) => `Call submit_manifest from your tool with the application and its manifest, ${APPLICATION_FOLDER}/${APPLICATION_MANIFEST}, naming no local_run. Then run ${freshLineSteps2("the provision line below")}, all in ${APPLICATION_FOLDER}/. The provision line: ${provisionStepLineOf(origin, windows)}`;
-var RUN_STEP_BACKGROUND = "The line runs until the application ends, so start it as a background process and read its lines";
 var SCHEDULED_JOB_SCHEDULE = "heartbeat";
 var ENTRY_PAGES = Object.freeze({
   database: Object.freeze({ follow: "the guide Add a database", page: "/cloud/guides/add-a-database/" }),
@@ -8080,16 +8242,20 @@ var standsAt = (io2, folder, name) => {
 var noFolderSentence = (name, where) => `Something that is no folder stands at ${name} in the project's root, where ${where}: move it, then run the line again. ${NOTHING_WRITTEN2}`;
 var scaffoldLinkSentence = (what) => `${what} stands on a link that leads outside the project's root, and the scaffold never writes through one. Put a folder in the link's place, or remove it, then run the line again. ${NOTHING_WRITTEN2}`;
 var listOf = (value) => value === null ? [] : Array.isArray(value) ? value : [value];
+var BRING_PAGE = "/cloud/guides/bring-an-existing-application/";
+var BRING_FOLLOW = "the guide Bring an existing application";
+var STANDS_DEPLOY_LINE = `Where ${APPLICATION_FOLDER}/ holds an application, deploy it: call deploy from your tool and run the line it answers in ${APPLICATION_FOLDER}/, as ${BRING_FOLLOW}, read_documentation's page ${BRING_PAGE}, says.`;
 var applicationStandsLines = (template, takeLines) => {
   const { takes } = TEMPLATE_FACTS[template];
   const lines = listOf(takeLines);
   const first = `The project's root holds ${APPLICATION_FOLDER}/ with files in it, so an application stands there, and ${SCAFFOLD_SUBCOMMAND} starts a new application and writes over none. ${NOTHING_WRITTEN2}`;
-  if (takes.length === 0 || lines.length !== takes.length) return [first];
+  if (takes.length === 0 || lines.length !== takes.length) return [first, STANDS_DEPLOY_LINE];
   return [
     first,
     ...takes.map(
       (take, index) => `To add the ${take.entry} package to the application that stands, run this line at the project's root, then follow ${take.follow}, read_documentation's page ${take.page}: ${lines[index]}`
-    )
+    ),
+    STANDS_DEPLOY_LINE
   ];
 };
 var STAGE_NOT_OWN = `Something that is not this run's own stands at ${STAGE_FOLDER} in the project's root, the name the scaffold writes under, an earlier run's files under another template or another resource name among it: move or remove ${STAGE_FOLDER}, then run the line again. ${NOTHING_WRITTEN2}`;
@@ -8170,8 +8336,9 @@ var applicationStateOf = (io2, app) => {
   }
 };
 var standsWayOn = (template, takeLines) => {
-  const lines = applicationStandsLines(template, takeLines);
-  return lines.length > 1 ? `. ${lines.slice(1).join("\n")}` : `: ${SCAFFOLD_SUBCOMMAND} starts a new application and writes over none.`;
+  const takes = applicationStandsLines(template, takeLines).slice(1, -1);
+  return `${takes.length > 0 ? `. ${takes.join("\n")}` : `: ${SCAFFOLD_SUBCOMMAND} starts a new application and writes over none.`}
+${STANDS_DEPLOY_LINE}`;
 };
 var stoppedCloseOf = (state, template, takeLines) => {
   const before = `before ${APPLICATION_FOLDER}/ was written`;
@@ -8836,44 +9003,79 @@ var usageLineOf = (subcommand) => {
   return `${pipedHead(subcommand)}${SERVED} ${[namedWithActs(subcommand), ...required, ...optional].join(" ")}`;
 };
 var usageHeadOf = (version) => `${TURNZERO_CLOUD_PACKAGE} ${version}: the Turn Zero Cloud command, installed from the public npm registry by your platform's tag, latest on production and next on development.`;
-var usageText = (version = commandVersion()) => {
-  const lines = [usageHeadOf(version), "", "Usage:"];
-  for (const subcommand of SUBCOMMANDS) lines.push(`  ${usageLineOf(subcommand)}`);
-  lines.push(`  ${SERVED} --version`, `  ${SERVED} --help`, "", WINDOWS_SENTENCE, "", NPX_FORM_SENTENCE, "", QUOTED_PATH_SENTENCE, "");
-  for (const subcommand of SUBCOMMANDS) {
-    lines.push(`${namedWithActs(subcommand)}: ${subcommand.summary}`, "", "Options:");
-    for (const option of subcommand.options) lines.push(`  ${shown(option)}${option.required ? " (required)" : ""}`, `      ${option.description}`);
-    lines.push("");
-  }
-  const reading = SUBCOMMANDS.filter((subcommand) => subcommand.credential !== null);
-  const unread = SUBCOMMANDS.filter((subcommand) => subcommand.credential === null && subcommand.reads === void 0).map((subcommand) => subcommand.name);
-  const unattended = reading.filter((subcommand) => subcommand.credential.mintedToken).map((subcommand) => subcommand.name);
-  const computerOnly = reading.filter((subcommand) => subcommand.credential.computerToken === true).map((subcommand) => subcommand.name);
-  lines.push("Input:");
-  for (const subcommand of reading) {
-    const credential = subcommand.credential;
-    if (credential.piped === false) continue;
-    lines.push(
-      `  ${subcommand.name} reads ${credential.aGrant} from standard input, as the line ${credential.call} answers pipes it in${credential.mintedToken ? `; and otherwise a minted token from ${MINTED_TOKEN_VARIABLE} where it is set, or this computer's token from its credential file` : credential.computerToken === true ? `; and otherwise this computer's token from its credential file, never a minted token from ${MINTED_TOKEN_VARIABLE}, whose being set refuses the run` : ""}${credential.bare !== void 0 ? `; ${credential.bare}` : ""}.`
-    );
-  }
-  for (const subcommand of SUBCOMMANDS) if (subcommand.reads !== void 0) lines.push(`  ${subcommand.name} reads ${subcommand.reads}.`);
-  lines.push(`  The command takes no credential in its arguments, and ${listed(unread)} ${unread.length === 1 ? "reads" : "read"} none.`, "", "Environment variables:");
-  for (const subcommand of SUBCOMMANDS) for (const [name, does] of subcommand.variables ?? []) lines.push(`  ${name}  under ${subcommand.name}, ${does}`);
-  if (unattended.length > 0) {
-    lines.push(
-      `  ${MINTED_TOKEN_VARIABLE}  under ${listed(unattended)}, a minted token for a tool connected by a minted token or an unattended run, set for the one line from where the tool keeps it or from your CI's secret store. Where it is set, it wins over this computer's credential file.`,
-      `  ${ORIGIN_VARIABLE}  under ${listed(unattended)}, in an unattended run, the platform's address the minted token is sent to where the line names no ${DEPLOY_OPTION.origin}. Under the token, a ${DEPLOY_OPTION.origin} the line names must be that address, or ${DEFAULT_COMMAND_ORIGIN} where this variable is unset. Where ${MINTED_TOKEN_VARIABLE} is not set and the line names no ${DEPLOY_OPTION.origin}, this variable names the address whose token the command reads from this computer's credential file${computerOnly.length > 0 ? `, under ${listed(computerOnly)} too where no grant is piped` : ""}. A run under a grant does not read it.`
-    );
-  }
-  lines.push(`  ${USER_AGENT_VARIABLE}  text appended to the command's user agent on each request.`, "", "Statuses:");
+var unreadNames = () => SUBCOMMANDS.filter((subcommand) => subcommand.credential === null && subcommand.reads === void 0).map((subcommand) => subcommand.name);
+var unattendedNames = () => SUBCOMMANDS.filter((subcommand) => subcommand.credential?.mintedToken === true).map((subcommand) => subcommand.name);
+var computerOnlyNames = () => SUBCOMMANDS.filter((subcommand) => subcommand.credential?.computerToken === true).map((subcommand) => subcommand.name);
+var sectionLinesOf = (subcommand) => [
+  `${namedWithActs(subcommand)}: ${subcommand.summary}`,
+  "",
+  "Options:",
+  ...subcommand.options.flatMap((option) => [`  ${shown(option)}${option.required ? " (required)" : ""}`, `      ${option.description}`]),
+  ""
+];
+var pipedLinesOf = (subcommand) => {
+  const credential = subcommand.credential;
+  if (credential === null || credential.piped === false) return [];
+  return [
+    `  ${subcommand.name} reads ${credential.aGrant} from standard input, as the line ${credential.call} answers pipes it in${credential.mintedToken ? `; and otherwise a minted token from ${MINTED_TOKEN_VARIABLE} where it is set, or this computer's token from its credential file` : credential.computerToken === true ? `; and otherwise this computer's token from its credential file, never a minted token from ${MINTED_TOKEN_VARIABLE}, whose being set refuses the run` : ""}${credential.bare !== void 0 ? `; ${credential.bare}` : ""}.`
+  ];
+};
+var readsLinesOf = (subcommand) => subcommand.reads !== void 0 ? [`  ${subcommand.name} reads ${subcommand.reads}.`] : [];
+var noCredentialLine = () => {
+  const unread = unreadNames();
+  return `  The command takes no credential in its arguments, and ${listed(unread)} ${unread.length === 1 ? "reads" : "read"} none.`;
+};
+var mintedTokenVariableLine = () => `  ${MINTED_TOKEN_VARIABLE}  under ${listed(unattendedNames())}, a minted token for a tool connected by a minted token or an unattended run, set for the one line from where the tool keeps it or from your CI's secret store. Where it is set, it wins over this computer's credential file.`;
+var originVariableLine = () => {
+  const computerOnly = computerOnlyNames();
+  return `  ${ORIGIN_VARIABLE}  under ${listed(unattendedNames())}, in an unattended run, the platform's address the minted token is sent to where the line names no ${DEPLOY_OPTION.origin}. Under the token, a ${DEPLOY_OPTION.origin} the line names must be that address, or ${DEFAULT_COMMAND_ORIGIN} where this variable is unset. Where ${MINTED_TOKEN_VARIABLE} is not set and the line names no ${DEPLOY_OPTION.origin}, this variable names the address whose token the command reads from this computer's credential file${computerOnly.length > 0 ? `, under ${listed(computerOnly)} too where no grant is piped` : ""}. A run under a grant does not read it.`;
+};
+var USER_AGENT_LINE = `  ${USER_AGENT_VARIABLE}  text appended to the command's user agent on each request.`;
+var ownVariableLinesOf = (subcommand) => (subcommand.variables ?? []).map(([name, does]) => `  ${name}  under ${subcommand.name}, ${does}`);
+var statusLineOf = (status, meaning, clauses, also) => `  ${COMMAND_STATUS[status]}  ${meaning}${clauses.length > 0 ? `: ${clauses.join("; ")}` : ""}.${also !== void 0 ? ` ${also}` : ""}`;
+var noteLinesOf2 = (subcommand) => (subcommand.note ?? []).flatMap((paragraph) => ["", paragraph]);
+var usageBlockOf = (subcommandHelp) => [
+  "Usage:",
+  ...SUBCOMMANDS.map((subcommand) => `  ${usageLineOf(subcommand)}`),
+  `  ${SERVED} --version`,
+  `  ${SERVED} --help`,
+  ...subcommandHelp ? [`  ${SERVED} <subcommand> --help`] : []
+];
+var sharedSentenceLines = () => [WINDOWS_SENTENCE, "", NPX_FORM_SENTENCE, "", QUOTED_PATH_SENTENCE];
+var SUBCOMMAND_HELP_SENTENCE = `Run ${SERVED} <subcommand> --help for that subcommand's options, credential, variables, statuses, and notes.`;
+var SHARED_HELP_SENTENCE = `Run ${SERVED} --help for every subcommand and the sentences they share: a line's Windows form, its npx form, and a path between double quotes.`;
+var shortUsageText = (version = commandVersion()) => [
+  usageHeadOf(version),
+  "",
+  ...usageBlockOf(true),
+  "",
+  ...sharedSentenceLines(),
+  "",
+  "Statuses:",
+  ...STATUS_MEANINGS.map(([status, meaning, also]) => statusLineOf(status, meaning, [], also)),
+  "",
+  "Subcommands:",
+  ...SUBCOMMANDS.map((subcommand) => `  ${namedWithActs(subcommand)}: ${subcommand.summary}`),
+  "",
+  SUBCOMMAND_HELP_SENTENCE
+].join("\n");
+var subcommandHelpOf = (subcommand, version = commandVersion()) => {
+  const lines = [usageHeadOf(version), "", "Usage:", `  ${usageLineOf(subcommand)}`, "", ...sectionLinesOf(subcommand)];
+  lines.push("Input:", ...pipedLinesOf(subcommand), ...readsLinesOf(subcommand), noCredentialLine(), "", "Environment variables:", ...ownVariableLinesOf(subcommand));
+  if (unattendedNames().includes(subcommand.name)) lines.push(mintedTokenVariableLine());
+  if (unattendedNames().length > 0 && (unattendedNames().includes(subcommand.name) || computerOnlyNames().includes(subcommand.name))) lines.push(originVariableLine());
+  lines.push(USER_AGENT_LINE, "", "Statuses:");
   for (const [status, meaning, also] of STATUS_MEANINGS) {
-    const clauses = SUBCOMMANDS.flatMap((subcommand) => subcommand.statuses[status] !== void 0 ? [`under ${subcommand.name}, ${subcommand.statuses[status]}`] : []);
-    lines.push(`  ${COMMAND_STATUS[status]}  ${meaning}${clauses.length > 0 ? `: ${clauses.join("; ")}` : ""}.${also !== void 0 ? ` ${also}` : ""}`);
+    const clause = subcommand.statuses[status];
+    if (clause !== void 0 || also !== void 0) lines.push(statusLineOf(status, meaning, clause !== void 0 ? [`under ${subcommand.name}, ${clause}`] : [], also));
   }
-  for (const subcommand of SUBCOMMANDS) for (const paragraph of subcommand.note ?? []) lines.push("", paragraph);
+  lines.push(...noteLinesOf2(subcommand), "", SHARED_HELP_SENTENCE);
   return lines.join("\n");
 };
+var subcommandHelpText = (name, version = commandVersion()) => {
+  const subcommand = SUBCOMMANDS.find((entry) => entry.name === name);
+  return subcommand === void 0 ? null : subcommandHelpOf(subcommand, version);
+};
 var grantArgumentSentence = () => "An argument holds a grant, and the command never takes a grant from its arguments: it reads the grant from standard input, as the line your tool's call answers pipes it in. Run the line the call answered as given. Nothing was sent and nothing was started.";
 var tokenArgumentSentence = () => `An argument holds a minted token, and the command never takes a credential from its arguments: it reads a minted token from ${MINTED_TOKEN_VARIABLE} alone, which a tool connected by a minted token, or an unattended run, sets for the one line from where the tool keeps the token or from your CI's secret store. Nothing was sent and nothing was started.`;
 var NOTHING_STARTED2 = "Nothing was started.";
@@ -8894,21 +9096,21 @@ var valuePlacesOf = (argv2) => {
   }
   return places;
 };
+var noSubcommandSentence = (first) => `${first === void 0 ? "No subcommand was named" : `The first argument is not a subcommand of ${TURNZERO_CLOUD_PACKAGE}`}: the subcommands are ${SUBCOMMANDS.map((entry) => entry.name).join(", ")}. ${NOTHING_STARTED2}`;
 var parseArguments = (argv2, onWindows2 = ON_WINDOWS) => {
   if (argv2.some((argument) => argument.includes(UPLOAD_GRANT_PREFIX))) return { kind: "refused", sentence: grantArgumentSentence() };
   if (argv2.some((argument) => argument.includes(MINTED_TOKEN_PREFIX))) return { kind: "refused", sentence: tokenArgumentSentence() };
   const values = valuePlacesOf(argv2);
   const standsAlone = (words) => argv2.some((argument, index) => words.includes(argument) && !values.has(index));
-  if (standsAlone(["--help", "-h"])) return { kind: "help" };
-  if (standsAlone(["--version"])) return { kind: "version" };
   const [first, ...afterName] = argv2;
   const subcommand = SUBCOMMANDS.find((entry) => entry.name === first);
-  if (subcommand === void 0) {
-    return {
-      kind: "refused",
-      sentence: `${first === void 0 ? "No subcommand was named" : `The first argument is not a subcommand of ${TURNZERO_CLOUD_PACKAGE}`}: the subcommands are ${SUBCOMMANDS.map((entry) => entry.name).join(", ")}. ${NOTHING_STARTED2}`
-    };
+  if (standsAlone(["--help", "-h"])) {
+    if (subcommand !== void 0) return { kind: "help", subcommand };
+    if (first.startsWith("-")) return { kind: "help" };
+    return { kind: "refused", sentence: noSubcommandSentence(first) };
   }
+  if (standsAlone(["--version"])) return { kind: "version" };
+  if (subcommand === void 0) return { kind: "refused", sentence: noSubcommandSentence(first) };
   let act = null;
   let rest = afterName;
   if (subcommand.acts !== void 0) {
@@ -8968,7 +9170,7 @@ async function runGuarded(argv2, io2) {
   }
   const parsed = parseArguments(argv2, io2.windows ?? ON_WINDOWS);
   if (parsed.kind === "help") {
-    io2.print(usageText(version));
+    io2.print((parsed.subcommand === void 0 ? null : subcommandHelpText(parsed.subcommand.name, version)) ?? shortUsageText(version));
     return COMMAND_STATUS.done;
   }
   if (parsed.kind === "version") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turnzero",
-  "version": "0.18.2-next.1",
+  "version": "0.18.3-next.1",
   "type": "module",
   "description": "The Turn Zero Cloud command, which an AI coding tool runs on your machine to deploy an application, store a secret, upload a file, download an export, take a library entry, write a local run's settings, start the application locally, and scaffold a new service from a template.",
   "license": "Apache-2.0",