deepline 0.3.357 → 0.3.358

package/dist/cli/chunk-QFBHEQCQ.mjs

@@ -0,0 +1,1421 @@
+// 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.
+  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).
+  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.
+    Read render.sections when you want the short human view of a JSON result.
+  File inputs: every --input, --payload, and --sql flag accepts inline text or
+    @path to read the value from a local file, for example --input @input.json.
+  Ids: play references look like prebuilt/person-to-phone-batch or
+    <workspace-slug>/my-play; run ids look like
+    play/<play-ref>/run/<timestamp>-<suffix> and are printed by plays run.
+  Large results: prefer the narrower command over post-processing a big
+    payload: runs export for rows, billing usage --run-id for cost,
+    --compact where offered, and runs get without --full.
+  Exit codes: 0 success; 2 usage or local input error; 3 auth or permission;
+    4 not found; 5 server, runtime, or provider failure; 7 validation or
+    check failed.
+  Help detail: the first --help for a command prints its full explanation,
+    with field-level output references and edge cases; later ones print the
+    core section. --help --verbose prints the full explanation again;
+    --help --quiet prints commander help only.
+`;
+var COMMAND_DOCS = {
+  "": {
+    core: `
+Make sure to run --help before running a command, you'll often find its
+behavior has some differences from your expectations!
+
+What Deepline is for:
+  Deepline runs GTM data work: find companies and people, resolve emails and
+  phones, research accounts, and keep durable, resumable runs of that work.
+  Three nouns cover almost everything:
+    tools  one provider or API operation (search, enrich, verify). Atomic,
+           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
+           plays run.
+    runs   one execution of a play: status, rows, logs, cost, and export.
+           Inspect with runs get, download rows with runs export.
+
+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
+  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
+  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
+  Use tools execute only when no play covers the job or for one-off lookups.
+${CONVENTIONS}`,
+    verbose: `
+Working rules:
+  Search with the task as one sentence, not keywords: search "50 seed-stage
+    company domains -> each company's lead investors".
+    Results are ranked for what you have and what you need, and each one
+    names its kind: prebuilt play, tool, custom play, or monitor type.
+  A CSV goes through the batch form of a prebuilt play, never one
+    single-record run per row: plays run prebuilt/<play>-batch --input
+    '{"csv":"leads.csv"}', then runs export <run-id> --out <path>. Work
+    emails: person-to-email-batch takes the whole file in one run. Each row
+    tries its LinkedIn profile first and falls through to name and company
+    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
+    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
+    find a cheaper route first. Never top up, buy credits, or change billing
+    unless the user asks. When the balance runs out, stop spending, deliver
+    the rows you have, and name the rows left unresolved.
+  Pilot before scale: run the play on a small slice, read its actual cost
+    with billing usage --run-id <run-id>, then run the full file under the
+    same play. A stated-scope input of about 25 rows or fewer is its own
+    pilot: run it once.
+
+Choosing between tools and plays:
+  A play is the right choice when the job has rows (a CSV) or needs more than
+  one provider in sequence: waterfalls stop at the first verified hit, reuse
+  completed rows on rerun, and persist results in the customer database. A
+  tool is right for one lookup, a search that returns candidates, or when
+  search returns no play that fits. Tools have no retry, no row memory,
+  and no export; you get one JSON response.
+
+Reading results without parsing:
+  Every structured payload carries render.sections, a list of titled line
+  groups that is exactly what a terminal user would see. When a result is
+  large, read render.sections first, then the specific field you need.
+
+Auth in non-interactive shells:
+  When the Auth line of deepline --help says not connected, stop and report
+  it; auth register needs a browser approval and auth register --wait blocks
+  until it happens, so an unattended agent must not call it.
+
+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.
+`
+  },
+  health: {
+    core: `
+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,
+  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.
+Output (JSON):
+  The server health object (status, version). With --play-runner, a run
+  summary for the smoke play.
+Cost:
+  Free. --play-runner uses no providers.
+Avoid:
+  Do not use health to check auth or balance; preflight covers all three.
+`
+  },
+  "auth status": {
+    core: `
+Purpose:
+  Report which Deepline host, workspace, and user this shell is authenticated
+  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.
+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.
+Output (JSON):
+  host, hostStatus, status ("claimed" when authenticated), connected
+  (boolean), workspace {id, name, slug}, user {id}, render.sections.
+Cost:
+  Free.
+Avoid:
+  connected false in an unattended shell is a stop-and-report condition, not
+  a prompt to run auth register.
+`
+  },
+  "auth register": {
+    core: `
+Purpose:
+  Start a device-style login: it prints an approval URL, and once a person
+  approves it in a browser the shell receives a workspace API key.
+When:
+  Only in an interactive session where a person can open the URL. Never in an
+  unattended agent shell: the command has nothing to do until a human acts.
+Input:
+  No arguments. It opens the approval page and waits for approval; keep that
+  default. In Cowork it prints the link and returns, and auth wait finishes
+  the login.
+Output:
+  The approval URL and, after approval, the connected workspace.
+Cost:
+  Free.
+Avoid:
+  If auth status says connected false and you cannot open a browser, report
+  that Deepline is not connected and stop.
+`
+  },
+  "auth wait": {
+    core: `
+Purpose:
+  Poll a pending auth register approval until it completes or times out.
+When:
+  After auth register returned before approval, as it does in Cowork, and a
+  person is approving it in a browser.
+Input:
+  No arguments beyond the pending registration it finds locally.
+Output:
+  The connected workspace once approved; a timeout error otherwise.
+Cost:
+  Free.
+`
+  },
+  "billing balance": {
+    core: `
+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.
+Input:
+  No arguments. Prints one line, "Balance: N credits". --verbose adds
+  reservations and usage awaiting settlement; --json returns the full record.
+Output (JSON):
+  balance (Deepline credits), balance_display, rough_usd_balance,
+  balance_status, and render.sections. The balance includes other activity
+  in the workspace, so a before and after difference does not isolate one
+  command; use billing usage for that.
+Cost:
+  Free.
+`
+  },
+  "billing usage": {
+    core: `
+Purpose:
+  Read what the workspace, or one run, has spent in Deepline credits.
+When:
+  After a run finishes, to report its actual cost: billing usage --run-id
+  <run-id>. This is the canonical per-run cost read; runs get does not
+  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.
+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.
+  render.sections includes a "Run spend: N Deepline Credits" line.
+Cost:
+  Free.
+Avoid:
+  Do not grep a runs get payload for cost; use this command.
+`,
+    verbose: `
+Output fields:
+  balance, balance_display, rough_usd_balance   the same balance preflight shows.
+  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.
+  usage.temporary_hold_credits                   credits held by active runs.
+  run (only with --run-id)                       {run_id, spent_credits,
+                                                  rough_usd_spent, event_count};
+                                                  null when the run has no
+                                                  billing events yet.
+  quota.*                                        monthly cap, when enabled.
+  recent activity                                one line per billed call in
+                                                  render.sections, newest first.
+Cases:
+  A run that is still active shows a partial spend; read it again after the
+  run reaches completed or failed.
+  A failed run with row failures still shows spend for the rows that ran.
+`
+  },
+  search: {
+    core: `
+Purpose:
+  One ranked search across everything Deepline can run: provider tools,
+  prebuilt plays, plays this workspace created, and monitor types. Each
+  result names its kind.
+When:
+  First, for any task where you do not already know the exact play or tool.
+  Search once with the task; there is no separate search for plays and for
+  tools.
+Input:
+  One argument: the task as a sentence, written as the input you have ->
+  the result you need, for example "50 company domains -> each one's lead
+  investors". Do not send keywords; the sentence is what ranks the results.
+  --type narrows to tools, prebuilts, custom, plays (prebuilts
+  and custom), or monitors, and --exclude leaves kinds out; both take a
+  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
+  --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;
+  a play adds reference, inputFields, describeCommand, and runCommand. Also
+  kinds, count, total, next_offset when there is another page, and
+  render.sections.
+Cost:
+  Free.
+Next:
+  describe <id> reads any result, whatever its kind. Then plays run for a
+  play, tools execute for a tool. When a play and a tool both fit a job with
+  rows, take the play.
+Avoid:
+  Do not hardcode a provider list; search returns what this workspace can
+  call now. Do not run anything from search output alone; describe it first.
+  tools search and plays search are deprecated aliases of this command.
+`
+  },
+  describe: {
+    core: `
+Purpose:
+  The contract for anything search returns: a tool, a play, or a monitor
+  type. What it is, cost, inputs, outputs, and an example of running it from
+  the CLI and from inside a play.
+When:
+  After search and before the first run of something you have not used. You
+  do not say which kind the id is.
+Input:
+  The id or reference from search. --verbose fills in every input and reads
+  every output in the examples; --cli-example and --play-example print one
+  example; --schema-only prints only the schema; --full-schema unfolds a
+  schema over 100 lines; --out <path> saves the output; --json prints JSON.
+  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:
+  kind, id, displayName, description, cost, inputs[], outputs[], and
+  runExamples {cli, play}, plus the fields tools describe or plays describe
+  returns for that kind.
+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: {
+    core: `
+Purpose:
+  The atomic provider layer: one operation per call (search people, enrich a
+  company, verify an email), priced per call in Deepline credits.
+When:
+  For one-off lookups, candidate searches, or when search finds no play
+  for the job. For CSV-shaped work use a play instead: plays retry,
+  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
+  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.
+`
+  },
+  "tools grep": {
+    core: `
+Purpose:
+  Literal, case-insensitive filtering of the tool registry by id, provider,
+  description, categories, or input field names.
+When:
+  When you know a provider or field name and want every matching tool rather
+  than a ranked guess. Use search for intent queries.
+Input:
+  A query; --mode all (default, AND), any (OR), or phrase; --categories.
+Output (JSON):
+  tools[] with id, provider, displayName, description, categories, and
+  executeCommand.
+Cost:
+  Free.
+`
+  },
+  "tools list": {
+    core: `
+Purpose:
+  Browse tool categories, or list every tool in one category exhaustively.
+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.
+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.
+Cost:
+  Free.
+`
+  },
+  "tools describe": {
+    core: `
+Purpose:
+  The contract for one tool: what it does, required inputs, pricing, and
+  output shape. Read it before the first execute of a tool you have not used.
+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
+  form and pass --json only for a program. --pricing-only, --schema-only,
+  --examples-only, --getters-only print one section. --out <path> saves the
+  output to a file. get is an alias of describe, and deepline describe <id>
+  is the same read for a tool, a play, or a monitor type.
+Output (JSON):
+  kind, id, cost {displayText, unit, billingMode}, inputs[] {name, type,
+  required, example}, outputs[] {name, type, read}, runExamples {cli, play},
+  toolId, provider, displayName, bestFor, description, categories,
+  inputSchema.fields[] {name, required, type, description},
+  inputSchema.jsonSchema, outputSchema, pricing {displayText, unit,
+  creditsPerUnit, usdPerUnit}, billingSource, connected, credentialStatus,
+  guidance (usage notes for the provider and the tool), examples[] (an
+  illustrative input and response, not an observed one), usageGuidance,
+  extractors (list paths for row-shaped output).
+Cost:
+  Free.
+Avoid:
+  Do not guess field names from the tool id; read inputSchema.fields.
+  The declared output shape and getters are the contract, and a tool can
+  return something else at runtime: a declared getter that is missing, or a
+  full list where one value is declared. Run one row and read what it
+  returned before building a play column on a getter.
+  A field with no declared getter is read from toolResponse.rawV2, with the
+  provider's nesting kept: .data and .data.data are different. A shape you
+  did not expect is a contract mismatch to fix, not a provider miss or an
+  invalid result.
+`,
+    verbose: `
+Output fields:
+  inputSchema.fields[]   the flat list to build --input from. required true
+                         fields must be present; type is string, integer,
+                         boolean, object, or array.
+  inputSchema.jsonSchema the full JSON Schema when a field is an object, for
+                         example provider filter objects.
+  pricing.displayText    human price, for example "0.15 Deepline credits /
+                         $0.015 per result".
+  pricing.unit           what one price unit is: result, call, row, credit.
+  connected              false means the provider needs a connected account or
+                         key in this workspace; execute will fail with 3.
+  credentialStatus       detail for connected false.
+  extractors / targetGetters  JSON paths the CLI uses to turn the raw provider
+                         response into rows; the same paths appear in tools
+                         execute output as output_preview.listSourcePath.
+  usageGuidance          provider-specific notes worth reading once.
+Related:
+  tools execute <id> --input @file.json uses the same schema; runtime output
+  help for authoring a play appears under runtimeOutputHelp.
+`
+  },
+  "tools execute": {
+    core: `
+Purpose:
+  Run one provider tool with a JSON input and print its result.
+When:
+  One-off lookups, searches that return candidates, or when no play covers the
+  job. Use a play for a CSV of rows.
+Input:
+  Positional tool id, then the parameters in exactly one of these forms:
+    --input '{"email":"a@b.com"}'      inline JSON object
+    --input @input.json                 read the JSON object from a file
+    -p email=a@b.com                    one key=value per -p, repeatable
+  --payload is an alias of --input. There is no --payload-file flag; use
+  @path. --out <file.csv> writes row-shaped output to a CSV file.
+Output (JSON):
+  job_id, status ("completed" or a failure status), toolResponse.rawV2 (the
+  complete provider result), output_preview {kind, rowCount, columns, preview,
+  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
+  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
+  failed call prints its error as JSON on stdout.
+`,
+    verbose: `
+Input rules:
+  The object must match inputSchema.fields from tools 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.
+Output fields:
+  toolResponse.rawV2     the complete provider response with its nesting
+                         kept; toolResponse.raw is the older field beside it.
+  output_preview.kind    "list" when the CLI found a row array; "value"
+                         otherwise.
+  output_preview.listSourcePath  the JSON path of that array inside
+                         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.
+Cases:
+  Insufficient credits fail before the provider is called, with an
+  insufficient-credits error; check the preflight balance first.
+  A provider that needs a connected account fails with an auth or permission
+  error; tools 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
+  prebuilt play (search), or write one (plays --help).
+`
+  },
+  plays: {
+    core: `
+Purpose:
+  Durable workflows. Prebuilt plays are Deepline-maintained waterfalls such as
+  name-and-domain-to-email, person-linkedin-to-email, person-to-phone, and
+  company search, each with a single-row and a -batch (CSV) variant. A play
+  you write is one TypeScript file.
+When:
+  Any job with rows, or any job that chains providers. A play reuses finished
+  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
+  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
+Writing a play:
+  Start from code that already works, not a blank file.
+  plays get prebuilt/<name> --source --out my.play.ts
+                                copy the closest prebuilt and edit the copy
+  plays check my.play.ts        validate after every edit; free
+  plays run my.play.ts --input '{...}'           run the local file
+  plays publish my.play.ts      make it live for plays run <name> and triggers
+  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 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>)
+  plays check <file>            deprecated or invalid usage, one hint per
+                                issue; read-only and free
+  plays triggers                every cron and webhook trigger
+Cost:
+  search, describe, list, check, and get are free; run spends credits.
+`,
+    verbose: `
+Authoring rules:
+  Reach the outside world only through ctx: ctx.csv, ctx.dataset,
+    ctx.tools.execute, ctx.runPlay, ctx.step, ctx.fetch, ctx.secrets,
+    ctx.customerDb, and ctx.log. No fs, raw fetch, or shell commands, also not
+    inside ctx.step. Local nondeterministic work such as Date.now or
+    Math.random goes inside ctx.step.
+  A run can be interrupted and replayed from the top; every finished step
+    and tool call then returns its saved result. So the play name, each
+    ctx.dataset key, ctx.step id, ctx.fetch key, and ctx.tools.execute id is
+    a fixed string literal, and renaming one pays for that work again.
+  Rows: ctx.dataset('key', rows).withColumn('name', (row, rowCtx) => ...)
+    .run({ key: 'domain' }). Use a business identifier as the row key. Put
+    one paid call in a column, and shaping, status, and miss_reason in
+    separate plain columns after it. Return the dataset for anything that
+    should export as CSV.
+  Dataset handles are async: await rows.count(), rows.first(),
+    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:
+    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.
+    staleAfterSeconds on the call sets how fresh a saved result must be.
+  Reuse before rebuilding: ctx.runPlay('prebuilt/<name>', input) runs a
+    prebuilt as one stage. Independent calls run together with Promise.all;
+    a call that needs another's result waits for it.
+  Failures: catch only ProviderTransientError, and only when another
+    provider can answer the same question. Keep the last provider outside
+    the catch so an exhausted waterfall fails loudly. Never branch on an
+    error message.
+  External APIs: ctx.fetch with a fixed key, and credentials through
+    ctx.secrets.bearer(...) or ctx.secrets.header(...), stored with deepline
+    secrets set. res.json is a property, not a method; check res.ok. A play
+    cannot loop ctx.fetch over pages: fan out over rows with ctx.dataset, or
+    call one endpoint that returns the whole result.
+  Triggers: a cron trigger receives {} unless its binding declares an input
+    object, written inline and pinned with the published revision.
+  Runtime: The default Play runtime is 30 minutes. For a bounded long batch
+    set the play option runtime: { timeout: '90m', size: 'standard' }, up to
+    4h. That is not the CLI wait timeout.
+  Recurring sourcing: .run({ key: 'domain', mode: 'net_new' }) returns only
+    rows the table has not seen before.
+  Results: project each answer into flat columns (the value, its source,
+    whether it was validated, the outcome, the reason) and keep evidence
+    under _dl_meta, including result._metadata.execution.receiptKey. Unknown
+    stays null, not false.
+  Diagram: a /** @mermaid <name> */ block above the play draws it in the
+    dashboard, with // @mermaid-node <id> out:"<identifier>" above the
+    statement each box stands for. plays check validates it.
+`
+  },
+  "plays grep": {
+    core: `
+Purpose:
+  Full-text search over plays this workspace authored (not prebuilt ones).
+When:
+  Finding a saved play by a phrase in its source or description.
+Input:
+  A query. --json forces JSON.
+Output (JSON):
+  Matching owned plays with the matched fields and terms.
+Cost:
+  Free.
+`
+  },
+  "plays list": {
+    core: `
+Purpose:
+  Inventory of saved and prebuilt plays, one bounded page at a time. It is
+  the command that carries cost estimates.
+When:
+  To price a play before running it: plays list --show-cost, then read the
+  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.
+Output (JSON):
+  plays[] with playKey, reference, displayName, description, origin,
+  runCount, lastRun, and with --show-cost costEstimate {status, unit ("row"
+  or "run"), lowCredits, highCredits, source, sampleRunCount} or
+  {status: "unavailable", reason, message}; count, has_more, next_cursor,
+  next (the next-page command), render.sections with a "cost estimate:"
+  line per play.
+Cost:
+  Free.
+Avoid:
+  plays 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
+  read its actual spend with billing usage --run-id <run-id>.
+Output fields:
+  costEstimate.source      "observed" (from past runs; shown with ~) or
+                           "static" (from the play's declared tools).
+  costEstimate.sampleRunCount  how many runs the observation is based on.
+  has_more / next_cursor   the page is bounded; pass --cursor to continue.
+  is_truncated             true when the page was cut for size.
+`
+  },
+  "plays describe": {
+    core: `
+Purpose:
+  The contract for one play: required input, CSV column expectations, output
+  fields, and the exact run command.
+When:
+  Always before the first run of a play. It is free and it is the only
+  reliable source of the input field and column names.
+Input:
+  The play reference from search (prebuilt/... or <workspace>/...).
+  --compact shortens schemas. --json forces JSON.
+Output (JSON):
+  name, reference, displayName, description, inputSchema (JSON Schema plus
+  fields[] {name, required, type}), outputSchema, csvInput {inputField,
+  rowInputSchema.required[], defaultColumns, columnFlags}, rowOutputSchema,
+  runCommand, examples, triggerStatus, latestRunId.
+  No cost estimate; use plays list --show-cost for that.
+Cost:
+  Free.
+Avoid:
+  Do not pass --show-cost here; it is not an option of this command.
+`,
+    verbose: `
+CSV plays:
+  csvInput.inputField is the input key that takes the CSV path (usually
+  "csv"), so the run input is {"csv":"path.csv"}. rowInputSchema.required
+  lists the per-row fields the play needs (for example first_name,
+  last_name, domain). defaultColumns maps each field to the header name the
+  play looks for (FIRST_NAME, LAST_NAME, COMPANY_DOMAIN). When your file uses
+  other headers, either rename them or pass the columnFlags, for example
+  --columns.domain website. The run fails at validation, before any credit
+  is spent, when a required column is missing.
+Output fields:
+  inputSchema.fields[]    flat list for a single-row play; build --input
+                          from it.
+  outputSchema.properties the per-row result fields, for example email,
+                          email_source, email_validated, waterfall_attempts.
+  runCommand              copy it and replace the placeholder input.
+  latestRunId             the most recent run in this workspace, if any;
+                          useful to reuse a finished result instead of
+                          rerunning.
+  triggerStatus           cron or webhook triggers configured for the play.
+Related:
+  plays get <ref> returns full metadata, revisions, and source; describe is
+  the compact read meant for running.
+`
+  },
+  "plays get": {
+    core: `
+Purpose:
+  Full metadata for a play: revisions, source, triggers, and latest runs.
+When:
+  Only when describe is not enough: reading the source (--source --out
+  file.play.ts), checking revisions, or auditing a saved play.
+Input:
+  The play reference. --source prints or writes the source; --working,
+  --live, --revision <n> pick which source.
+Output (JSON):
+  The play record with revision and trigger metadata; with --source, the
+  TypeScript source.
+Cost:
+  Free.
+`
+  },
+  "plays check": {
+    core: `
+Purpose:
+  Validate a play contract without starting a run: a local .play.ts file is
+  bundled and checked, a named or prebuilt play is confirmed discoverable.
+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.
+Output (JSON):
+  valid (boolean), target, name, reference, inputSchema, outputSchema,
+  runtimeLimit, note, and for local files any errors or warnings with the
+  repair steps.
+Cost:
+  Free.
+Avoid:
+  valid true does not mean the input you plan to pass is valid; describe
+  shows the required fields.
+`
+  },
+  "plays run": {
+    core: `
+Purpose:
+  Start one run of a play, wait for it, and print the result package with
+  the run id.
+When:
+  After describe. A CSV goes through the play's batch form
+  (prebuilt/<name>-batch) in one run; the single-record form is for one
+  person or company. Pilot a slice first when the estimate times the row
+  count is a large share of the balance; an input of about 25 rows or fewer
+  is its own pilot.
+Input:
+  Positional: a play reference (prebuilt/... or <workspace>/...) or a local
+  .play.ts path. A path runs that file as written and never publishes it; a
+  name runs the live version, which only plays set-live changes. Then the
+  play input in exactly one of these forms:
+    --input '{"csv":"leads.csv"}'   inline JSON object (CSV plays take the path)
+    --input @input.json             read the object from a file
+    --key value                     any unknown flag becomes input.key
+  --columns.<field> <header> maps a CSV header to a required field.
+  --no-wait returns the run id immediately instead of waiting.
+  --run-id-file <path> writes the run id as soon as the server accepts it.
+Output (JSON, printed when the run ends):
+  run {id, playName, status ("completed", "failed", "stopped")},
+  dashboardUrl, steps[] with per-step progress, rowOutcomes, warnings,
+  datasets[] {datasetId, name, storage {schema, table}}, and actions holding
+  exact follow-up commands: getRunCmd, getFullRunCmd, getBillingCmd,
+  getLogsCmd, exportDatasetCmds[], queryTableSqlCmds[]. Rows are not in this
+  payload. Progress lines are printed while it waits; the JSON is the last
+  thing printed.
+Cost:
+  Spends Deepline credits through the play's tool calls. Validation errors
+  (missing column, bad input) fail before any spend.
+Avoid:
+  Do not run the single-record play once per row of a file; each run pays
+  its own start-up and balance admission, and the batch form keeps a
+  row-level failure inside one completed run.
+  Do not poll runs get while plays run is still waiting; it already waits.
+  Do not rerun a failed run from scratch; the same command reuses completed
+  rows.
+`,
+    verbose: `
+Waiting and timeouts:
+  The command watches the run until it ends. Prefixed activity lines report
+  queueing and per-step progress; if the tool shell has an execution
+  timeout shorter than the run, start with --no-wait or --run-id-file and
+  poll with runs get <run-id> until run.status is terminal.
+Input rules:
+  A CSV path is relative to the current directory; the CLI uploads the file
+  before submitting, so the run does not depend on the file afterwards.
+  Header matching is case-insensitive against csvInput.defaultColumns from
+  describe; other headers need --columns.<field> <header>.
+  --limit 5 and similar pass-through flags become input.limit = 5.
+Output fields:
+  run.status              the run's terminal state. "failed" with row-level
+                          failures still keeps the succeeded rows; read
+                          rowOutcomes and warnings.
+  steps[].progress        {total, executed, reused, failed, completedRows}
+                          per dataset step. reused counts rows recovered from
+                          an earlier run.
+  datasets[].storage      {schema, table}: where the rows live in the
+                          customer database. Row counts and fill statistics
+                          are in runs get, not here.
+  actions.exportDatasetCmds[]  the exact runs export line for each dataset.
+  actions.getBillingCmd   the exact cost read for this run.
+  error                   present on failure; insufficient-credits errors
+                          name the missing amount.
+Reruns and idempotency:
+  Running the same play with the same input reuses completed provider calls
+  and rows, so rerunning after a partial failure only pays for the missing
+  work. --force starts a fresh run graph; --force-tool-refresh repeats
+  billed provider calls and is almost never what you want.
+Related:
+  runs get <run-id> for status later; runs export for rows; runs logs for
+  persisted logs; billing usage --run-id for cost.
+`
+  },
+  "plays set-live": {
+    core: `
+Purpose:
+  Make one version of a play live, so plays run <name>, triggers, and
+  ctx.runPlay callers use it. A local .play.ts file is bundled, validated,
+  saved as a revision, and promoted in one step; a saved play promotes one
+  of its existing revisions.
+When:
+  After iterating on a local file with plays run ./file.play.ts, once its
+  result is right. Running a local file never publishes it.
+Input:
+  A local path ending in .play.ts, or a saved play name with --latest or
+  --revision-id <id>. --dry-run bundles and prints the planned artifact
+  without publishing. --expected-artifact <hash> refuses to publish when the
+  file no longer produces the artifact hash plays check printed.
+Output (JSON):
+  success, name, liveVersion, revisionId, artifactHash, previousLiveVersion,
+  previousArtifactHash, and the trigger metadata and bindings now live.
+Cost:
+  Free. It changes cloud state: every caller of the play name gets the new
+  version at once.
+Avoid:
+  Do not publish to test a change; run the file by path instead.
+  A cron or webhook trigger cannot report its own failure. After publishing
+  a triggered play, check that a failure notifies someone: notifications
+  --help.
+`
+  },
+  "plays publish": {
+    core: `
+Purpose:
+  Publish a local .play.ts file or promote a saved revision, so plays run
+  <name>, triggers, and ctx.runPlay callers use it. The same operation as
+  plays set-live.
+When:
+  Once a play run by file path gives the right result. Running a local file
+  never publishes it.
+Input:
+  A local path ending in .play.ts, or a saved play name with --latest or
+  --revision-id <id>. --dry-run bundles and prints the planned artifact
+  without publishing. --expected-artifact <hash> refuses to publish when the
+  file no longer produces the artifact hash plays check printed.
+Output (JSON):
+  success, name, liveVersion, revisionId, artifactHash, and the trigger
+  metadata and bindings now live.
+Cost:
+  Free. It changes cloud state: every caller of the play name gets the new
+  version at once.
+Avoid:
+  A cron or webhook trigger cannot report its own failure. After publishing
+  a triggered play, check that a failure notifies someone: notifications
+  --help.
+`
+  },
+  runs: {
+    core: `
+Purpose:
+  Everything about executions of plays: current status, row outcomes, logs,
+  cost, export, and cancellation.
+Which command:
+  runs get <run-id>        status, step progress, dataset handles, next steps
+  runs export <run-id> --out f.csv   the result rows as CSV
+  billing usage --run-id <run-id>    what the run cost
+  runs list --play <ref>   recent runs of a play with status and credits
+  runs logs <run-id>       persisted logs; --failed for the failure window
+  runs watch <run-id>      follow an active run until it ends
+  runs stop <run-id>       cancel; runs stop-all cancels every active run
+Ids:
+  play/<play-ref>/run/<timestamp>-<suffix>, printed by plays run as runId.
+Cost:
+  All of these are free; a run's spend was charged while it ran.
+`
+  },
+  "runs get": {
+    core: `
+Purpose:
+  Current status and structure of one run: state, per-step progress, row
+  counts, dataset handles, and exact follow-up commands.
+When:
+  To check a run started with --no-wait, to find the dataset table name for
+  db query, or to see row-level failure counts. Not for cost and not for
+  rows.
+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.
+Output (JSON):
+  kind "run_overview", run {id, playName, status, startedAt, finishedAt,
+  durationMs}, steps[] {id, kind, status, label, progress {total, executed,
+  reused, failed, completedRows}}, failures.steps[], errorDetails,
+  rowOutcomes, warnings[], datasets[] {datasetId, name, rowCount, summary,
+  storage {schema, table}, preview {returnedRows, totalRows, partial, rows}},
+  result or resultState, and actions holding exact follow-up commands
+  (getFullRunCmd, getBillingCmd, getLogsCmd, exportDatasetCmds[],
+  queryTableSqlCmds[]). A batch run's payload is tens of kilobytes; read
+  run.status and datasets[] and take rows and cost from the narrower
+  commands.
+Cost:
+  Free.
+Avoid:
+  Cost is not in this payload without --full; use billing usage --run-id.
+  datasets[].preview.rows is a sample, not the rows; use runs export or db
+  query.
+`,
+    verbose: `
+Output fields:
+  run.status            queued, running, completed, failed, or stopped. Only
+                        the last three are terminal.
+  run.activity          the current step while running, null when finished.
+  steps[].label         the step's state in one line, as the dashboard shows
+                        it.
+  datasets[].summary.reportedPopulation  {totalRows, persistedRows,
+                        succeededRows, failedRows}. failedRows > 0 means some
+                        rows have no result; export them and read the
+                        failure columns before reporting.
+  datasets[].summary.columnStats  per-column fill and unique counts; a quick
+                        fill-rate read without exporting.
+  datasets[].storage    {schema, table}: the customer-database table holding
+                        the rows; actions.queryTableSqlCmds[] has a ready db
+                        query for it.
+  datasets[].preview    {returnedRows, totalRows, partial, rows}: a sample
+                        for a first look, never an export count.
+  resultState           "available_in_full" means the result was left out;
+                        --full resolves it.
+  rowOutcomes           terminal row accounting: successes, failures and
+                        superseded rows are disjoint, and a superseded row
+                        belongs to a newer write's latest view. Absent while
+                        the run is active. A completed status alone does not
+                        mean every input row produced a successful row.
+  actions.*Cmd          exact commands: exportDatasetCmds[], getBillingCmd,
+                        queryTableSqlCmds[], getLogsCmd, and stopRunCmd while
+                        the run is active.
+With --full:
+  diagnostics holds the raw status: billing, timeline, errors, child runs.
+  --json diagnostics needs --full. Use --full only when a program will read
+  it; it is several times larger than the default overview.
+Debugging a run:
+  When a run failed or looks stuck, read runs get <run-id> for its state and
+  last event, then runs logs <run-id> --failed for the failure window, then
+  runs watch <run-id> to follow it if it is still active. A run can go quiet
+  for minutes while it waits on a slow provider (Apify actors, large company
+  searches), an intentional ctx.sleep, or a rate-limit backoff; that is
+  healthy. Stop it only after about ten minutes without progress on a fast
+  tool.
+`
+  },
+  "runs export": {
+    core: `
+Purpose:
+  Write a run's result rows to a local CSV file.
+When:
+  After a run completes, as the way to get rows. It is also the file to
+  show a user.
+Input:
+  The run id and --out <path> (required). --format json writes an array of
+  rows instead of CSV. --dataset <path> selects a handle when the run
+  returned more than one (default: the returned dataset, usually
+  result.rows). --metadata-out <path.json> writes the export metadata. --json
+  prints the receipt as JSON; it does not change the file format.
+Output (JSON):
+  csv_path or json_path (absolute), source, rowCount, columns[] (the CSV
+  header), datasets, and actions with follow-up commands. The file includes
+  the input columns
+  plus the play's output fields (for example email, email_source,
+  email_validated, waterfall_attempts) and per-provider attempt columns.
+Cost:
+  Free.
+Avoid:
+  Do not reconstruct rows from runs get; export is complete and cheap.
+`,
+    verbose: `
+Cases:
+  Right after a run finishes, export can report that the backing dataset was
+  not ready to export yet and print the command to retry. Run that command
+  again, or read the rows with db query meanwhile; never rerun the play, the
+  rows are already paid for.
+  A run with failed rows exports them too; the output fields for those rows
+  are blank and the attempt columns explain why. Report them as unresolved
+  rather than dropping them.
+  A run that returned no dataset (a single-value play) has nothing to export;
+  the result is in runs get under outputs or result.
+  --dataset accepts a dataset path such as result.rows; runs get
+  actions.exportDatasetCmds[] has the exact line for each dataset.
+Output fields:
+  columns[]         the exact header order written; use it to pick columns to
+                    show.
+  rowCount          rows written, including failed rows.
+  local.csv_path    same as csv_path; present for tooling.
+`
+  },
+  "runs list": {
+    core: `
+Purpose:
+  Recent runs of a play, or all runs in a status, with per-run credits.
+When:
+  To find a previous run id, to check whether a play already ran on the same
+  input, or to read per-run spend across several runs.
+Input:
+  --play <ref> and/or --status <queued|running|completed|failed|stopped>
+  (at least one). --limit, --offset (with --play), --compact, --json.
+Output (JSON):
+  runs[] {id, status, playName, createdAtIso, startedAtIso, finishedAtIso,
+  billingTotalCredits}, count, total, has_more, next, render.sections (one
+  line per run: id, status, start time, credits).
+Cost:
+  Free.
+Avoid:
+  runs[].id is the public run id that runs get, watch, export and stop
+  accept. runId and workflowId are older names for it; temporalRunId is a
+  backend identifier and not a run id. Use the id plays run returned for
+  your own run: the latest entry here may belong to another invocation that
+  started at the same time.
+`
+  },
+  "runs logs": {
+    core: `
+Purpose:
+  The stored text logs of one run, or a search of recent events across the
+  workspace's runs. Nothing runs again.
+When:
+  When a run failed and the runs get error is not enough: runs logs
+  <run-id> --failed shows the failure window; --out <path> saves the whole
+  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
+  with --where.
+Input:
+  A run id alone reads text logs; no run id, or any search flag, searches
+  events. The flags, event kinds, and --where filter examples are listed
+  above.
+Output:
+  Log lines (human) or a JSON envelope; with --out, the file path. Follow
+  next.logs for the next page of events, and pass nextCursor to --cursor for
+  older text logs.
+Cost:
+  Free.
+Avoid:
+  --out, --failed and --log-level apply to text logs and cannot be combined
+  with an event search. --where is not SQL: it takes equality tests joined
+  with &&.
+`
+  },
+  "runs receipt": {
+    core: `
+Purpose:
+  Read the tool responses a run retained, by receipt key. Nothing runs again
+  and nothing is billed.
+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.
+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
+  file and does not overwrite. The key is the row's
+  _metadata.execution.receiptKey, not a call-site id or a job id; read the
+  row's actual schema before extracting keys.
+Output (JSON):
+  One outcome per key, in the order asked, duplicates kept. A successful
+  entry holds result.toolResponse; an error stays with its key.
+Cost:
+  Free.
+Avoid:
+  Exit 4 means a key was not found; exit 5 means a result is incomplete or
+  unavailable, with the successful entries still returned. Reads need the
+  workspace the run belongs to.
+`
+  },
+  "runs watch": {
+    core: `
+Purpose:
+  Follow an active run until it ends, polling its status every two seconds.
+When:
+  Only for a run started with --no-wait that you want to watch. plays run
+  already waits, and runs get answers "is it done". runs tail is an alias.
+Input:
+  The run id. --compact shows step transitions only; --json prints one
+  terminal package at the end; --jsonl prints events as JSON Lines.
+Output:
+  Progress lines as the run changes, then the same package shape as runs get
+  --json.
+Cost:
+  Free.
+`
+  },
+  "runs stop": {
+    core: `
+Purpose:
+  Request cancellation of one active run.
+When:
+  A run is stuck, was started by mistake, or was superseded. Runs of the same
+  play do not cancel each other: an older run keeps working and keeps
+  spending until it ends or is stopped. runs list --play <name> --status
+  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.
+Output (JSON):
+  The run's new status; cancellation is asynchronous, so poll runs get.
+Cost:
+  Free, but rows already processed were charged.
+`
+  },
+  "runs stop-all": {
+    core: `
+Purpose:
+  Request cancellation of every active run in the workspace.
+When:
+  Unjamming a workspace. Do not use it to stop one run; use runs stop.
+Input:
+  --reason "<text>". --dry-run lists what would be stopped. --json.
+Output (JSON):
+  The runs that were asked to stop.
+Cost:
+  Free.
+`
+  },
+  "runs rerun": {
+    core: `
+Purpose:
+  Start a new run of the same play with the same input as an earlier run,
+  reusing its completed rows.
+When:
+  After fixing the cause of a partial failure. When a failed run is
+  resumable, runs get also prints the exact command under actions.rerunCmd.
+Input:
+  The run id. --json.
+Output (JSON):
+  The new run's package, as plays run prints.
+Cost:
+  Spends credits only for rows that were not completed before.
+`
+  },
+  notifications: {
+    core: `
+Purpose:
+  Named notifications. Each one sends the play events you choose to a
+  connected target, such as a Slack channel or an email address.
+When:
+  After publishing a play that runs on a cron or webhook trigger. A trigger
+  cannot report its own failure, so check that a failed run reaches someone.
+Input:
+  notifications list            what exists; read it before editing a rule
+  notifications events          the play events a notification can receive;
+                                do not guess event ids
+  notifications slack channels --search <words>
+                                find a channel in the connected Slack
+  notifications add <name> --to slack:#channel --for play.cron.failed
+  notifications test <name>     send a test message
+Output:
+  The named notifications with their targets and events; add and test
+  confirm what changed or was sent.
+Cost:
+  Free.
+Avoid:
+  Reading the configuration needs no approval. Adding a rule or sending a
+  test changes something outside the run, so get the user's go-ahead first.
+  Slack itself is connected in Dashboard -> Integrations, not here.
+  Delivery retries are handled internally and are not configurable.
+`
+  },
+  "csv show": {
+    core: `
+Purpose:
+  Inspect a local CSV before running a play over it: headers, fill rates,
+  sample values, or a row range.
+When:
+  Before plays run, to confirm the file has the columns describe requires
+  and to count rows for pricing. Free and local.
+Input:
+  <path> (required). --summary prints stats instead of rows. --rows
+  start:end (inclusive, default 0:19), --columns a,b, --format json|csv|table.
+Output (JSON):
+  With --summary: total_rows and rows, one per column: {column, present,
+  missing, present_percent, unique, top_values, other_count}. Without it:
+  the rows in the requested range.
+Cost:
+  Free. No network.
+Avoid:
+  Do not use head or wc to inspect a CSV that a play will consume; --summary
+  gives the row count and column names in one call.
+`
+  },
+  "db query": {
+    core: `
+Purpose:
+  Run SQL against the workspace's customer database, where play runs persist
+  their result rows.
+When:
+  To read result rows in place (filter, join, count) instead of exporting,
+  or to write to your own storage.* tables.
+Input:
+  --sql "<statement>" or --sql @file.sql (required). --max-rows <n>,
+  --format table|json|csv|markdown, --out <path> for csv or markdown, --json.
+  Table names come from runs get: datasets[].storage {schema, table}, for
+  example "storage"."prebuilt_person_to_phone_batch_phone_rows"; quote both
+  parts. actions.queryTableSqlCmds[] has a ready query for each dataset.
+Output (JSON):
+  command ("SELECT" and so on), rows[] (one object per row), columns[]
+  {name}, row_count, row_count_returned, truncated (true when --max-rows or
+  the server bound cut the result), next.
+Cost:
+  Free.
+Avoid:
+  Do not guess table names; a run's dataset table is named in runs get
+  under datasets[].storage.
+`
+  },
+  "sessions send": {
+    core: `
+Purpose:
+  Upload an agent session transcript, or a file, to Deepline so the team can
+  see how a task went.
+When:
+  Only after the user agrees. Ask once, at the end of the task and in its own
+  message. After a user-requested feedback report, offer it alongside. When
+  the upload succeeds, tell the user: "Session sent to Deepline. Rating:
+  <rating>".
+Input:
+  --current-session (the calling agent's session, else the newest one started
+  in this directory), or --session-id <uuid> (repeatable, each with an
+  optional --label), or --file <path> for a raw file. --agent
+  auto|claude|codex limits where transcripts are looked for.
+  --rating good|poor|neutral, judged by outcome and not tone: good when the
+  user's goal was met without product problems; poor when it was missed, or
+  a product failure, bug, or avoidable friction (including a substantial
+  workaround) got in the way; neutral when partly met or unclear. A session
+  that produced a feedback report is usually poor or neutral. --json.
+Output (JSON):
+  A confirmation envelope with uploaded and session_ids; the text form names
+  the session that was uploaded.
+Cost:
+  Free.
+Avoid:
+  The command is sessions, plural; the singular session form is the old one.
+  In a Cowork sandbox the transcripts are mounted under
+  ~/mnt/.claude/projects: when no session files are found and that directory
+  exists, link it to ~/.claude/projects and retry, or pass the newest
+  transcript there with --file.
+`
+  },
+  "feedback send": {
+    core: `
+Purpose:
+  Send a bug report or product feedback to the Deepline team. The calling
+  agent's session id is attached, so a report can be matched to a transcript.
+When:
+  The user asks to report something: confirm the text with them first, pass
+  --requested, and offer to share the session with sessions send.
+  Unasked, when you see friction Deepline could act on, unless the user
+  restricts external reporting: a play far slower than its input size,
+  earlier comparable runs, or visible progress would suggest, or one that
+  looks stuck; or an ordinary result that took avoidable discovery,
+  conversion, id extraction, retries, exports, or a manual workaround. Send
+  one concise report per issue, without --requested and without a
+  transcript, then keep working on the task. Provider work that is
+  legitimately long is not friction.
+Input:
+  Positional text or --file <path> (- for stdin). --command "<the command
+  that reproduced it>" and --payload <json or text> attach a repro.
+  --error-outcome terminal when an error stopped the task, continued when
+  work went on, including through a workaround; omit it when no error
+  occurred. --requested only when the user asked for the report. --json.
+  Put the evidence in the text. A slow run: the goal, the play and run id,
+  input size, observed duration, status changes or polling count, and what
+  you expected. Extra steps: the goal, the command path you took, the
+  detours, and the direct path you expected.
+Output (JSON):
+  A confirmation envelope for the report.
+Cost:
+  Free. A report does not authorize a paid reproduction or a session upload.
+`
+  },
+  skills: {
+    core: `
+Purpose:
+  Reinstall the Deepline agent skill files (deepline-gtm and its siblings)
+  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.
+Input:
+  --scope global|local, --agent <target>, --dry-run, --json.
+Output (JSON):
+  The install plan (dry run) or the result envelope listing written and
+  removed skill directories.
+Cost:
+  Free.
+Avoid:
+  The bare command replaces skill files; in a sandbox or a task that said
+  not to change skills, use --dry-run.
+`
+  },
+  update: {
+    core: `
+Purpose:
+  Update the Deepline CLI to the latest release.
+When:
+  When a command reports the CLI is too old for a feature. Ordinary commands
+  auto-update in the background unless DEEPLINE_SKIP_SELF_UPDATE=1 is set or
+  settings autoupdate off was run.
+Input:
+  No arguments. --json.
+Output:
+  The installed and new versions.
+Cost:
+  Free.
+`
+  },
+  doctor: {
+    core: `
+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 any check fails, which is common in sandboxes with no skills on disk.
+Input:
+  --scope global|local. --json.
+Output (JSON):
+  Check results with status and repair hints. Exit 7 means at least one
+  check failed; the JSON says which.
+Cost:
+  Free.
+`
+  },
+  setup: {
+    core: `
+Purpose:
+  Interactive first-run setup: authenticate, install skills, and print
+  starter prompts.
+When:
+  A person setting up a new machine. Not for unattended shells; it needs a
+  browser for auth.
+Input:
+  Flags for scope and agent target; see the options above.
+Output:
+  Progress and the starter prompts.
+Cost:
+  Free.
+`
+  },
+  version: {
+    core: `
+Purpose:
+  Print the installed CLI version.
+Output (JSON with --json):
+  {version}.
+`
+  }
+};
+function commandDocKey(command) {
+  const parts = [];
+  let current = command;
+  while (current && current.parent) {
+    parts.unshift(current.name());
+    current = current.parent;
+  }
+  return parts.join(" ");
+}
+function helpDetailFromArgv(argv) {
+  if (argv.includes("--quiet")) return "quiet";
+  if (argv.includes("--verbose")) return "verbose";
+  return "core";
+}
+function renderCommandExplanation(key, detail, options = {}) {
+  if (detail === "quiet") return "";
+  const doc = COMMAND_DOCS[key];
+  if (!doc) return "";
+  const prefix = key ? `deepline ${key}` : "deepline";
+  const sections = [doc.core.trim()];
+  if (detail === "verbose" && doc.verbose) {
+    sections.push(doc.verbose.trim());
+  }
+  const body = `
+Explanation:
+${indent(sections.join("\n\n"))}
+`;
+  if (options.pointer === false) return body;
+  const pointer = options.firstRead && doc.verbose ? `Help detail: this first read printed the full explanation; later ${prefix} --help calls in this session print the core section, --help --verbose prints the full explanation again, and --help --quiet omits it.` : detail === "verbose" || !doc.verbose ? `Help detail: ${prefix} --help --quiet omits this explanation.` : `Help detail: ${prefix} --help --verbose adds output field references and edge cases; --help --quiet omits this explanation.`;
+  return `${body}
+${pointer}
+`;
+}
+function indent(text) {
+  return text.split("\n").map((line) => line.length > 0 ? `  ${line}` : line).join("\n");
+}
+
+export {
+  COMMAND_DOCS,
+  commandDocKey,
+  helpDetailFromArgv,
+  renderCommandExplanation
+};