deepline 0.3.370 → 0.3.371

package/dist/cli/{chunk-IDBLJSLL.mjs → chunk-3FTYFVYN.mjs}

@@ -2,7 +2,7 @@ import {
   argsWantJson,
   openInBrowser,
   printCommandEnvelope
-} from "./chunk-GGRVNAOH.mjs";
+} from "./chunk-DOXAN2I7.mjs";
 import {
   ACTIVE_ORG_ID_ENV,
   ACTIVE_ORG_NAME_ENV,
@@ -25,7 +25,7 @@ import {
   saveHostEnvValues,
   saveProjectDeeplineEnvValues,
   storedHostApiKey
-} from "./chunk-LJWOPNJJ.mjs";
+} from "./chunk-KKRRIFR3.mjs";
 
 // src/cli/commands/auth.ts
 import {
@@ -825,7 +825,7 @@ Common commands:
   deepline auth register
   deepline auth wait --timeout 300
   deepline auth status
-  deepline auth status --json
+  deepline auth status
 
 Notes:
   Auth status shows the target host and active workspace without printing secrets.
@@ -909,12 +909,12 @@ Notes:
 Examples:
   deepline auth status
   deepline auth status --auth-scope folder
-  deepline auth status --json
+  deepline auth status
 `
   ).option(
     "--reveal",
     "Persist the revealed API key back to the host auth file"
-  ).option("--auth-scope <scope>", "Read only folder or global auth").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--auth-scope <scope>", "Read only folder or global auth").option("--json", "Emit JSON output").action(async (options) => {
     process.exitCode = await handleStatus([
       ...options.reveal ? ["--reveal"] : [],
       ...options.authScope ? ["--auth-scope", String(options.authScope)] : [],

package/dist/cli/{chunk-Z6B4UPM4.mjs → chunk-3GK3SH3G.mjs}

@@ -314,11 +314,11 @@ function examples(described, options) {
 }
 var EXPLANATIONS = {
   tool: {
-    cli: "--input takes a JSON object or @file.json. The result prints when the call finishes; add --json for the full result payload.",
+    cli: "--input takes a JSON object or @file.json. The result prints when the call finishes.",
     play: "id names the step and must stay stable. Read a declared output with its getter; every other provider field is in result.toolResponse.rawV2."
   },
   play: {
-    cli: "--input takes a JSON object or @file.json. The run waits and prints its output; add --json for the full result, or read it later with deepline runs get <run-id> --json.",
+    cli: "--input takes a JSON object or @file.json. The run waits and prints its output; read it later with deepline runs get <run-id>.",
     play: "The first argument is a stable key for the child run. The call waits and returns the output object."
   },
   monitor: {

package/dist/cli/{chunk-4Y5UDYQK.js → chunk-44SHFHA3.js}

@@ -21,7 +21,7 @@ var _chunkLA46MMTLjs = require('./chunk-LA46MMTL.js');
 
 
 
-var _chunkSFI7U6CAjs = require('./chunk-SFI7U6CA.js');
+var _chunkA7X7KFXXjs = require('./chunk-A7X7KFXX.js');
 
 
 
@@ -167,7 +167,7 @@ async function queryCustomerDatabase(http, input) {
     if (error instanceof _chunk7P5AA3SNjs.DeeplineError && (_optionalChain([error, 'access', _2 => _2.code, 'optionalAccess', _3 => _3.startsWith, 'call', _4 => _4("NETWORK_")]) || // Older API readers return PostgreSQL errors as HTTP 400, including
     // lost connections and explicitly unknown transaction resolution.
     /^08[A-Z0-9]{3}$/.test(_nullishCoalesce(error.code, () => ( ""))) || ["57P01", "57P02", "57P03"].includes(_nullishCoalesce(error.code, () => ( ""))) || error.statusCode === 408 || (_nullishCoalesce(error.statusCode, () => ( 0))) >= 500)) {
-      throw new (0, _chunkSFI7U6CAjs.CustomerDbQueryOutcomeUnknownError)(
+      throw new (0, _chunkA7X7KFXXjs.CustomerDbQueryOutcomeUnknownError)(
         error,
         plan.request.body.operation_key
       );
@@ -175,7 +175,7 @@ async function queryCustomerDatabase(http, input) {
     throw error;
   }
   if (!result || typeof result !== "object" || Array.isArray(result) || typeof result.command !== "string" || !Array.isArray(result.columns) || !Array.isArray(result.rows) || typeof result.truncated !== "boolean" || result.row_count !== null && (!Number.isSafeInteger(result.row_count) || result.row_count < 0) || !Number.isSafeInteger(result.row_count_returned) || result.row_count_returned < 0) {
-    throw new (0, _chunkSFI7U6CAjs.CustomerDbQueryOutcomeUnknownError)(
+    throw new (0, _chunkA7X7KFXXjs.CustomerDbQueryOutcomeUnknownError)(
       new (0, _chunk7P5AA3SNjs.DeeplineError)(
         "The SQL response did not contain a valid result.",
         200,
@@ -186,7 +186,7 @@ async function queryCustomerDatabase(http, input) {
   }
   const operation = result.operation;
   if (input.operationKey !== void 0 && (!operation || operation.operation_key !== input.operationKey || !Number.isSafeInteger(operation.completed_at_ms) || operation.completed_at_ms < 0 || !["executed", "operation_recovery"].includes(operation.source))) {
-    throw new (0, _chunkSFI7U6CAjs.CustomerDbQueryOutcomeUnknownError)(
+    throw new (0, _chunkA7X7KFXXjs.CustomerDbQueryOutcomeUnknownError)(
       new (0, _chunk7P5AA3SNjs.DeeplineError)(
         "The server did not confirm the original atomic SQL operation.",
         200,
@@ -2910,8 +2910,8 @@ function runtimeSelectionHeaders(runtime) {
   }
   const receivers = _optionalChain([process, 'access', _104 => _104.env, 'access', _105 => _105.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS, 'optionalAccess', _106 => _106.trim, 'call', _107 => _107()]);
   return {
-    [_chunkSFI7U6CAjs.RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
-    ...receivers ? { [_chunkSFI7U6CAjs.RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
+    [_chunkA7X7KFXXjs.RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
+    ...receivers ? { [_chunkA7X7KFXXjs.RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
   };
 }
 function isolatedCiRuntimeEventReadHeaders() {
@@ -2927,7 +2927,7 @@ function isolatedCiRuntimeEventReadHeaders() {
       "RUNTIME_EVENT_INTERNAL_TOKEN_REQUIRED"
     );
   }
-  return { [_chunkSFI7U6CAjs.COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
+  return { [_chunkA7X7KFXXjs.COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
 }
 function normalizeTestPolicyOverrides(value, source) {
   if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -3217,8 +3217,8 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
   constructor(options) {
-    this.config = _chunkSFI7U6CAjs.resolveConfig.call(void 0, options);
-    this.http = new (0, _chunkSFI7U6CAjs.HttpClient)(this.config);
+    this.config = _chunkA7X7KFXXjs.resolveConfig.call(void 0, options);
+    this.http = new (0, _chunkA7X7KFXXjs.HttpClient)(this.config);
     this.toolCalls = new ToolCalls(
       this.http,
       this.config.timeout,
@@ -3409,7 +3409,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
-      // playKey and triggerStatus were projected away here, so `plays describe`
+      // playKey and triggerStatus were projected away here, so `describe`
       // was strictly less informative than `plays list` for the same play — no
       // stable key, and no way to see that a cron was armed.
       ...play.playKey ? { playKey: play.playKey } : {},
@@ -4313,7 +4313,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * This is the SDK equivalent of:
    *
    * ```bash
-   * deepline runs get <run-id> --json
+   * deepline runs get <run-id>
    * ```
    */
   async getRunStatus(runId, options) {
@@ -4350,7 +4350,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
       });
     } catch (error) {
       failedLogsLoaded = false;
-      const retryCommand = `deepline runs logs ${runId} --failed --json`;
+      const retryCommand = `deepline runs logs ${runId} --failed`;
       const reason = error instanceof Error && error.message.trim() ? ` (${error.message.trim().slice(0, 500)})` : "";
       failedLogs = {
         runId,
@@ -4417,7 +4417,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * This is the SDK equivalent of:
    *
    * ```bash
-   * deepline runs list --play <play-name> --status failed --json
+   * deepline runs list --play <play-name> --status failed
    * ```
    */
   async listRuns(options) {
@@ -4555,7 +4555,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * This is the SDK equivalent of:
    *
    * ```bash
-   * deepline runs logs <run-id> --limit 200 --json
+   * deepline runs logs <run-id> --limit 200
    * ```
    */
   async getRunLogs(runId, options) {
@@ -4847,7 +4847,7 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * This is the SDK equivalent of:
    *
    * ```bash
-   * deepline runs stop <run-id> --reason "stale lock" --json
+   * deepline runs stop <run-id> --reason "stale lock"
    * ```
    */
   async stopRun(runId, options) {
@@ -4863,8 +4863,8 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * This is the SDK equivalent of:
    *
    * ```bash
-   * deepline runs stop-all --dry-run --json
-   * deepline runs stop-all --reason "stale lock" --json
+   * deepline runs stop-all --dry-run
+   * deepline runs stop-all --reason "stale lock"
    * ```
    *
    * Use this when a failed parent run left child or waiting runs active and you

package/dist/cli/{chunk-RLXMRC6P.mjs → chunk-46JCJ7FT.mjs}

@@ -1,14 +1,14 @@
 // src/cli/command-docs.ts
 var CONVENTIONS = `
 Conventions (apply to every command):
-  Output mode: structured commands print JSON automatically when stdout is not
-    a terminal, which is the case inside agent tool shells. --json forces it in
-    a terminal. search is the exception: readable unless --json.
+  Output mode: readable text by default. --json prints JSON. tools execute
+    is the exception: it prints JSON; --output-format csv prints a readable
+    summary and writes the rows to a CSV file.
   Streams: stdout carries only the command result. Progress, update notices,
     skills-sync notes, and warnings go to stderr.
-  Piping JSON: 2>&1 puts stderr text in front of the JSON, so the parse fails
-    and the real error is hidden; | head and | tail cut the document. Parse
-    stdout alone (--json | python3 ..., or --json > out.json).
+  Piping JSON: pass --json only when a program parses the output, and parse
+    stdout alone. 2>&1 puts stderr text in front of the JSON, so the parse
+    fails and the real error is hidden; | head and | tail cut the document.
   JSON envelope: most payloads include render.sections[].lines (the human
     summary as text), next.* (exact follow-up commands; run commands name
     them actions.*Cmd), and command_context.
@@ -43,7 +43,7 @@ What Deepline is for:
            priced per call. Discover with search, inspect with tools
            describe, call with tools execute.
     plays  a durable workflow, usually a prebuilt waterfall over a CSV. Discover
-           with search, read the contract with plays describe, start with
+           with search, read the contract with describe, start with
            plays run.
     runs   one execution of a play: status, rows, logs, cost, and export.
            Inspect with runs get, download rows with runs export.
@@ -51,11 +51,11 @@ What Deepline is for:
 The agent path for a typical task:
   deepline --help prints the CLI version and the auth state on its first two
   lines, checked live. Do not run version or auth status as well.
-  1. deepline preflight             only when you need the credit balance
+  1. deepline billing balance       only when you need the credit balance
   2. deepline search "<input you have -> result you need>"
                                     one search over prebuilt plays, tools, your
                                     workspace's plays, and monitor types
-  3. deepline plays describe <ref>  read required input, CSV columns, output
+  3. deepline describe <ref>  read required input, CSV columns, output
   4. deepline plays run <ref> --input '{"csv":"file.csv"}'   waits, prints run id
   5. deepline runs export <run-id> --out result.csv          rows as CSV
   6. deepline billing usage --run-id <run-id>                what it cost
@@ -75,7 +75,7 @@ Working rules:
     domain, so do not split the file or run a second pass. Phones: a known
     person -> person-to-phone-batch.
   The balance is a ceiling, not a budget to use up. Before each paid call,
-    estimate its cost: the price from tools describe <tool> --pricing-only or
+    estimate its cost: the price from describe <tool> or
     plays list --show-cost, times the results or rows you will request. Take
     the cheapest route that can answer and test it with the smallest limit.
     If one tool call would cost more than about 5 credits, lower its limit or
@@ -108,50 +108,7 @@ Auth in non-interactive shells:
 Skills:
   The bare skills command reinstalls the Deepline skill files on disk. To see
   which skills are installed without changing anything, run
-  skills --dry-run --json and read the plan.
-`
-  },
-  preflight: {
-    core: `
-Purpose:
-  One read-only call that reports server health, whether this shell is
-  authenticated, and the workspace's Deepline credit balance.
-When:
-  Once at the start of a task, before the first paid call. Its balance is the
-  balance for the whole task; do not repeat preflight, auth status, or billing
-  balance later unless a command fails with an auth or balance error.
-Input:
-  No arguments. --json forces JSON in a terminal (automatic when piped).
-Output (JSON):
-  status ("ok" or "error"), cli_version, host, health.status, auth.connected
-  (boolean),
-  auth.org_name, billing.balance (number of Deepline credits),
-  billing.balance_display, billing.balance_status, and render.sections with
-  the four-line human summary.
-Cost:
-  Free. Makes no provider calls.
-Avoid:
-  Do not treat auth.connected false as something to fix with auth register in
-  an unattended shell; report it instead.
-`,
-    verbose: `
-Output fields:
-  health.status       "ok" when the API answered; anything else means the host
-                      is unreachable or degraded and paid work should not start.
-  health.version      API version string, currently "v2".
-  auth.status         "claimed" for a working key; auth.connected mirrors it as
-                      a boolean and is the field to branch on.
-  auth.org_id/org_name  the workspace every following command will bill.
-  auth.rate_limit_tier  informational.
-  billing.balance     Deepline credits available now. Compare it with a play's
-                      cost estimate (plays list --show-cost) times the row
-                      count before running a large file.
-  billing.rough_usd_balance  the same balance in approximate USD.
-  billing.balance_status  "active" normally; other values mean the workspace
-                      cannot spend and runs will fail with a balance error.
-Related:
-  health (server only), auth status (identity only), billing balance (credits
-  only). preflight is the union and is the one to prefer.
+  skills --dry-run and read the plan.
 `
   },
   health: {
@@ -159,7 +116,7 @@ Related:
 Purpose:
   Read-only connectivity check that prints the server's raw health payload.
 When:
-  Only when preflight reports a health problem and you want the raw payload,
+  Only when a command cannot reach the server and you want the raw payload,
   or with --play-runner to prove the whole play execution plane works.
 Input:
   No arguments. --play-runner runs a tiny no-provider play end to end.
@@ -169,7 +126,8 @@ Output (JSON):
 Cost:
   Free. --play-runner uses no providers.
 Avoid:
-  Do not use health to check auth or balance; preflight covers all three.
+  Do not use health to check auth or balance; use auth status or billing
+  balance.
 `
   },
   "auth status": {
@@ -179,7 +137,7 @@ Purpose:
   as, without changing anything.
 When:
   When you need the workspace name or id, or to confirm auth after a 3 exit
-  code. For the routine start-of-task check, prefer preflight.
+  code.
 Input:
   No arguments. --auth-scope folder|global reads one auth store only.
   --reveal persists the API key into the local auth file; do not use it.
@@ -234,9 +192,8 @@ Cost:
 Purpose:
   Read the workspace's current Deepline credit balance.
 When:
-  After a run reports a balance or insufficient-credits error, or when you
-  need only the balance and preflight was not run. preflight already
-  includes this number; do not call both at the start of a task.
+  Once at the start of a task, before the first paid call, and after a run
+  reports a balance or insufficient-credits error.
 Input:
   No arguments. Prints one line, "Balance: N credits". --verbose adds
   reservations and usage awaiting settlement; --json returns the full record.
@@ -259,7 +216,7 @@ When:
   include cost unless you pass --full.
 Input:
   --run-id <run-id> scopes the spend to one play run. --limit and --cursor
-  page the recent-call list. --json forces JSON.
+  page the recent-call list. --json prints JSON.
 Output (JSON):
   balance, usage.last_30_days_usage_credits, usage.month_spent_credits, and
   with --run-id: run.spent_credits, run.rough_usd_spent, run.event_count.
@@ -271,7 +228,7 @@ Avoid:
 `,
     verbose: `
 Output fields:
-  balance, balance_display, rough_usd_balance   the same balance preflight shows.
+  balance, balance_display, rough_usd_balance   credits available now.
   plan.usd_per_credit                            conversion used for rough USD.
   usage.month_spent_credits                      spend in the current period.
   usage.last_30_days_usage_credits               trailing-30-day spend.
@@ -308,7 +265,7 @@ Input:
   comma-separated list. --categories <a,b> and --search_terms <a,b> filter
   tools and work without a task. --limit (1-50) and --offset page.
 Output:
-  A readable ranked list by default, also when piped; read that form. With
+  A readable ranked list by default; read that form. With
   --json: results[] where each item has id, kind (tool, prebuilt_play,
   custom_play, monitor_type), displayName, and description. A tool adds
   provider, categories, inputFields, pricing, connected, and executeCommand;
@@ -344,15 +301,11 @@ Input:
   A play your workspace created is shown instead of a Deepline tool or
   prebuilt play of the same name; --prebuilt shows the Deepline one.
 Output:
-  Readable text by default, also when piped; read that form. With --json:
+  Readable text by default; read that form. With --json:
   kind, id, displayName, description, cost, inputs[], outputs[], and
-  runExamples {cli, play}, plus the fields tools describe or plays describe
-  returns for that kind.
+  runExamples {cli, play}, plus the kind's own fields.
 Cost:
   Free.
-Avoid:
-  tools describe and plays describe are this command limited to one kind and
-  keep their own flags (--pricing-only, --examples-only, --getters-only).
 `
   },
   tools: {
@@ -366,11 +319,11 @@ When:
   reuse completed rows, and export.
 The sequence:
   search <words>              ranked tools and plays for an intent
-  tools describe <id>         required input fields, pricing, output shape
+  describe <id>         required input fields, pricing, output shape
   tools execute <id> --input '{...}'   run it
 Cost:
   search, describe, list, and grep are free. execute can spend credits; the
-  price is in tools describe <id> --pricing-only.
+  price is in describe <id>.
 `
   },
   "tools grep": {
@@ -398,7 +351,7 @@ When:
   To see what kinds of tools exist (bare tools list) or to enumerate one
   category without ranking (tools list email_finder).
 Input:
-  Optional positional category. --json forces JSON.
+  Optional positional category. --json prints JSON.
 Output (JSON):
   Bare: one entry per category with its tool count. With a category: one row
   per tool with required inputs and a pricing hint. Never truncated.
@@ -415,7 +368,7 @@ When:
   Always before paying for an unfamiliar tool; the input schema is the only
   reliable source of field names.
 Input:
-  The tool id. Prints readable text by default, also when piped; read that
+  The tool id. Prints readable text by default; read that
   form and pass --json only for a program. --pricing-only, --schema-only,
   --examples-only, --getters-only print one section. --byok prints only
   whether you can use your own provider credentials and how to connect them. --out <path> saves the
@@ -491,17 +444,17 @@ Output (JSON):
   listSourcePath}, summary, next, render.sections. Errors return a non-zero
   exit code and an error object, not a completed status.
 Cost:
-  Spends Deepline credits per call at the price in tools describe. A search
+  Spends Deepline credits per call at the price in describe. A search
   with limit N is one call; it is not billed per result.
 Avoid:
   Do not wrap the result in shell parsing to find rows; output_preview
   already lists the row path and the first rows, and --out writes the CSV.
-  Do not add 2>&1 when you parse --json: stderr text breaks the parse. A
+  Do not add 2>&1 when you parse the JSON: stderr text breaks the parse. A
   failed call prints its error as JSON on stdout.
 `,
     verbose: `
 Input rules:
-  The object must match inputSchema.fields from tools describe. Extra keys
+  The object must match inputSchema.fields from describe. Extra keys
   are rejected by most providers. Nested filter objects (for example
   crustdata_v3_* filters) must be passed as JSON, so use --input, not -p.
   An @path value is read relative to the current directory.
@@ -514,12 +467,12 @@ Output fields:
                          toolResponse, for example toolResponse.raw.companies.
   output_preview.preview a bounded sample of rows; the full array is at the
                          listSourcePath, and --out writes all of it as CSV.
-  next.inspect           the same command with --json, for debugging.
+  next.inspect           a read-only command that inspects the call, for debugging.
 Cases:
   Insufficient credits fail before the provider is called, with an
-  insufficient-credits error; check the preflight balance first.
+  insufficient-credits error; check billing balance first.
   A provider that needs a connected account fails with an auth or permission
-  error; tools describe shows connected false beforehand.
+  error; describe shows connected false beforehand.
   Free tools (run_javascript, free_* ids) never charge.
 Related:
   To run the same operation over many rows, put the rows in a CSV and use a
@@ -538,7 +491,7 @@ When:
   rows on rerun, so a failed run can be resumed instead of repaid.
 The sequence:
   search "<input you have -> result you need>"   find the play
-  plays describe <ref>          required input, CSV columns, output fields
+  describe <ref>          required input, CSV columns, output fields
   plays list --show-cost        per-row or per-run credit estimate
   plays run <ref> --input '{"csv":"file.csv"}'   start and wait
   runs export <run-id> --out out.csv             rows
@@ -552,7 +505,7 @@ Writing a play:
   The file is: export default definePlay('name', async (ctx, input) => {...}).
   --help --verbose lists the authoring rules.
 Auditing plays:
-  plays list --json             every saved play
+  plays list                    every saved play
   plays versions --name <play>  its revisions, and which one is live
   plays get <play> --source --out <dir>          a revision's source (--live,
                                 --working, or --revision <n>)
@@ -582,7 +535,7 @@ Authoring rules:
     rows.peek(n), rows.materialize(n), or for await. Array methods on a
     handle fail plays check.
   Tool calls: rowCtx.tools.execute({ id, tool, input, description }). Read
-    results through the getters tools describe lists:
+    results through the getters describe lists:
     result.extractedValues.<name>.get() and
     result.extractedLists.<name>.get(). A field with no getter is under
     result.toolResponse.rawV2 with the provider's nesting kept.
@@ -622,7 +575,7 @@ Purpose:
 When:
   Finding a saved play by a phrase in its source or description.
 Input:
-  A query. --json forces JSON.
+  A query. --json prints JSON.
 Output (JSON):
   Matching owned plays with the matched fields and terms.
 Cost:
@@ -639,7 +592,7 @@ When:
   cost estimate line for the play, or costEstimate in JSON.
 Input:
   --show-cost adds estimates. --limit and --cursor page. --categories
-  filters by tool category. --json forces JSON.
+  filters by tool category. --json prints JSON.
 Output (JSON):
   plays[] with playKey, reference, displayName, description, origin,
   runCount, lastRun, and with --show-cost costEstimate {status, unit ("row"
@@ -650,13 +603,13 @@ Output (JSON):
 Cost:
   Free.
 Avoid:
-  plays describe does not include a cost estimate; this command does.
+  describe does not include a cost estimate; this command does.
 `,
     verbose: `
 Pricing a run:
   Multiply lowCredits..highCredits by the row count when unit is "row", or
-  use it directly when unit is "run". Compare with billing.balance from
-  preflight. When the estimate is unavailable, run a two-row slice first and
+  use it directly when unit is "run". Compare with the billing balance.
+  When the estimate is unavailable, run a two-row slice first and
   read its actual spend with billing usage --run-id <run-id>.
 Output fields:
   costEstimate.source      "observed" (from past runs; shown with ~) or
@@ -676,7 +629,7 @@ When:
   reliable source of the input field and column names.
 Input:
   The play reference from search (prebuilt/... or <workspace>/...).
-  --compact shortens schemas. --json forces JSON.
+  --compact shortens schemas. --json prints JSON.
 Output (JSON):
   name, reference, displayName, description, inputSchema (JSON Schema plus
   fields[] {name, required, type}), outputSchema, csvInput {inputField,
@@ -739,7 +692,7 @@ When:
   Before running a local play file, and after editing one. Free, so run it
   every time.
 Input:
-  A local path ending in .play.ts, or a play reference. --json forces JSON.
+  A local path ending in .play.ts, or a play reference. --json prints JSON.
 Output (JSON):
   valid (boolean), target, name, reference, inputSchema, outputSchema,
   runtimeLimit, note, and for local files any errors or warnings with the
@@ -914,7 +867,7 @@ Input:
   The run id. --full resolves a full-only result and adds diagnostics with
   billing and timeline (large). --log-failed attaches the failure log window.
   --input prints the original input (may contain customer data). --json
-  forces JSON; --json run.status,datasets.name selects fields.
+  prints JSON; --json run.status,datasets.name selects fields.
 Output (JSON):
   kind "run_overview", run {id, playName, status, startedAt, finishedAt,
   durationMs}, steps[] {id, kind, status, label, progress {total, executed,
@@ -1054,7 +1007,7 @@ When:
   log. Without a run id it searches events: which runs or steps failed
   (--kind run.failed, --kind step.failed), with --payloads for the details.
   To read what a tool call in a run returned: runs logs <run-id> --kind
-  receipt.completed --payloads --json, then one exact result by its eventId
+  receipt.completed --payloads, then one exact result by its eventId
   with --where.
 Input:
   A run id alone reads text logs; no run id, or any search flag, searches
@@ -1080,7 +1033,7 @@ Purpose:
 When:
   A row of a run's output records a receipt key and you need what that tool
   call returned. Without a key, find the call first with runs logs <run-id>
-  --kind receipt.completed --payloads --json.
+  --kind receipt.completed --payloads.
 Input:
   The run id, then --key <key> (repeatable) or --keys <file> with one key
   per line (--keys - reads stdin). --out <file> writes the JSON to a new
@@ -1126,7 +1079,7 @@ When:
   running lists them. Completed work is kept and reused by a later run of the
   same play and input.
 Input:
-  The run id and --reason "<text>". --json forces JSON.
+  The run id and --reason "<text>". --json prints JSON.
 Output (JSON):
   The run's new status; cancellation is asynchronous, so poll runs get.
 Cost:
@@ -1310,7 +1263,7 @@ Purpose:
   from the current release. It writes to disk.
 When:
   Only when asked to install or update skills. To see what is installed
-  without changing anything, use --dry-run --json and read the plan.
+  without changing anything, use --dry-run and read the plan.
 Input:
   --scope global|local, --agent <target>, --dry-run, --json.
 Output (JSON):
@@ -1345,8 +1298,8 @@ Purpose:
   Read-only diagnosis of the local install: CLI version, skills, auth,
   workspace, and API connectivity, with suggested repairs.
 When:
-  When something local is wrong (skills missing, auth file odd). For the
-  routine start-of-task check use preflight; doctor is stricter and exits 7
+  When something local is wrong (skills missing, auth file odd). Doctor is
+  stricter and exits 7
   when any check fails, which is common in sandboxes with no skills on disk.
 Input:
   --scope global|local. --json.