deepline 0.3.389 → 0.3.391

package/dist/cli/{chunk-HXENYWVS.js → chunk-4TCT77UF.js}

@@ -1,5 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/cli/command-docs.ts
 var CONVENTIONS = `
+[[cli:
 Conventions (apply to every command):
   Output mode: readable text by default. --json prints JSON. tools execute
     is the exception: it prints JSON; --output-format csv prints a readable
@@ -15,9 +16,14 @@ Conventions (apply to every command):
     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.
+]]
+[[mcp:
+Conventions (apply to every tool):
+]]
   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.
+    play/<play-ref>/run/<timestamp>-<suffix> and are printed by [[plays run]].
+[[cli:
   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.
@@ -28,27 +34,41 @@ Conventions (apply to every command):
     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: `
+[[cli:
 Make sure to run --help before running a command, you'll often find its
 behavior has some differences from your expectations!
+]]
+[[mcp:
+Read deepline_help for a tool before calling it, 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.
+           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 describe, start with
-           plays run.
+           with [[search]], read the contract with [[cli:describe]][[mcp:deepline_describe_play]], start with
+           [[plays run]].
+[[cli:
     runs   one execution of a play: status, rows, logs, cost, and export.
            Inspect with runs get, download rows with runs export.
+]]
+[[mcp:
+    runs   one execution of a play: status, rows, logs, and cost. Inspect
+           with deepline_get_run, read rows with deepline_read_play_output.
+]]
 
 The agent path for a typical task:
+[[cli:
   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 billing balance       only when you need the credit balance
@@ -59,31 +79,56 @@ The agent path for a typical task:
   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.
+]]
+[[mcp:
+  1. deepline_auth_status     the connected workspace
+  2. deepline_search with query "<input you have -> result you need>"
+                              one search over prebuilt plays, tools, your
+                              workspace's plays, and monitor types
+  3. deepline_describe_play   read required input, CSV columns, output
+  4. deepline_run_play        returns the run id; a CSV goes in input_file
+  5. deepline_read_play_output   the result rows, a page at a time
+  6. deepline_billing_usage with 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".
+  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
+[[cli:
     single-record run per row: plays run prebuilt/<play>-batch --input
     '{"csv":"leads.csv"}', then runs export <run-id> --out <path>. Work
+]]
+[[mcp:
+    single-record run per row: deepline_run_play with play
+    prebuilt/<play>-batch, the CSV rows in input_file, and inputs
+    {"csv": "<input_file.path>"}. Read the rows with
+    deepline_read_play_output. 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,
+[[cli:
     estimate its cost: the price from describe <tool> or
     plays list --show-cost, times the results or rows you will request. Take
+]]
+[[mcp:
+    estimate its cost: the price from deepline_describe_tool or
+    deepline_describe_play, 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
+    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.
 
@@ -99,6 +144,7 @@ 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.
+[[cli:
 
 Auth in non-interactive shells:
   When the Auth line of deepline --help says not connected, stop and report
@@ -109,50 +155,69 @@ 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 and read the plan.
+]]
 `
   },
   health: {
     core: `
 Purpose:
   Read-only check that the configured Deepline host answers. Needs no API
-  key; --play-runner does.
+  key[[cli:; --play-runner does]].
 When:
-  Only when a command cannot reach the server, or with --play-runner to prove
-  the whole play execution plane works.
+  Only when [[cli:a command cannot reach the server]][[mcp:a call fails]][[cli:, or with --play-runner to prove
+  the whole play execution plane works]].
+[[cli:
 Input:
   No arguments. --play-runner runs a tiny no-provider play end to end.
+]]
+[[cli:
 Output:
   Text: "<host>: <status>", then any service notice. --json: the server
   health object plus status_banner (null when there is no notice). With
   --play-runner,
   {status, playRunner: {status, check}}. An unreachable host exits nonzero
   with "Cannot reach Deepline API: <reason>".
+]]
+[[mcp:
+Output:
+  The server health object plus status_banner (null when there is no
+  notice).
+]]
 Cost:
-  Free. --play-runner uses no providers.
+  Free.[[cli: --play-runner uses no providers.]]
 Avoid:
-  Do not use health to check auth or balance; use auth status or billing
-  balance.
+  Do not use [[health]] to check auth or balance; use [[auth status]] or [[cli:billing
+  balance]][[mcp:deepline_billing_usage]].
 `
   },
   "auth status": {
     core: `
 Purpose:
-  Report which Deepline host, workspace, and user this shell is authenticated
+  Report which Deepline host, workspace, and user this [[cli:shell]][[mcp:connector]] is authenticated
   as, without changing anything.
 When:
-  When you need the workspace name or id, or to confirm auth after a 3 exit
-  code.
+  When you need the workspace name or id[[cli:, or to confirm auth after a 3 exit
+  code]].
+[[cli:
 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.
+]]
+[[cli:
 Output (JSON):
   host, hostStatus, status ("claimed" when authenticated), connected
   (boolean), workspace {id, name, slug}, user {id}, render.sections.
+]]
+[[mcp:
+Output:
+  status ("claimed" when authenticated), org_id, org_name, org_slug, user_id,
+  user_email.
+]]
 Cost:
   Free.
 Avoid:
-  connected false in an unattended shell is a stop-and-report condition, not
-  a prompt to run auth register.
+  connected false[[cli: in an unattended shell]] is a stop-and-report condition[[cli:, not
+  a prompt to run auth register]].
 `
   },
   "auth register": {
@@ -163,28 +228,32 @@ Purpose:
 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.
+[[cli:
 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
+  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.
+  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
+  After [[auth register]] returned before approval, as it does in Cowork, and a
   person is approving it in a browser.
+[[cli:
 Input:
   No arguments beyond the pending registration it finds locally.
+]]
 Output:
   The connected workspace once approved; a timeout error otherwise.
 Cost:
@@ -198,14 +267,25 @@ Purpose:
 When:
   Once at the start of a task, before the first paid call, and after a run
   reports a balance or insufficient-credits error.
+[[cli:
 Input:
   No arguments. Prints one line, "Balance: N credits". --verbose adds
   reservations and usage awaiting settlement; --json returns the full record.
+]]
+[[cli:
 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.
+]]
+[[mcp:
+Output:
+  balance {balance (Deepline credits), balance_display, rough_usd_balance,
+  balance_status}. The balance includes other activity in the workspace, so
+  a before and after difference does not isolate one call; read a run's
+  spend with deepline_billing_usage with run_id.
+]]
 Cost:
   Free.
 `
@@ -215,22 +295,34 @@ Cost:
 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.
+  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 [[cli:--full]][[mcp:full: true]].
+[[cli:
 Input:
   --run-id <run-id> scopes the spend to one play run. --limit and --cursor
   page the recent-call list. --json prints JSON.
+]]
+[[cli:
 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.
+]]
+[[mcp:
+Output:
+  usage {balance, usage {month_spent_credits, last_30_days_usage_credits,
+  temporary_hold_credits}, plan, quota, recent.entries}, and with run_id
+  usage.run {run_id, spent_credits, rough_usd_spent, event_count}, null
+  when the run has no billing events yet.
+]]
 Cost:
   Free.
 Avoid:
-  Do not grep a runs get payload for cost; use this command.
+  Do not grep a [[runs get]] payload for cost; use this command.
 `,
     verbose: `
+[[cli:
 Output fields:
   balance, balance_display, rough_usd_balance   credits available now.
   plan.usd_per_credit                            conversion used for rough USD.
@@ -244,6 +336,7 @@ Output fields:
   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.
@@ -260,6 +353,7 @@ 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.
+[[cli:
 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
@@ -268,9 +362,10 @@ Input:
   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; read that form. With
-  --json: results[] where each item has id, kind (tool, prebuilt_play,
+  [[cli: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;
   a play adds reference, inputFields, describeCommand, and runCommand. Also
@@ -279,13 +374,15 @@ Output:
 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
+  [[cli:describe]][[mcp:deepline_describe_tool or deepline_describe_play]] <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
+  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.
+[[cli:
   tools search and plays search are deprecated aliases of this command.
+]]
 `
   },
   describe: {
@@ -295,8 +392,9 @@ Purpose:
   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
+  After [[search]] and before the first run of something you have not used. You
   do not say which kind the id is.
+[[cli:
 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
@@ -306,10 +404,13 @@ Input:
   --feature <name>[=<value>] describes one.
   A play your workspace created is shown instead of a Deepline tool or
   prebuilt play of the same name; --prebuilt shows the Deepline one.
+]]
+[[cli:
 Output:
   Readable text by default; read that form. With --json:
   kind, id, displayName, description, cost, inputs[], outputs[], and
   runExamples {cli, play}, plus the kind's own fields.
+]]
 Cost:
   Free.
 `
@@ -324,12 +425,12 @@ When:
   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
-  describe <id>         required input fields, pricing, output shape
-  tools execute <id> --input '{...}'   run it
+  [[search <words>]]              ranked tools and plays for an intent
+  [[cli:describe <id>]][[mcp:deepline_describe_tool]]         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 describe <id>.
+  price is in [[cli:describe <id>]][[mcp:deepline_describe_tool]].
 `
   },
   "tools grep": {
@@ -340,11 +441,15 @@ Purpose:
 When:
   When you know a provider or field name and want every matching tool rather
   than a ranked guess. Use search for intent queries.
+[[cli:
 Input:
   A query; --mode all (default, AND), any (OR), or phrase; --categories.
+]]
+[[cli:
 Output (JSON):
   tools[] with id, provider, displayName, description, categories, and
   executeCommand.
+]]
 Cost:
   Free.
 `
@@ -354,13 +459,17 @@ Cost:
 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).
+  To see what kinds of tools exist (bare [[tools list]]) or to enumerate one
+  category without ranking ([[tools list email_finder]]).
+[[cli:
 Input:
   Optional positional category. --json prints JSON.
+]]
+[[cli:
 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.
 `
@@ -373,12 +482,15 @@ Purpose:
 When:
   Always before paying for an unfamiliar tool; the input schema is the only
   reliable source of field names.
+[[cli:
 Input:
   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. --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.
+]]
+[[cli:
 Output (JSON):
   kind, id, cost {displayText, unit, billingMode}, inputs[] {name, type,
   required, example}, outputs[] {name, type, read}, runExamples {cli, play},
@@ -389,6 +501,7 @@ Output (JSON):
   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:
@@ -403,6 +516,7 @@ Avoid:
   invalid result.
 `,
     verbose: `
+[[cli:
 Output fields:
   inputSchema.fields[]   the flat list to build --input from. required true
                          fields must be present; type is string, integer,
@@ -424,8 +538,9 @@ Output fields:
                          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
+  [[tools execute <id>]][[cli: --input @file.json]] uses the same schema; runtime output
   help for authoring a play appears under runtimeOutputHelp.
 `
   },
@@ -436,6 +551,7 @@ Purpose:
 When:
   One-off lookups, searches that return candidates, or when no play covers the
   job. Use a play for a CSV of rows.
+[[cli:
 Input:
   Positional tool id, then the parameters in exactly one of these forms:
     --input '{"email":"a@b.com"}'      inline JSON object
@@ -443,26 +559,38 @@ Input:
     -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.
+]]
+[[cli:
 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.
+]]
+[[mcp:
+Output:
+  data, the provider result, and credits_used when it is reported.
+]]
 Cost:
-  Spends Deepline credits per call at the price in describe. A search
+  Spends Deepline credits per call at the price in [[cli:describe]][[mcp:deepline_describe_tool]]. 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 [[cli:wrap the result in shell parsing]][[mcp:post-process the result]] to find rows; output_preview
+  already lists the row path and the first rows[[cli:, and --out writes the CSV]].
+[[cli:
   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: `
+[[cli:
 Input rules:
   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.
+]]
+[[cli:
 Output fields:
   toolResponse.rawV2     the complete provider response with its nesting
                          kept; toolResponse.raw is the older field beside it.
@@ -473,15 +601,16 @@ Output fields:
   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           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 billing balance first.
+  insufficient-credits error; check [[cli:billing balance]][[mcp:deepline_billing_usage]] first.
   A provider that needs a connected account fails with an auth or permission
-  error; describe shows connected false beforehand.
+  error; [[cli:describe]][[mcp:deepline_describe_tool]] 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).
+  prebuilt play ([[search]]), or write one ([[cli:plays --help]][[mcp:deepline_help with command: plays]]).
 `
   },
   plays: {
@@ -494,6 +623,7 @@ Purpose:
 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.
+[[cli:
 The sequence:
   search "<input you have -> result you need>"   find the play
   describe <ref>          required input, CSV columns, output fields
@@ -517,6 +647,30 @@ Auditing plays:
   plays check <file>            deprecated or invalid usage, one hint per
                                 issue; read-only and free
   plays triggers                every cron and webhook trigger
+]]
+[[mcp:
+The sequence:
+  deepline_search with query "<input you have -> result you need>"
+                                find the play
+  deepline_describe_play        required input, CSV columns, output fields
+  deepline_run_play             start and wait; there is no cost estimate over
+                                MCP, so price a large run with a small slice
+  deepline_read_play_output     rows
+Writing a play:
+  Send the complete .play.ts file graph inline: entrypoint plus files.
+  deepline_check_play           validate after every edit; free
+  deepline_run_inline_play      run it without publishing; CSV data files go
+                                in files, named by input_file_path
+  deepline_publish_play         make it live for deepline_run_play and triggers
+  The file is: export default definePlay('name', async (ctx, input) => {...}).
+  deepline_help with command "plays" and detail "verbose" lists the
+  authoring rules.
+Auditing plays:
+  deepline_search_plays         saved plays
+  deepline_list_play_versions   its revisions, and which one is live
+  deepline_check_play           deprecated or invalid usage, one hint per
+                                issue; read-only and free
+]]
 Cost:
   search, describe, list, check, and get are free; run spends credits.
 `,
@@ -538,9 +692,9 @@ Authoring rules:
     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.
+    handle fail [[cli:plays check]][[mcp:deepline_check_play]].
   Tool calls: rowCtx.tools.execute({ id, tool, input, description }). Read
-    results through the getters describe lists:
+    results through the getters [[cli:describe]][[mcp:deepline_describe_tool]] 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.
@@ -553,8 +707,8 @@ Authoring rules:
     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
+    ctx.secrets.bearer(...) or ctx.secrets.header(...)[[cli:, 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
@@ -570,7 +724,7 @@ Authoring rules:
     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.
+    statement each box stands for. [[cli:plays check]][[mcp:deepline_check_play]] validates it.
 `
   },
   "plays grep": {
@@ -579,10 +733,14 @@ 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.
+[[cli:
 Input:
   A query. --json prints JSON.
+]]
+[[cli:
 Output (JSON):
   Matching owned plays with the matched fields and terms.
+]]
 Cost:
   Free.
 `
@@ -590,14 +748,23 @@ Cost:
   "plays list": {
     core: `
 Purpose:
-  Inventory of saved and prebuilt plays, one bounded page at a time. It is
-  the command that carries cost estimates.
+  Inventory of saved and prebuilt plays, one bounded page at a time.[[cli: It is
+  the command that carries cost estimates.]]
 When:
+[[cli:
   To price a play before running it: plays list --show-cost, then read the
   cost estimate line for the play, or costEstimate in JSON.
+]]
+[[mcp:
+  To find a saved or prebuilt play by name. It carries no cost estimate; price
+  a play by running a small slice and reading deepline_billing_usage.
+]]
+[[cli:
 Input:
   --show-cost adds estimates. --limit and --cursor page. --categories
   filters by tool category. --json prints JSON.
+]]
+[[cli:
 Output (JSON):
   plays[] with playKey, reference, displayName, description, origin,
   runCount, lastRun, and with --show-cost costEstimate {status, unit ("row"
@@ -605,23 +772,30 @@ Output (JSON):
   {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.
+[[cli:
 Avoid:
   describe does not include a cost estimate; this command does.
+]]
 `,
     verbose: `
+[[cli:
 Pricing a run:
   Multiply lowCredits..highCredits by the row count when unit is "row", or
   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>.
+]]
+[[cli:
 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": {
@@ -632,30 +806,45 @@ Purpose:
 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.
+[[cli:
 Input:
   The play reference from search (prebuilt/... or <workspace>/...).
   --compact shortens schemas. --json prints JSON.
+]]
+[[cli:
 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.
+[[cli:
 Avoid:
   Do not pass --show-cost here; it is not an option of this command.
+]]
 `,
     verbose: `
 CSV plays:
+[[cli:
   csvInput.inputField is the input key that takes the CSV path (usually
   "csv"), so the run input is {"csv":"path.csv"}. rowInputSchema.required
+]]
+[[mcp:
+  csvInput.inputField is the input key that takes the CSV (usually "csv").
+  A play cannot read a file path from this client: send the rows as
+  deepline_run_play input_file and set that input to input_file.path.
+  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
+  other headers, either rename them[[cli: 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.
+[[cli:
 Output fields:
   inputSchema.fields[]    flat list for a single-row play; build --input
                           from it.
@@ -669,6 +858,7 @@ Output fields:
 Related:
   plays get <ref> returns full metadata, revisions, and source; describe is
   the compact read meant for running.
+]]
 `
   },
   "plays get": {
@@ -676,13 +866,15 @@ Related:
 Purpose:
   Full metadata for a play: revisions, source, triggers, and latest runs.
 When:
-  Only when describe is not enough: reading the source (--source --out
+  Only when describe is not enough: reading the source ([[--source]] [[--out]]
   file.play.ts), checking revisions, or auditing a saved play.
+[[cli:
 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
+  The play record with revision and trigger metadata; with [[--source]], the
   TypeScript source.
 Cost:
   Free.
@@ -691,21 +883,25 @@ Cost:
   "plays check": {
     core: `
 Purpose:
-  Validate a play contract without starting a run: a local .play.ts file is
+  Validate a play contract without starting a run: [[cli:a local .play.ts file]][[mcp:an inline .play.ts file graph]] 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.
+[[cli:
 Input:
   A local path ending in .play.ts, or a play reference. --json prints JSON.
+]]
+[[cli:
 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
+  valid true does not mean the input you plan to pass is valid; [[describe]]
   shows the required fields.
 `
   },
@@ -715,11 +911,13 @@ 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
+  After [[cli:describe]][[mcp:deepline_describe_play]]. 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.
+  is its own pilot.[[mcp: A play cannot read a file path from this client:
+  send a CSV's rows as input_file and set the CSV input to input_file.path.]]
+[[cli:
 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
@@ -731,6 +929,8 @@ Input:
   --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.
+]]
+[[cli:
 Output (JSON, printed when the run ends):
   run {id, playName, status ("completed", "failed", "stopped")},
   dashboardUrl, steps[] with per-step progress, rowOutcomes, warnings,
@@ -739,6 +939,16 @@ Output (JSON, printed when the run ends):
   getLogsCmd, exportDatasetCmds[], queryTableSqlCmds[]. Rows are not in this
   payload. Progress lines are printed while it waits; the JSON is the last
   thing printed.
+]]
+[[mcp:
+Output:
+  The run package deepline_get_run returns, once the run ends: run {id,
+  playName, status, dashboardUrl}, steps[] with per-step progress,
+  rowOutcomes, warnings, datasets[] {tableNamespace, sqlQualifiedTableName,
+  actions}, and next {inspect, full, billing, logs}, each naming the MCP call
+  for that follow-up. Pass a dataset's tableNamespace as table_namespace to
+  deepline_read_play_output for its rows; rows are not in this payload.
+]]
 Cost:
   Spends Deepline credits through the play's tool calls. Validation errors
   (missing column, bad input) fail before any spend.
@@ -746,22 +956,33 @@ 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 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:
+[[cli:
   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.
+]]
+[[mcp:
+  deepline_run_play waits for the run to end, up to timeout_ms (default 50000,
+  maximum 90000; stay under your client's tool-call timeout); timeout_ms: 0
+  returns once the run is admitted. A run still active then returns its
+  status; call deepline_get_run with run.id until run.status is terminal.
+]]
+[[cli:
 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.
+]]
+[[cli:
 Output fields:
   run.status              the run's terminal state. "failed" with row-level
                           failures still keeps the succeeded rows; read
@@ -776,31 +997,86 @@ Output fields:
   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.
+  work.[[cli: --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.
+  [[runs get <run-id>]] for status later; [[cli:runs export]][[mcp:deepline_read_play_output]] for rows; [[runs logs]] for
+  persisted logs; [[billing usage --run-id]] for cost.
+`
+  },
+  "plays versions": {
+    core: `
+Purpose:
+  List the saved revisions of a workspace play, newest first, and which one
+  is live.
+When:
+  Before making an older revision live or running a specific revision.
+[[cli:
+Input:
+  --name <play>. --json forces JSON.
+]]
+Output (JSON):
+  The play's revisions, each with its revision id and whether it is live.
+Cost:
+  Free.
+`
+  },
+  "plays delete": {
+    core: `
+Purpose:
+  Move a workspace play to Trash and stop its triggers. Its revisions and
+  run history are kept, so it can be restored.
+When:
+  When the user asks to remove a play. Prebuilt plays cannot be deleted.
+[[cli:
+Input:
+  The play name. --yes confirms; --dry-run shows the planned change.
+]]
+Output (JSON):
+  The deleted play and the triggers that were stopped.
+Cost:
+  Free.
+`
+  },
+  "plays restore": {
+    core: `
+Purpose:
+  Restore a play from Trash. The saved play is enabled again and its trigger
+  bindings are recreated.
+When:
+  After a play was deleted by mistake.
+[[cli:
+Input:
+  The play name. --json forces JSON.
+]]
+Output (JSON):
+  The restored play.
+Cost:
+  Free.
 `
   },
   "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,
+  Make one version of a play live, so [[plays run <name>]], triggers, and
+  ctx.runPlay callers use it.[[cli: 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.
+  of its existing revisions.]][[mcp: It promotes one of a saved play's existing
+  revisions; deepline_publish_play saves and promotes a new file graph.]]
 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.
+  After iterating on [[cli:a local file with plays run ./file.play.ts]][[mcp:a play with deepline_run_inline_play]], once its
+  result is right. Running [[cli:a local file]][[mcp:a play inline]] never publishes it.
+[[cli:
 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.
@@ -808,26 +1084,28 @@ 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.
+  Do not publish to test a change; [[cli:run the file by path]][[mcp:run it with deepline_run_inline_play]] instead.
   A cron or webhook trigger cannot report its own failure. After publishing
-  a triggered play, check that a failure notifies someone: notifications
-  --help.
+  a triggered play, check that a failure notifies someone[[cli:: 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.
+  Publish [[cli:a local .play.ts file]][[mcp:an inline .play.ts file graph]] 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
+  Once a play [[cli:run by file path]][[mcp:run inline]] gives the right result. Running [[cli:a local file]][[mcp:a play inline]]
   never publishes it.
+[[cli:
 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.
@@ -836,8 +1114,8 @@ Cost:
   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.
+  a triggered play, check that a failure notifies someone[[cli:: notifications
+  --help]].
 `
   },
   runs: {
@@ -846,6 +1124,7 @@ Purpose:
   Everything about executions of plays: current status, row outcomes, logs,
   cost, export, and cancellation.
 Which command:
+[[cli:
   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
@@ -853,8 +1132,18 @@ Which command:
   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
+]]
+[[mcp:
+  deepline_get_run              status, step progress, dataset handles, next steps
+  deepline_read_play_output     the result rows, a page at a time
+  deepline_billing_usage with run_id    what the run cost
+  deepline_list_runs            recent runs of a play with status and credits
+  deepline_get_run_logs         persisted logs
+  deepline_stop_run             cancel; deepline_stop_all_runs cancels every
+                                active run
+]]
 Ids:
-  play/<play-ref>/run/<timestamp>-<suffix>, printed by plays run as runId.
+  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.
 `
@@ -865,14 +1154,17 @@ 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
+  To check a run started with [[cli:--no-wait]][[mcp:timeout_ms: 0, or one still running when deepline_run_play returned]], to find the dataset table name for
+  [[db query]], or to see row-level failure counts. Not for cost and not for
   rows.
+[[cli:
 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
   prints JSON; --json run.status,datasets.name selects fields.
+]]
+[[cli:
 Output (JSON):
   kind "run_overview", run {id, playName, status, startedAt, finishedAt,
   durationMs}, steps[] {id, kind, status, label, progress {total, executed,
@@ -884,14 +1176,23 @@ Output (JSON):
   queryTableSqlCmds[]). A batch run's payload is tens of kilobytes; read
   run.status and datasets[] and take rows and cost from the narrower
   commands.
+]]
+[[mcp:
+Output:
+  The run package (kind "play_run"): run {id, playName, status}, steps[],
+  rowOutcomes, warnings, datasets[] {tableNamespace, sqlQualifiedTableName,
+  actions}, and next.*.command, each naming the MCP call for a follow-up.
+  With full: true the package is under package, beside the diagnostics.
+]]
 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.
+  Cost is not in this payload without [[--full]]; use [[billing usage --run-id]].
+  datasets[].preview.rows is a sample, not the rows; use [[cli:runs export]][[mcp:deepline_read_play_output]] or [[db
+  query]].
 `,
     verbose: `
+[[cli:
 Output fields:
   run.status            queued, running, completed, failed, or stopped. Only
                         the last three are terminal.
@@ -919,14 +1220,15 @@ Output fields:
   actions.*Cmd          exact commands: exportDatasetCmds[], getBillingCmd,
                         queryTableSqlCmds[], getLogsCmd, and stopRunCmd while
                         the run is active.
-With --full:
+]]
+With [[cli:--full]][[mcp:full: true]]:
   diagnostics holds the raw status: billing, timeline, errors, child runs.
-  --json diagnostics needs --full. Use --full only when a program will read
+  [[cli:--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
+  When a run failed or looks stuck, read [[runs get <run-id>]] for its state and
+  last event, then [[runs logs <run-id>]][[cli: --failed]] for the failure window, then
+  [[cli:runs watch <run-id>]][[mcp:deepline_get_run again]] 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
@@ -940,12 +1242,14 @@ Purpose:
 When:
   After a run completes, as the way to get rows. It is also the file to
   show a user.
+[[cli:
 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
@@ -984,19 +1288,23 @@ Purpose:
 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.
+[[cli:
 Input:
   --play <ref> and/or --status <queued|running|completed|failed|stopped>
   (at least one). --limit, --offset (with --play), --compact, --json.
+]]
+[[cli:
 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
+  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
+  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.
 `
@@ -1007,6 +1315,7 @@ Purpose:
   The stored text logs of one run, or a search of recent events across the
   workspace's runs. Nothing runs again.
 When:
+[[cli:
   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
@@ -1014,20 +1323,31 @@ When:
   To read what a tool call in a run returned: runs logs <run-id> --kind
   receipt.completed --payloads, then one exact result by its eventId
   with --where.
+]]
+[[mcp:
+  When a run failed and the deepline_get_run error is not enough. It returns
+  the latest log lines of one run; after_seq pages from an earlier point.
+]]
+[[cli:
 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.
+]]
+[[cli:
 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.
+[[cli:
 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": {
@@ -1039,12 +1359,14 @@ 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.
+[[cli:
 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.
@@ -1063,9 +1385,11 @@ Purpose:
 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.
+[[cli:
 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.
@@ -1080,13 +1404,15 @@ Purpose:
 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
+  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.
+[[cli:
 Input:
   The run id and --reason "<text>". --json prints JSON.
+]]
 Output (JSON):
-  The run's new status; cancellation is asynchronous, so poll runs get.
+  The run's new status; cancellation is asynchronous, so poll [[runs get]].
 Cost:
   Free, but rows already processed were charged.
 `
@@ -1096,9 +1422,11 @@ Cost:
 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.
+  Unjamming a workspace. Do not use it to stop one run; use [[runs stop]].
+[[cli:
 Input:
   --reason "<text>". --dry-run lists what would be stopped. --json.
+]]
 Output (JSON):
   The runs that were asked to stop.
 Cost:
@@ -1112,11 +1440,13 @@ Purpose:
   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.
+  resumable, [[runs get]] also prints the exact command under actions.rerunCmd.
+[[cli:
 Input:
   The run id. --json.
+]]
 Output (JSON):
-  The new run's package, as plays run prints.
+  The new run's package, as [[plays run]] prints.
 Cost:
   Spends credits only for rows that were not completed before.
 `
@@ -1129,6 +1459,7 @@ Purpose:
 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.
+[[cli:
 Input:
   notifications list            what exists; read it before editing a rule
   notifications events          the play events a notification can receive;
@@ -1137,6 +1468,7 @@ Input:
                                 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.
@@ -1155,19 +1487,21 @@ 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
+  Before [[plays run]], to confirm the file has the columns describe requires
   and to count rows for pricing. Free and local.
+[[cli:
 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,
+  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
+  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.
 `
   },
@@ -1179,20 +1513,22 @@ Purpose:
 When:
   To read result rows in place (filter, join, count) instead of exporting,
   or to write to your own storage.* tables.
+[[cli:
 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
+  {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
+  Do not guess table names; a run's dataset table is named in [[runs get]]
   under datasets[].storage.
 `
   },
@@ -1206,6 +1542,7 @@ When:
   message. After a user-requested feedback report, offer it alongside. When
   the upload succeeds, tell the user: "Session sent to Deepline. Rating:
   <rating>".
+[[cli:
 Input:
   --current-session (the calling agent's session, else the newest one started
   in this directory), or --session-id <uuid> (repeatable, each with an
@@ -1216,6 +1553,7 @@ Input:
   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.
@@ -1226,7 +1564,7 @@ Avoid:
   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.
+  transcript there with [[--file]].
 `
   },
   "feedback send": {
@@ -1236,15 +1574,16 @@ Purpose:
   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.
+  [[--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
+  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.
+[[cli:
 Input:
   Positional text or --file <path> (- for stdin). --command "<the command
   that reproduced it>" and --payload <json or text> attach a repro.
@@ -1255,6 +1594,7 @@ Input:
   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:
@@ -1269,8 +1609,10 @@ Purpose:
 When:
   Only when asked to install or update skills. To see what is installed
   without changing anything, use --dry-run and read the plan.
+[[cli:
 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.
@@ -1278,7 +1620,7 @@ Cost:
   Free.
 Avoid:
   The bare command replaces skill files; in a sandbox or a task that said
-  not to change skills, use --dry-run.
+  not to change skills, use [[--dry-run]].
 `
   },
   update: {
@@ -1289,8 +1631,10 @@ 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.
+[[cli:
 Input:
   No arguments. --json.
+]]
 Output:
   The installed and new versions.
 Cost:
@@ -1306,8 +1650,10 @@ When:
   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.
+[[cli:
 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.
@@ -1323,8 +1669,10 @@ Purpose:
 When:
   A person setting up a new machine. Not for unattended shells; it needs a
   browser for auth.
+[[cli:
 Input:
   Flags for scope and agent target; see the options above.
+]]
 Output:
   Progress and the starter prompts.
 Cost:
@@ -1359,13 +1707,10 @@ function renderCommandExplanation(key, detail, options = {}) {
   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 explanation = renderActionExplanation(key, detail, CLI_DOC_SURFACE);
   const body = `
 Explanation:
-${indent(sections.join("\n\n"))}
+${indent(explanation)}
 `;
   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.`;
@@ -1373,6 +1718,29 @@ ${indent(sections.join("\n\n"))}
 ${pointer}
 `;
 }
+var CLI_DOC_SURFACE = {
+  name: "cli",
+  reference: (reference) => reference
+};
+var SURFACE_LINES = /^\[\[(cli|mcp):\n([\s\S]*?)\n\]\](\n|$)/gm;
+var SURFACE_TEXT_OR_REFERENCE = /\[\[(?:(cli|mcp):)?([\s\S]*?)\]\]/g;
+function renderDocText(text, surface) {
+  const only = (name, body) => name === surface.name ? body : "";
+  return text.replace(
+    SURFACE_LINES,
+    (_, name, body, end) => only(name, body + end)
+  ).replace(
+    SURFACE_TEXT_OR_REFERENCE,
+    (_, name, body) => name === void 0 ? surface.reference(body) : only(name, body)
+  );
+}
+function renderActionExplanation(key, detail, surface) {
+  const doc = COMMAND_DOCS[key];
+  if (!doc) return "";
+  const sections = [doc.core.trim()];
+  if (detail === "verbose" && doc.verbose) sections.push(doc.verbose.trim());
+  return renderDocText(sections.join("\n\n"), surface);
+}
 function indent(text) {
   return text.split("\n").map((line) => line.length > 0 ? `  ${line}` : line).join("\n");
 }
@@ -1382,4 +1750,7 @@ function indent(text) {
 
 
 
-exports.COMMAND_DOCS = COMMAND_DOCS; exports.commandDocKey = commandDocKey; exports.helpDetailFromArgv = helpDetailFromArgv; exports.renderCommandExplanation = renderCommandExplanation;
+
+
+
+exports.COMMAND_DOCS = COMMAND_DOCS; exports.commandDocKey = commandDocKey; exports.helpDetailFromArgv = helpDetailFromArgv; exports.renderCommandExplanation = renderCommandExplanation; exports.CLI_DOC_SURFACE = CLI_DOC_SURFACE; exports.renderDocText = renderDocText; exports.renderActionExplanation = renderActionExplanation;