turnzero 0.26.0 → 0.27.0

package/dist/turnzero-cloud.mjs

@@ -1354,7 +1354,7 @@ var AUTHORIZE_CREDENTIAL = Object.freeze({
   bare: `with nothing piped, it keeps a verifier and prints the challenge and the ${MINT_TOKEN_ACTION} call that authorize this computer`
 });
 var AUTHORIZATION_ORIGIN_VARIABLE_LINE = `the platform's address the authorization reaches where the line names no ${DEPLOY_OPTION.origin}, and the one address beside ${DEFAULT_COMMAND_ORIGIN} and ${DEVELOPMENT_COMMAND_ORIGIN} a ${DEPLOY_OPTION.origin} may name, an address of this machine only where it names it.`;
-var CREDENTIAL_FILE_WORDS = `${CREDENTIAL_FILE_NAME} in a folder ${CREDENTIAL_FOLDER_NAME} under ${CONFIG_HOME_VARIABLE}, or under .config in your home folder where that is unset, readable by you alone; on Windows in a folder ${WINDOWS_CREDENTIAL_FOLDER_NAME} under your profile folder, ${PROFILE_VARIABLE}, where a file under ${LOCAL_APP_DATA_VARIABLE} from an older version is moved once`;
+var CREDENTIAL_FILE_WORDS = `${CREDENTIAL_FILE_NAME} in a folder ${CREDENTIAL_FOLDER_NAME} under ${CONFIG_HOME_VARIABLE}, or under .config in your home folder where that is unset, readable by you alone. On Windows it is in a folder ${WINDOWS_CREDENTIAL_FOLDER_NAME} under your profile folder, ${PROFILE_VARIABLE}. A file under ${LOCAL_APP_DATA_VARIABLE} from an older version is moved there once`;
 var AUTHORIZE_AFTER_OWN_ERROR = "a token code the line carried may not have been presented, and it is live until it expires and mints nothing without this computer's verifier; where a token was minted, list_tokens from your tool shows it by its label, and revoke_token ends it";
 async function authorize(call, io2) {
   const origin = authorizationOriginOf(io2.env, call.named[DEPLOY_OPTION.origin], NOTHING_SENT);
@@ -1383,7 +1383,8 @@ async function authorize(call, io2) {
 }
 var AUTHORIZE_ROW = Object.freeze({
   name: AUTHORIZE_SUBCOMMAND,
-  summary: `Authorizes this computer at the platform's address in two acts around one ${MINT_TOKEN_ACTION} call your tool makes. Run with nothing piped, it keeps a verifier in this computer's credential file and prints the challenge and the call. Run with the token code the call's line pipes in, it presents the code with the verifier, keeps the token the platform mints in the credential file, and prints authorized:. It prints no token, code, or verifier.`,
+  summary: `Authorizes this computer at the platform's address, in two acts around one ${MINT_TOKEN_ACTION} call your tool makes. Run with nothing piped, it keeps a verifier in this computer's credential file, and prints the challenge and the call. Run with the token code the call's line pipes in, it presents the code with the verifier. It then keeps the token the platform mints in the credential file, and prints authorized:. It prints no token, code, or verifier.`,
+  example: AUTHORIZE_SUBCOMMAND,
   options: AUTHORIZE_OPTIONS,
   credential: AUTHORIZE_CREDENTIAL,
   statuses: {
@@ -2190,7 +2191,8 @@ var EXPORT_AFTER_OWN_ERROR = `the files written so far stand under the folder, a
 var EXPORT_DOWNLOAD_ROW = Object.freeze({
   name: EXPORT_SUBCOMMAND,
   acts: EXPORT_ACTS,
-  summary: `Downloads every file of a completed export, its manifest, each table's CSV, and each stored file, under the download grant the ${DOWNLOAD_GRANT_ACTION} call answered, checking each against the length its answer states and the version the manifest names.`,
+  summary: `Downloads every file of a completed export: its manifest, each table's CSV, and each stored file. It runs under the download grant the ${DOWNLOAD_GRANT_ACTION} call answered. It checks each file against the length that answer states and the version the manifest names.`,
+  example: `${EXPORT_SUBCOMMAND} ${EXPORT_ACTS[0]} ${EXPORT_OPTION.export} <application id>/<export id> ${EXPORT_OPTION.path} <folder>`,
   options: EXPORT_DOWNLOAD_OPTIONS,
   credential: EXPORT_DOWNLOAD_CREDENTIAL,
   statuses: {
@@ -3985,7 +3987,8 @@ async function deploy(named, io2, flags = /* @__PURE__ */ new Set()) {
 var DEPLOY_AFTER_OWN_ERROR = "the deploy may or may not have started: call read_status from your tool first, make the start-only retry a pending upload it answers carries, and run the line again only where it shows neither";
 var DEPLOY_ROW = Object.freeze({
   name: DEPLOY_SUBCOMMAND,
-  summary: "Zips the application folder (or takes a .zip file), makes the preparing deploy call under this computer's token or, for a tool connected by a minted token or a job with no tool, under a minted token, then uploads the zip under the upload grant that call answers, starts the deploy, and waits for it, printing each step and the outcome. With no credential, it sends nothing and prints the two routes to one: the minted token's variables first, then, where the address is admitted, the login route.",
+  summary: "Deploys the application folder, or a .zip file. It zips the folder, makes the preparing deploy call, uploads the zip under the upload grant that call answers, starts the deploy, and waits for it, printing each step and the outcome. It runs under this computer's token. A tool connected by a minted token, or a job with no tool, runs it under a minted token. With no credential, it sends nothing and prints the two routes to one: the minted token's variables first, then, where the address is admitted, the login route.",
+  example: `${DEPLOY_SUBCOMMAND} ${DEPLOY_OPTION.application} <application id> ${DEPLOY_OPTION.path} <folder>`,
   options: DEPLOY_OPTIONS,
   credential: DEPLOY_CREDENTIAL,
   reads: DEPLOY_READS,
@@ -4242,7 +4245,8 @@ async function check(named, io2) {
 var CHECK_AFTER_OWN_ERROR = "a check uploads nothing and starts nothing, so run the line again";
 var CHECK_ROW = Object.freeze({
   name: CHECK_SUBCOMMAND,
-  summary: `Checks a deploy before it is made, uploading nothing: zips the application folder as ${DEPLOY_SUBCOMMAND} does (or takes a .zip file), asks the platform under the credential ${DEPLOY_SUBCOMMAND} reads which checks of the application's state would refuse a deploy now, and runs the deploy's own checks of the zip on this computer. It prints one refused: line for each refusal and a last checked: line. With no credential, it sends nothing and prints the two routes to one, as ${DEPLOY_SUBCOMMAND} does.`,
+  summary: `Checks a deploy before it is made, and uploads nothing. It zips the application folder as ${DEPLOY_SUBCOMMAND} does, or takes a .zip file. It asks the platform which checks of the application's state would refuse a deploy now. It also runs the deploy's own checks of the zip on this computer. It prints one refused: line for each refusal, then a last checked: line. It reads the credential ${DEPLOY_SUBCOMMAND} reads. With no credential, it sends nothing and prints the two routes to one, as ${DEPLOY_SUBCOMMAND} does.`,
+  example: `${CHECK_SUBCOMMAND} ${CHECK_OPTION.application} <application id> ${CHECK_OPTION.path} <folder>`,
   options: CHECK_OPTIONS,
   credential: CHECK_CREDENTIAL,
   reads: CHECK_READS,
@@ -4298,7 +4302,8 @@ async function hash(named, io2, flags = /* @__PURE__ */ new Set()) {
 }
 var HASH_ROW = Object.freeze({
   name: HASH_SUBCOMMAND,
-  summary: `Prints ${HASH_LINE_HEAD}<hash> on the line after the version line: the SHA-256 of the zip deploy uploads from the same folder, or of a .zip file's bytes. It reads what a deploy from the folder would upload, and no deploy needs it first. A further line follows only where there is something to name: the paths the zip left out, or a warning. A warning names a .zip file or a local run's output at the folder's root, a file that looks like a key or a credential, a source file that writes inside the folder, or a health path of manifest.json that no file names, package files and documentation set aside. With ${HASH_OPTION.list}, one line follows for each file the zip holds. It reads no grant and sends nothing, so a ${HASH_OPTION.origin} the line carries is checked and set aside.`,
+  summary: `Prints the SHA-256 of the zip a deploy from the folder would upload, or of a .zip file's bytes. It prints ${HASH_LINE_HEAD}<hash> on the line after the version line, and no deploy needs it first. Further lines name the paths the zip left out, and any warnings. A warning flags a .zip file or a local run's output at the folder's root, or a file that looks like a key or a credential. It also flags a source file that writes inside the folder, and a manifest.json health path that no file names, not counting package files and documentation. With ${HASH_OPTION.list}, it prints one line for each file in the zip. It reads no grant and sends nothing, so a ${HASH_OPTION.origin} on the line is checked, then set aside.`,
+  example: `${HASH_SUBCOMMAND} ${HASH_OPTION.path} <folder> ${HASH_OPTION.list}`,
   options: HASH_OPTIONS,
   credential: null,
   statuses: { done: "the hash printed", nothing_started: "no hash was printed" },
@@ -4631,7 +4636,8 @@ async function secret(call, io2) {
 var SECRET_ROW = Object.freeze({
   name: SECRET_SUBCOMMAND,
   acts: SECRET_ACTS,
-  summary: "Stores a secret under a name, or rotates the value a name holds, under the secret grant the store_secret or rotate_secret call answered, or, with no grant piped, under this computer's token. It reads the value from a file, from an environment variable it names, or from a prompt at the terminal, sends it once to the platform, and never prints it.",
+  summary: "Stores a secret under a name, or rotates the value a name holds. It reads the value from a file, from an environment variable it names, or from a prompt at the terminal. It sends the value once to the platform, and never prints it. It runs under the secret grant the store_secret or rotate_secret call answered. With no grant piped, it runs under this computer's token.",
+  example: `${SECRET_SUBCOMMAND} ${SECRET_ACTS[0]} ${SECRET_OPTION.name} <name> ${SECRET_OPTION.application} <application id> ${SECRET_OPTION.environment} development ${SECRET_OPTION.valueFile} <file>`,
   options: SECRET_OPTIONS,
   credential: SECRET_CREDENTIAL,
   statuses: {
@@ -4779,7 +4785,8 @@ async function put(call, io2) {
 }
 var PUT_ROW = Object.freeze({
   name: PUT_SUBCOMMAND,
-  summary: "Uploads one file to a storage area of the application's under the upload grant the mint_upload_grant call answered, and prints the file as the area holds it.",
+  summary: "Uploads one file to one of the application's storage areas, and prints the file as the area holds it. It runs under the upload grant the mint_upload_grant call answered.",
+  example: `${PUT_SUBCOMMAND} ${PUT_OPTION.area} <area> ${PUT_OPTION.name} <name> ${PUT_OPTION.path} <file>`,
   options: PUT_OPTIONS,
   credential: PUT_CREDENTIAL,
   statuses: {
@@ -5019,7 +5026,8 @@ async function localRun(call, io2) {
 }
 var RUN_ROW = Object.freeze({
   name: RUN_SUBCOMMAND,
-  summary: `Starts the application on this machine as the platform starts it, with npm start, and hands it the shell's environment with every setting of the environment file laid over it, the file's line winning. It passes the application's output through, with the value of a credential setting, and a connection string that holds a password, replaced by the setting's name between angle brackets, and a value under ${RETIRED_PLATFORM_CREDENTIAL_SETTING}, the platform credential's earlier name, by <${LOCAL_RUN_SETTING.platformCredential}>. It reads no credential and sends nothing. ${RUN_BACKGROUND_SENTENCE}`,
+  summary: `Starts the application on this machine with npm start, as the platform starts it. The application gets the shell's environment, with each setting of the environment file laid over it, the file's line winning. It passes the application's output through. In it, the value of a credential setting, and a connection string that holds a password, are replaced by the setting's name between angle brackets. A value under ${RETIRED_PLATFORM_CREDENTIAL_SETTING}, the platform credential's earlier name, is replaced by <${LOCAL_RUN_SETTING.platformCredential}>. It reads no credential and sends nothing. ${RUN_BACKGROUND_SENTENCE}`,
+  example: `${RUN_SUBCOMMAND} ${RUN_OPTION.path} <folder>`,
   options: RUN_OPTIONS,
   credential: null,
   statuses: {
@@ -5668,7 +5676,8 @@ async function libraryTake(call, io2) {
 var LIBRARY_ROW = Object.freeze({
   name: LIBRARY_SUBCOMMAND,
   acts: LIBRARY_ACTS,
-  summary: "Takes a library entry into the project: reads its files from the library, checks each file's SHA-256 and the entry's closure hash, then writes its row in the library folder's manifest.json and replaces the entry's folder under that folder whole. For an entry with compiled modules it copies its package.json and lib/ into the application's folder, declares the copy where it is not declared, and runs npm install there. It reads under the credential check reads. With no credential, it sends nothing and prints the two routes to one, as check does.",
+  summary: "Takes a library entry into the project. It reads the entry's files from the library, and checks each file's SHA-256 and the entry's closure hash. It then writes the entry's row in the library folder's manifest.json, and replaces the entry's folder there whole. For an entry with compiled modules, it copies the entry's package.json and lib/ into the application's folder. It declares the copy where it is not declared, and runs npm install there. It reads the credential check reads. With no credential, it sends nothing and prints the two routes to one, as check does.",
+  example: `${LIBRARY_SUBCOMMAND} ${LIBRARY_ACTS[0]} ${LIBRARY_OPTION.entry} <name> ${LIBRARY_OPTION.path} <project root>`,
   options: LIBRARY_TAKE_OPTIONS,
   credential: LIBRARY_CREDENTIAL,
   reads: LIBRARY_READS,
@@ -5931,7 +5940,8 @@ var LOGIN_OPTIONS = Object.freeze([
 var LOGIN_AFTER_OWN_ERROR = "the login may not have completed; where a token was minted, list_tokens from your tool shows it by its label, and revoke_token ends it; run login again to log this computer in";
 var LOGIN_ROW = Object.freeze({
   name: LOGIN_SUBCOMMAND,
-  summary: `Logs this computer in at the platform's address: it opens the platform's computer login page (${COMPUTER_LOGIN_PATH}) in your default browser, where you approve the login under your sign-in, and keeps the token the platform mints in this computer's credential file. It then reads the account the token acts as and prints authorized: with the address, the account's sign-in address, or its id where it has none, the token's label, and its expiry. Where the browser cannot answer, it asks for the code the page shows. It prints no token, code, or verifier.`,
+  summary: `Logs this computer in at the platform's address. It opens the platform's computer login page (${COMPUTER_LOGIN_PATH}) in your default browser, where you approve the login under your sign-in. It keeps the token the platform mints in this computer's credential file. It then reads the account the token acts as, and prints authorized: with the address, the account's sign-in address (or its id where it has none), the token's label, and its expiry. Where the browser cannot answer, it asks for the code the page shows. It prints no token, code, or verifier.`,
+  example: LOGIN_SUBCOMMAND,
   options: LOGIN_OPTIONS,
   credential: null,
   reads: "nothing from standard input; with the browser it waits for the page to answer on a port of this computer, and with --no-browser it reads the code the page shows from the terminal, hidden; once the token is kept, it reads the account through read_account under it",
@@ -6027,7 +6037,8 @@ async function logout(call, io2) {
 }
 var LOGOUT_ROW = Object.freeze({
   name: LOGOUT_SUBCOMMAND,
-  summary: "Ends this computer's authorization at the platform's address: revokes the token the credential file keeps for it, under the token itself, removes the token and any pending request from the file, and prints logged out: with the address and the token's id. Where the platform cannot be reached or refuses, it removes both all the same and names revoke_token with the id.",
+  summary: "Ends this computer's authorization at the platform's address. It revokes the token the credential file keeps for that address, under the token itself. It removes the token and any pending request from the file, and prints logged out: with the address and the token's id. Where the platform cannot be reached or refuses, it still removes both, and names revoke_token with the id.",
+  example: LOGOUT_SUBCOMMAND,
   options: LOGOUT_OPTIONS,
   credential: null,
   reads: "this computer's token for the origin from its credential file, and sends it only to that origin",
@@ -6115,7 +6126,8 @@ async function whoami(call, io2) {
 }
 var WHOAMI_ROW = Object.freeze({
   name: WHOAMI_SUBCOMMAND,
-  summary: `Names the account this computer's token acts as at the platform's address: it reads the token the credential file keeps for the address and makes one ${READ_ACCOUNT_ACTION} call under it. It prints the address, the account's sign-in address and id, and the token's label and expiry. With no token for the address, it sends nothing, names the ways on with no login (deploy_files, ${AUTHORIZE_SUBCOMMAND}, and ${PROVISION_SUBCOMMAND}), and then prints the login route. It prints no token.`,
+  summary: `Names the account this computer's token acts as at the platform's address. It reads the token the credential file keeps for the address, and makes one ${READ_ACCOUNT_ACTION} call under it. It prints the address, the account's sign-in address and id, and the token's label and expiry. With no token for the address, it sends nothing. It names the ways on with no login (deploy_files, ${AUTHORIZE_SUBCOMMAND}, and ${PROVISION_SUBCOMMAND}), then prints the login route. It prints no token.`,
+  example: WHOAMI_SUBCOMMAND,
   options: WHOAMI_OPTIONS,
   credential: null,
   reads: "this computer's token for the origin from its credential file, never a minted token from TURNZERO_CLOUD_MINTED_TOKEN, and sends it only to that origin",
@@ -6701,14 +6713,15 @@ async function remintAndWrite(io2, { application, envFile, origin }, userAgent,
 }
 var PROVISION_ROW = Object.freeze({
   name: PROVISION_SUBCOMMAND,
-  summary: `Re-mints an application's development platform credential, and its development database credential where the application has a development database, and writes the local run's settings into the environment file: ${[
+  summary: `Re-mints an application's development platform credential, and its development database credential where it has a development database. It then writes the local run's settings into the environment file: ${[
     LOCAL_RUN_SETTING.databaseConnection,
     LOCAL_RUN_SETTING.databaseConnectionLimit,
     LOCAL_RUN_SETTING.platformCredential,
     LOCAL_RUN_SETTING.environment,
     LOCAL_RUN_SETTING.api,
     LOCAL_RUN_SETTING.gatewayUrl
-  ].join(", ")}, and ${LOCAL_RUN_SETTING.application}, the first two only where the application has a development database. It removes a ${RETIRED_PLATFORM_CREDENTIAL_SETTING} line, the platform credential's earlier name. It prints no credential value.`,
+  ].join(", ")}, and ${LOCAL_RUN_SETTING.application}. It writes the first two only where the application has a development database. It removes a ${RETIRED_PLATFORM_CREDENTIAL_SETTING} line, the platform credential's earlier name. It prints no credential value.`,
+  example: `${PROVISION_SUBCOMMAND} ${PROVISION_OPTION.application} <application id>`,
   options: PROVISION_OPTIONS,
   credential: PROVISION_CREDENTIAL,
   reads: PROVISION_READS,
@@ -6747,7 +6760,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 Claude Code or Codex" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect your AI tool" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill.",
       "",
       "## What you run here",
@@ -7021,7 +7034,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 Claude Code or Codex" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect your AI tool" says how.`,
       "- Before you change or deploy this service, read the server's `deploy` skill.",
       "",
       "## What you run here",
@@ -7140,7 +7153,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 Claude Code or Codex" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect your AI tool" 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",
@@ -7346,7 +7359,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 Claude Code or Codex" says how.`,
+      `- Where the server is not connected, connect it first. The platform's page "Connect your AI tool" 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",
@@ -9118,7 +9131,8 @@ var SCAFFOLD_AFTER_LOGIN = `Once ${LOGIN_SUBCOMMAND} has printed authorized:, ru
 var SCAFFOLD_SIGN_IN_WHY = `A template that takes library entries needs a sign-in, since the library's reads are under a credential; ${SCAFFOLD_DEFAULT_TEMPLATE}, which takes none, runs without one.`;
 var SCAFFOLD_ROW = Object.freeze({
   name: SCAFFOLD_SUBCOMMAND,
-  summary: `Writes a new service from a template into a project, ${SCAFFOLD_DEFAULT_TEMPLATE} where the line names no ${SCAFFOLD_OPTION.template}. A template that takes library entries, as database-service takes the Database entry and web-app takes three, takes each as library take does, under the credential library take reads, checking each file's SHA-256 and each entry's closure hash before it writes anything. It then writes the template's files under app/, the manifest's packages member filled from the library folder's rows, runs npm install and npm test there, and prints the next steps. Where such a template reads no credential, it writes nothing and prints the login route, closed by this line to run again once signed in. It starts a new application and writes over none. A template that takes no entry reads no credential.`,
+  summary: `Writes a new service from a template into a project, ${SCAFFOLD_DEFAULT_TEMPLATE} where the line names no ${SCAFFOLD_OPTION.template}. It writes the template's files under app/, runs npm install and npm test there, and prints the next steps. It starts a new application, and writes over no file. Some templates take library entries: database-service takes the Database entry, and web-app takes three. Such a template takes each entry as library take does, under the same credential and with the same checks, before it writes anything. It fills the manifest's packages member from the library folder's rows. With no credential, it writes nothing, and prints the login route and this line to run again once you are signed in. A template that takes no entry reads no credential.`,
+  example: `${SCAFFOLD_SUBCOMMAND} ${SCAFFOLD_OPTION.template} database-service ${SCAFFOLD_OPTION.path} <project root>`,
   options: SCAFFOLD_OPTIONS,
   credential: SCAFFOLD_CREDENTIAL,
   reads: SCAFFOLD_READS,
@@ -9442,7 +9456,8 @@ async function session(call, io2) {
 }
 var SESSION_ROW = Object.freeze({
   name: SESSION_SUBCOMMAND,
-  summary: `Signs a test end user in and writes the session's cookie into a file curl -b reads, through one ${SIGN_IN_TEST_END_USER_ACTION} call under the credential ${DEPLOY_SUBCOMMAND} reads. It prints one line naming the hostname, the end user, the expiry, and the file, never the cookie's value. With no credential, it sends nothing and prints the two routes to one.`,
+  summary: `Signs a test end user in, and writes the session's cookie into a file curl -b reads. It makes one ${SIGN_IN_TEST_END_USER_ACTION} call under the credential ${DEPLOY_SUBCOMMAND} reads. It prints one line naming the hostname, the end user, the expiry, and the file, never the cookie's value. With no credential, it sends nothing and prints the two routes to one.`,
+  example: `${SESSION_SUBCOMMAND} ${SESSION_OPTION.application} <application id> ${SESSION_OPTION.environment} development ${SESSION_OPTION.endUser} <end user id or label> ${SESSION_OPTION.out} <path>`,
   options: SESSION_OPTIONS,
   credential: SESSION_CREDENTIAL,
   reads: SESSION_READS,
@@ -9516,7 +9531,8 @@ async function token(call, io2) {
 var TOKEN_ROW = Object.freeze({
   name: TOKEN_SUBCOMMAND,
   acts: TOKEN_ACTS,
-  summary: `Mints a token that is not this computer's, its value never in the chat, in two acts around one ${MINT_TOKEN_ACTION} call your tool makes. ${TOKEN_ACTS[0]} keeps a verifier in this computer's credential file and prints the challenge and the call. ${TOKEN_ACTS[1]}, run by you in a terminal outside the AI coding tool with the token code the call's line pipes in, presents the code with the verifier and prints the token's value once to standard output, every other line on standard error.`,
+  summary: `Mints a token that is not this computer's, keeping its value out of the chat, in two acts around one ${MINT_TOKEN_ACTION} call your tool makes. ${TOKEN_ACTS[0]} keeps a verifier in this computer's credential file, and prints the challenge and the call. You run ${TOKEN_ACTS[1]} yourself, in a terminal outside the AI coding tool, with the token code the call's line pipes in. It presents the code with the verifier, and prints the token's value once to standard output. Every other line goes to standard error.`,
+  example: `${TOKEN_SUBCOMMAND} ${TOKEN_ACTS[0]}`,
   options: TOKEN_OPTIONS,
   credential: TOKEN_CREDENTIAL,
   statuses: {
@@ -9892,9 +9908,17 @@ var usageHeadOf = (version) => `${TURNZERO_CLOUD_PACKAGE} ${version}: the Turn Z
 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 exampleLineOf = (subcommand) => {
+  const credential = subcommand.credential;
+  const mustPipe = credential !== null && credential.piped !== false && credential.bare === void 0 && credential.computerToken !== true;
+  return `${mustPipe ? `echo <${credential.grant}> | ` : ""}${SERVED} ${subcommand.example}`;
+};
 var sectionLinesOf = (subcommand) => [
   `${namedWithActs(subcommand)}: ${subcommand.summary}`,
   "",
+  "Example:",
+  `  ${exampleLineOf(subcommand)}`,
+  "",
   "Options:",
   ...subcommand.options.flatMap((option) => [`  ${shown(option)}${option.required ? " (required)" : ""}`, `      ${option.description}`]),
   ""
@@ -9911,7 +9935,7 @@ 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 mintedTokenVariableLine = () => `  ${MINTED_TOKEN_VARIABLE}  under ${listed(unattendedNames())}, a minted token for a tool connected by a minted token, or for an unattended run. Set it 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.`;
@@ -9928,7 +9952,7 @@ var usageBlockOf = (subcommandHelp) => [
   ...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 SUBCOMMAND_HELP_SENTENCE = `Run ${SERVED} <subcommand> --help for that subcommand's example, 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),
@@ -9962,8 +9986,8 @@ 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 grantArgumentSentence = () => "An argument holds a grant. 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. The command never takes a credential from its arguments: it reads a minted token from ${MINTED_TOKEN_VARIABLE} alone. A tool connected by a minted token, or an unattended run, sets that variable 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.";
 var unquoted = (value) => value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
 var quoteInPathSentence = (name) => `${name} names a path, and its value holds a double quote, which no path on Windows holds. The usual cause is a path written with a backslash before its closing quote, which cmd and Windows PowerShell 5.1 read as keeping the quote, joining the arguments after it into the value. Write the path with no backslash at its end. ${NOTHING_STARTED2}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turnzero",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "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",