deepline 0.3.272 → 0.3.273

package/README.md

@@ -38,6 +38,15 @@ with project-local skills automatically.
 
 ## Use it with an agent
 
+For an existing run, start with `deepline runs logs --help`. It includes every
+known event kind, what records it, available fields, filters, payload reads,
+pagination and retention. `runs logs` reads text or structured events;
+`runs get`, `runs watch`, `runs export` and `runs receipt` cover status, live
+observation, dataset rows and retained tool results. These inspection commands
+read existing evidence without starting provider work. TypeScript callers use
+`client.runs.logs`, `client.runs.searchEvents` and `client.runs.getReceipts`;
+their source JSDoc and the generated SDK/API references describe the same reads.
+
 Paste this into Claude Code, Codex, or another coding agent:
 
 ```text

package/dist/bundling-sources/sdk/src/client.ts

@@ -740,25 +740,33 @@ export type RunsWatchOptions = {
 /** @deprecated Use `RunsWatchOptions`. */
 export type RunsTailOptions = RunsWatchOptions;
 
-/** Log fetch options for `client.runs.logs(...)`. */
+/** Read retained text with `client.runs.logs(...)`; use `runs.searchEvents` for structured filters and payloads. */
 export type RunsLogsOptions = {
-  /** Return the LAST `limit` stored log lines (default 200). */
+  /** Return the last `limit` retained lines in sequence order; default 200. Ignored when `all` is true. */
   limit?: number;
-  /** Fetch every stored log line, paginating to the full totalCount. */
+  /** Page through every retained line. Cannot combine with `failed`; sampling or retention loss cannot be recovered. */
   all?: boolean;
-  /** Select the bounded failure view; truncated runs degrade explicitly. */
+  /** Read a terminal-failed run's last 20 retained lines, or fewer with `limit`. Retention loss returns an explicit association and warning. */
   failed?: boolean;
 };
 
-/** Persisted log response for one play run. */
+/** Retained text for one run. Counts and retention flags describe the stored stream, not every original console call. */
 export type RunsLogsResult = {
+  /** Public run identity. */
   runId: string;
+  /** Count tracked by the log stream; may exceed available bodies after retention truncation. */
   totalCount: number;
+  /** Number of line bodies returned in `entries`. */
   returnedCount: number;
+  /** First returned stored sequence, or null for an empty view. */
   firstSequence: number | null;
+  /** Last returned stored sequence, or null for an empty view. */
   lastSequence: number | null;
+  /** Tail/all: returned count is below total count. Failed: the stream lost bodies to retention. Check `logsTruncated` to distinguish retention loss from a selected tail. */
   truncated: boolean;
+  /** More retained lines exist after `lastSequence`; always false for the designed failure window. */
   hasMore: boolean;
+  /** Formatted text lines in stored sequence order; structured context is available through event search. */
   entries: string[];
   /** Selected public log view. */
   view?: 'tail' | 'failed' | 'all';
@@ -775,53 +783,77 @@ export type RunsLogsResult = {
   logsTruncated?: boolean;
 };
 
-/** Bounded org-scoped search over durable Play runtime observations. */
+/** Read existing events in the authenticated organization/runtime scope, newest first by occurrence time and event ID. See the complete catalog and field contract in `deepline runs logs --help`. */
 export type RunsEventSearchOptions = {
   /** Inclusive UTC timestamp; defaults to one hour before the request. */
   since?: string;
-  /** Exclusive UTC timestamp; defaults to the request time. */
+  /** Exclusive UTC timestamp; defaults to the request time. A window spans at most seven days; event retention is seven days. */
   until?: string;
   /** Optional run filter. Omit to search across the active organization. */
   runId?: string;
+  /** Exact Play name; HTTP query parameter `playName`, CLI `--play`. */
   playName?: string;
+  /** Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`; future stored kinds are accepted too. */
   kind?: string;
-  /** Flat equality predicate in the supported PostgreSQL JSONPath subset. */
+  /** Equality joined with `&&`, at most eight predicates and 512 bytes. Fields: orgId, runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId, stepKind, datasetId, phase, provider, operation and scalar `context.<key>`. Missing fields do not match; status is not inferred from kind. No body, message, level, nested payload, range or OR search. HTTP `jsonpath`, CLI `--where`. */
   jsonpath?: string;
-  /** Include canonical event details and receipt-backed outputs, capped to ten events and 16 MiB total. */
+  /** Add stored canonical `eventPayload` and, for receipt matches, retained `payload`. At most ten events and 16 MiB; unavailable receipts return null. HTTP `payloads=true`, CLI `--payloads`. Does not execute tools. */
   includePayloads?: boolean;
+  /** Page size: default 100, maximum 200; with payloads, default and maximum ten. */
   limit?: number;
+  /** Opaque `nextCursor` from the preceding page. Reuse that page's returned since/until and the same filters and runtime scope. */
   cursor?: string;
   /** Explicit Preview selection requires the existing runtime credential. */
   runtime?: PlayRuntimeSelection;
 };
 
+/** One indexed observation; optional indexed fields and payloads depend on what its producer recorded. */
 export type RunsEventSearchEntry = {
+  /** Stable event identity; also breaks ties in newest-first pagination. */
   eventId: string;
+  /** Producer occurrence time as a UTC timestamp string. */
   occurredAt: string;
+  /** Index ingestion time as a UTC timestamp string; may be later than occurrence. */
   ingestedAt: string;
+  /** Public run identity associated with this observation. */
   runId: string;
+  /** Recorded Play name. */
   playName: string;
+  /** Exact indexed kind; canonical payloads use `type` for this dotted name. */
   kind: string;
+  /** Recorded log severity, or null; not a JSONPath filter field. */
   level: string | null;
+  /** Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. */
   message: string | null;
+  /** Indexed identity and recorded scalar fields. SDK/API keep this nested; CLI search flattens it onto each event. Provider/operation describe typed activity observations, not every provider call. */
   searchDoc: Record<string, unknown>;
-  /** Accepted Play event from PScale when this run uses the unified journal. */
+  /** Stored canonical event details, only when payloads are requested and available. Lifecycle/activity/dataset payloads are observations, not complete tool responses or dataset rows. */
   eventPayload?: Record<string, unknown>;
-  /** Optional full result, included only when explicitly requested. */
+  /** Retained work result for a receipt match when payloads are requested; null if unavailable. Other events need not carry this field. */
   payload?: RunsEventPayload | null;
 };
 
+/** One bounded search page. Continue using `nextCursor` and these exact time bounds; CLI-only counts and follow-up commands are not SDK/API fields. */
 export type RunsEventSearchResult = {
+  /** Matching observations in descending occurredAt/eventId order. */
   events: RunsEventSearchEntry[];
+  /** Opaque continuation token, or null when no further page exists. */
   nextCursor: string | null;
+  /** Resolved inclusive UTC bound, including a defaulted bound. */
   since: string;
+  /** Resolved exclusive UTC bound, including a defaulted bound. */
   until: string;
 };
 
+/** Retained work outcome hydrated for a receipt event; not a new execution, billing receipt or guarantee of a raw HTTP response. */
 export type RunsEventPayload = {
+  /** Recorded terminal work outcome. */
   status: 'completed' | 'failed' | 'skipped';
+  /** Stored result data, or null when no output was retained. */
   output: unknown | null;
+  /** Stored failure message, or null when absent. */
   error: string | null;
+  /** Stored structured failure details, or null when absent. */
   errorPayload: unknown | null;
 };
 
@@ -902,7 +934,7 @@ export type PlaySecretCheck = {
  * @sdkReference client 020 client.runs
  */
 export type RunsNamespace = {
-  /** Read retained tool results associated with a run, in supplied key order. Never executes tools. */
+  /** Read retained tool results in supplied key order. Use keys returned in exported evidence or execution metadata; search does not expose receipt keys. Never executes tools. */
   getReceipts: (
     runId: string,
     options: { keys: string[] },
@@ -937,9 +969,9 @@ export type RunsNamespace = {
   watch: (runId: string, options?: RunsWatchOptions) => Promise<PlayStatus>;
   /** @deprecated Use `watch`; retained as a source-compatible alias. */
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
-  /** Fetch persisted log lines for a run. */
+  /** Read a run's retained text tail, full stream (`all`) or terminal failure window (`failed`). For structured filters and payloads, see [run logs and events](run-events.md). */
   logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
-  /** Search recent durable runtime events across runs in the active organization. */
+  /** Search existing events across the active organization; default last hour, up to 200 events per page (ten with payloads). See [run logs and events](run-events.md) for the catalog, query fields and response types. */
   searchEvents: (
     options?: RunsEventSearchOptions,
   ) => Promise<RunsEventSearchResult>;
@@ -4342,7 +4374,7 @@ export class DeeplineClient {
     return { ...response, runs: response.runs ?? [] };
   }
 
-  /** Read batches rather than silently truncating a long key list. */
+  /** Read retained tool results without executing tools, preserving supplied key order and batching 100 keys per request. Obtain keys from exported evidence or execution metadata; each key must be nonempty, at most 2,048 characters and contain no CR, LF or NUL. Missing/expired results have an explicit per-key error. */
   async getRunReceipts(
     runId: string,
     options: { keys: string[] },
@@ -4426,7 +4458,7 @@ export class DeeplineClient {
   }
 
   /**
-   * Fetch persisted logs for a run using the public runs resource model.
+   * Read a run's retained text tail (default 200), full retained stream (`all`), or terminal failure window (`failed`, at most 20). These are existing reads; sampling and retention loss cannot be recovered. See [run logs and events](run-events.md) for structured search and payload retrieval.
    *
    * This is the SDK equivalent of:
    *
@@ -4525,7 +4557,7 @@ export class DeeplineClient {
     };
   }
 
-  /** Search bounded, structured runtime history without requiring a run id. */
+  /** Read structured history across the active organization without requiring a run ID. Defaults to the last hour, newest first; use the returned cursor and exact time bounds to continue. See [run logs and events](run-events.md) for all kinds, indexed fields, payloads and SDK/API response types. */
   async searchRunEvents(
     options: RunsEventSearchOptions = {},
   ): Promise<RunsEventSearchResult> {

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.272',
+  version: '0.3.273',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/runs/receipts.ts

@@ -1,23 +1,39 @@
-/** A retained result, not a new tool execution or a billing receipt. */
+/** Read-only retained tool evidence associated with a run. Each requested key returns either its stored result or an explicit error; this never executes tools or returns a billing receipt. */
 export type RunToolReceiptResult = {
+  /** Exact key supplied to the read, obtained from exported evidence or execution metadata. */
   receiptKey: string;
+  /** Recorded work status when available; an error does not imply a fresh provider failure. */
   status?: string;
 } & (
   | {
+      /** Retained result envelope; provider fields reflect stored evidence, not a guaranteed raw HTTP response. */
       result: {
+        /** Status recorded in the tool result. */
         status: string;
+        /** Provider job identity when recorded. */
         job_id?: string;
+        /** Stored tool response. */
         toolResponse: Record<string, unknown>;
+        /** Stored target values when the tool supplied them. */
         targetValues?: Record<string, unknown>;
+        /** Stored list dataset metadata when supplied. */
         listDatasets?: Record<string, unknown>;
+        /** Stored list row evidence when supplied. */
         listRows?: Record<string, unknown>;
       };
       error?: never;
     }
-  | { result?: never; error: { code: string; message: string } }
+  | {
+      result?: never;
+      /** Explicit lookup/access/retention failure for this key. */
+      error: { code: string; message: string };
+    }
 );
 
+/** Results in the exact requested key order, including errors for unavailable keys. */
 export type RunToolReceiptsResponse = {
+  /** Public run identity used to scope the read. */
   runId: string;
+  /** One result or error per requested key. */
   receipts: RunToolReceiptResult[];
 };

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -1607,13 +1607,14 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<AsyncPlayRunRef>;
 
   /**
-   * Write a customer-safe line to the durable Run Log Stream. Omitting level
-   * preserves the historical info-level behavior.
+   * Write a customer-safe retained log line, searchable as `log.appended` in the unified event journal. Default severity is info; runtime sampling and retention limits apply. Use `runs.logs` for retained text and `runs.searchEvents` for indexed context; see `deepline runs logs --help` for the complete read contract.
    */
   log(
     message: string,
     options?: {
+      /** Defaults to info. Warn/error lines are not subject to info/debug sampling. */
       level?: 'debug' | 'info' | 'warn' | 'error';
+      /** At most eight flat scalar fields and 2,048 UTF-8 bytes total. Keys match [A-Za-z_][A-Za-z0-9_]{0,63}; __proto__, constructor and prototype are forbidden. String values are at most 256 UTF-8 bytes. Search with `$.context.<key> == literal`; context cannot override run/event identity. */
       context?: Readonly<Record<string, string | number | boolean>>;
     },
   ): void;

package/dist/cli/index.js

@@ -3512,7 +3512,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.272",
+  version: "0.3.273",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -8368,7 +8368,7 @@ var DeeplineClient = class _DeeplineClient {
     );
     return { ...response, runs: response.runs ?? [] };
   }
-  /** Read batches rather than silently truncating a long key list. */
+  /** Read retained tool results without executing tools, preserving supplied key order and batching 100 keys per request. Obtain keys from exported evidence or execution metadata; each key must be nonempty, at most 2,048 characters and contain no CR, LF or NUL. Missing/expired results have an explicit per-key error. */
   async getRunReceipts(runId, options) {
     if (!options.keys.length || options.keys.some(
       (key) => typeof key !== "string" || !key.trim() || key.length > 2048 || /[\r\n\0]/.test(key)
@@ -8424,7 +8424,7 @@ var DeeplineClient = class _DeeplineClient {
     );
   }
   /**
-   * Fetch persisted logs for a run using the public runs resource model.
+   * Read a run's retained text tail (default 200), full retained stream (`all`), or terminal failure window (`failed`, at most 20). These are existing reads; sampling and retention loss cannot be recovered. See [run logs and events](run-events.md) for structured search and payload retrieval.
    *
    * This is the SDK equivalent of:
    *
@@ -8503,7 +8503,7 @@ var DeeplineClient = class _DeeplineClient {
       ...probe.logsTruncated ? { logsTruncated: true } : {}
     };
   }
-  /** Search bounded, structured runtime history without requiring a run id. */
+  /** Read structured history across the active organization without requiring a run ID. Defaults to the last hour, newest first; use the returned cursor and exact time bounds to continue. See [run logs and events](run-events.md) for all kinds, indexed fields, payloads and SDK/API response types. */
   async searchRunEvents(options = {}) {
     const now = Date.now();
     const params = new URLSearchParams({
@@ -15663,6 +15663,233 @@ function registerPlayTriggerConfigCommands(plays) {
 // src/cli/commands/play.ts
 var import_node_crypto7 = require("crypto");
 
+// src/cli/run-logs-help.ts
+var EVENT_DETAILS = {
+  "run.created": {
+    emittedBy: "Run admission",
+    payloadFields: ["status", "playName", "runtimeBackend"]
+  },
+  "run.started": {
+    emittedBy: "Execution coordinator",
+    payloadFields: ["playName", "runtimeBackend"]
+  },
+  "run.waiting": {
+    emittedBy: "Durable wait handling",
+    payloadFields: ["waitKind", "waitUntil"]
+  },
+  "run.resumed": { emittedBy: "Durable wait handling", payloadFields: [] },
+  "run.completed": {
+    emittedBy: "Run finalization",
+    payloadFields: ["result", "resultSummary", "terminalWorkCounterSegment"]
+  },
+  "run.failed": {
+    emittedBy: "Run finalization",
+    payloadFields: [
+      "error",
+      "result",
+      "resultSummary",
+      "terminalWorkCounterSegment"
+    ]
+  },
+  "run.cancelled": {
+    emittedBy: "Run cancellation",
+    payloadFields: ["error", "result"]
+  },
+  "step.started": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "step.progress": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "status", "progress"]
+  },
+  "step.completed": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "step.failed": {
+    emittedBy: "Managed step execution",
+    payloadFields: [
+      "stepId",
+      "label",
+      "kind",
+      "error",
+      "artifactTableNamespace"
+    ]
+  },
+  "step.skipped": {
+    emittedBy: "Managed step execution",
+    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
+  },
+  "log.appended": {
+    emittedBy: "ctx.log and runtime/coordinator messages",
+    payloadFields: [
+      "lines",
+      "lineContexts",
+      "producerAttempt",
+      "channelOffset",
+      "logsTruncated"
+    ]
+  },
+  "dataset.lifecycle": {
+    emittedBy: "Managed dataset storage",
+    payloadFields: [
+      "datasetId",
+      "path",
+      "tableNamespace",
+      "phase",
+      "persistedRows",
+      "succeededRows",
+      "failedRows",
+      "complete",
+      "bornFrom"
+    ]
+  },
+  "activity.observed": {
+    emittedBy: "Managed provider/dataset/runner activity",
+    payloadFields: ["observation"]
+  },
+  "work.counters": {
+    emittedBy: "Runtime work accounting",
+    payloadFields: [
+      "attempt",
+      "invocationSeq",
+      "segmentId",
+      "logicalCalls",
+      "providerRequests",
+      "provider429s",
+      "final"
+    ]
+  }
+};
+var RUN_LOGS_KIND_HELP = [
+  ...Object.entries(RUN_EVENT_KIND_CATALOG).map(([kind, descriptor]) => ({
+    kind,
+    description: descriptor.description,
+    ...EVENT_DETAILS[kind]
+  })),
+  ...Object.entries(RUN_RECEIPT_SEARCH_KIND_CATALOG).map(
+    ([kind, descriptor]) => ({
+      kind,
+      description: descriptor.description,
+      emittedBy: "Durable work receipt settlement",
+      payloadFields: ["status", "output", "error", "errorPayload"]
+    })
+  ),
+  {
+    kind: RUN_EVENT_SEARCH_FALLBACK_KIND,
+    description: "Fallback for an observation without a recognized event type.",
+    emittedBy: "Event indexing",
+    payloadFields: []
+  }
+];
+var SECTIONS = [
+  {
+    title: "Choose the read",
+    paragraphs: [
+      "These commands read existing evidence; they do not start a run or execute a provider. Replace <run-id>, <play-name> and other angle-bracket values with identifiers returned by the CLI.",
+      "Text logs: runs logs <run-id> returns the last 200 retained lines by default. --out writes the full retained stream to a local file. --log-level filters text severity; debug includes all retained levels. --failed reads only a terminal-failed run\u2019s last 20 retained lines and reports retention limitations.",
+      "Event search: omit the run ID, or add any of --since, --until, --play, --kind, --where, --payloads, --cursor, --runtime-namespace or --runtime-backend. A supplied run ID then narrows the search. --limit and --json alone do not switch a run\u2019s text logs to event search. Text-only flags --out, --failed, --log-level, --logs and --debug cannot be combined with event search.",
+      "Current status and returned output selectors: runs get <run-id> --json. Live observation: runs watch <run-id>. Dataset rows: runs export <run-id> --dataset <returned-selector> --out rows.csv. A referenced tool response: runs receipt <run-id> --key <returned-receipt-key> --json. Read each command\u2019s --help for its options."
+    ],
+    commands: [
+      "deepline runs logs <run-id> --json",
+      "deepline runs logs <run-id> --out run.log --json",
+      "deepline runs logs --kind run.failed --json",
+      "deepline runs logs --kind step.failed --payloads --json",
+      "deepline runs logs --kind receipt.failed --payloads --json"
+    ]
+  },
+  {
+    title: "Search window and pagination",
+    paragraphs: [
+      "Search defaults to the last hour, newest first. Use explicit ISO UTC --since and --until values for reproducible queries; the maximum lookback is seven days. Default page size is 100 events; --limit accepts 1\u2013200. With --payloads, default and maximum are 10 events, with 16 MiB total payload data.",
+      "JSON returns events[], returnedCount, since, until, nextCursor and next.logs. Run the returned next.logs command to continue with the same filters and UTC window; nextCursor is opaque. A bounded page or an empty result does not establish whole-run coverage or application health."
+    ],
+    commands: [
+      "deepline runs logs <run-id> --kind log.appended --json",
+      "deepline runs logs --play <play-name> --since <UTC-start> --until <UTC-end> --json"
+    ]
+  },
+  {
+    title: "Fields you can filter with --where",
+    paragraphs: [
+      "Identity strings: orgId, runId, playName, runtimeScope. These come from authenticated execution state; filters only narrow your authorized organization/runtime. Preview reads require the existing runtime credential and an authorized --runtime-namespace; --runtime-backend selects daytona or modal.",
+      "Event string: kind. Optional strings: source, stepId, stepKind, status, datasetId, phase, provider, operation. Optional positive integer: producerAttempt. These fields exist only when recorded; inspect a returned event before filtering on an optional field.",
+      'stepId/stepKind describe recorded step work; datasetId/phase describe dataset lifecycle (registered, available, failed). provider/operation appear on typed provider activity.observed events, not every receipt or provider call. status is the recorded status or activity state when present: run.completed and step.completed do not imply status == "completed". Select lifecycle outcomes with --kind.',
+      "context.<key> matches an authored flat scalar log field: string, number or boolean. Context cannot override event identity. Missing fields do not match. --where supports only $.field == literal predicates joined with &&, at most eight predicates and 512 bytes. No OR, ranges, wildcards, nested payload paths or text search. Time uses --since/--until; level and message are not --where fields."
+    ],
+    commands: [
+      `deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads --json`,
+      `deepline runs logs <run-id> --where '$.source == "worker" && $.producerAttempt == 1' --json`,
+      `deepline runs logs --kind activity.observed --where '$.provider == "<returned-provider>" && $.operation == "<returned-operation>"' --json`,
+      `deepline runs logs --kind log.appended --where '$.context.<authored-key> == "<recorded-value>"' --json`
+    ]
+  },
+  {
+    title: "What you get back",
+    paragraphs: [
+      "Search events include eventId, occurredAt, ingestedAt, kind, runId, playName, level and message. The CLI puts indexed fields directly on each events[] entry; SDK/API responses keep them under searchDoc. Log search message is a preview (up to 2,048 characters); use text logs or --out for full retained lines.",
+      "--payloads adds eventPayload for stored canonical events: lifecycle, step details/errors, activity observations, dataset transitions and work counters. Receipt matches instead hydrate payload with status, output, error and errorPayload. An event without a receipt does not promise a tool response; retained payloads may be unavailable. Neither --where nor event search indexes request/response bodies.",
+      "Search does not expose a receipt key or storage reference. To retrieve a specific retained tool response with runs receipt, use the receipt key returned in the run\u2019s exported evidence or tool execution metadata. For full row data, follow runs get output/export actions; dataset.lifecycle contains metadata, not all dataset rows.",
+      "The catalog lists known searchable kinds, including receipt outcomes and the runtime.event fallback. Use the exact dotted name with --kind. Future stored kinds can also be queried; this list is not a CLI validation allowlist. Events are observations, not a count of billed provider calls.",
+      "Catalog payload fields are possible producer fields, not required fields or --where paths. Canonical eventPayload uses type for the dotted event kind; its kind field, when present on a step, becomes indexed stepKind. Indexed log entries describe individual lines rather than reproducing the original lines batch.",
+      "Canonical event envelopes carry runId, type, occurredAt (producer milliseconds), source, optional seq and optional producer-owned payload. Search occurredAt/ingestedAt are UTC timestamp strings. source identifies the recorded producer; producerAttempt is present only when known.",
+      "activity.observed stores observation with activityId, stepId, target, state and observedAt. Targets describe provider, dataset, lease, runner, step or capacity work. State kinds are active, queued, waiting, retrying, scheduled, completed or failed; retry/wait detail stays in the payload. work.counters contains aggregate logicalCalls, providerRequests and provider429s, not per-call responses."
+    ],
+    commands: []
+  }
+];
+var RETENTION = [
+  "Event/log/receipt search shares the PlanetScale index. New runs marked runEventStore=planet_scale retain accepted event/log history in PlanetScale; Convex keeps current run/control state and eligible saved-Play rollup facts. Older unmarked runs retain their existing readers. No backfill is implied.",
+  "Search retention is seven days; receipt payload retention is independent. Logs reflect accepted, retained lines: runtime sampling and truncation can omit original console output. Read returned retention/sampling warnings; an export contains the full retained stream, not suppressed lines."
+];
+function wrapParagraph(text, indent2 = 2) {
+  const lines = [];
+  const padding = " ".repeat(indent2);
+  let line = padding;
+  for (const word of text.split(" ")) {
+    if (line.length + word.length > 80 && line.trim()) {
+      lines.push(line.trimEnd());
+      line = padding;
+    }
+    line += `${word} `;
+  }
+  lines.push(line.trimEnd());
+  return lines.join("\n");
+}
+function renderRunLogsHelp() {
+  const section = ({
+    title,
+    paragraphs,
+    commands
+  }) => [
+    `${title}:`,
+    ...paragraphs.flatMap((paragraph) => [wrapParagraph(paragraph), ""]),
+    ...commands.length ? ["  Common commands:", ...commands.map((command) => `    ${command}`)] : [],
+    ""
+  ];
+  return [
+    "",
+    ...section(SECTIONS[0]),
+    "Known --kind values (complete catalog):",
+    ...RUN_LOGS_KIND_HELP.flatMap(
+      ({ kind, description, emittedBy, payloadFields }) => [
+        `  ${kind}`,
+        wrapParagraph(description, 4),
+        wrapParagraph(
+          `Recorded by: ${emittedBy}. Payload fields: ${kind === RUN_EVENT_SEARCH_FALLBACK_KIND ? "producer-specific fields; inspect the returned payload" : payloadFields.join(", ") || "event envelope only"}.`,
+          4
+        )
+      ]
+    ),
+    "",
+    ...SECTIONS.slice(1).flatMap(section),
+    "Storage and retention:",
+    ...RETENTION.flatMap((paragraph) => [wrapParagraph(paragraph), ""])
+  ].join("\n");
+}
+
 // ../play-runtime/run-execution-state.ts
 function assertNeverState(value, what) {
   throw new Error(`Unhandled ${what}: ${JSON.stringify(value)}`);
@@ -36794,51 +37021,21 @@ Examples:
   });
   runs.command("logs [runId]").description(
     "Fetch one run\u2019s logs or search recent runtime events across runs."
-  ).addHelpText(
-    "after",
-    `
-Notes:
-  Prints a bounded recent log preview by default. Use --out to write the full
-  retained stream to a local file. Use --log-level to filter by severity;
-  default debug preserves the complete historical stream.
-
-  Search flags read the org-scoped event index (last hour by default, at most
-  seven days). Org, run, Play, runtime scope and known attempt identity are
-  attached automatically. --where accepts equality joined with && for orgId,
-  runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId,
-  stepKind, datasetId, phase, provider, operation, and scalar context.<key>.
-  Filters only narrow the authenticated org/runtime scope. Provider and
-  operation come from typed provider activity observations; this does not
-  index request/response bodies or promise one event per provider call. --payloads
-  includes full result data in this command, capped at ten events and 16 MiB.
-
-  Event, log, and receipt search share one PlanetScale index. For runs marked
-  runEventStore=planet_scale, PlanetScale owns full event/log history; Convex
-  keeps the live run snapshot, admission fence, and eligible saved-Play rollup
-  facts. Marked-run log bodies are not copied into Convex. Unmarked legacy runs
-  keep their existing Convex event history and Run Log Stream.
-  Known --kind values: ${RUN_EVENT_SEARCH_KIND_VALUES.join(", ")}.
-
-Examples:
-  deepline runs logs play/my-play/run/20260501t000000-000
-  deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
-  deepline runs logs play/my-play/run/20260501t000000-000 --failed --json
-  deepline runs logs play/my-play/run/20260501t000000-000 --log-level error
-  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --log-level debug --json
-  deepline runs logs --since 2026-09-29T00:00:00Z --kind step.failed --json
-  deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"' --json
-  deepline runs logs --play my-play --where '$.context.companyId == "acme_123"' --json
-  deepline runs logs --where '$.status == "failed"' --payloads --play my-play --json
-`
-  ).option("--limit <count>", "Maximum log lines or search events to print").option("--out <path>", "Write the full retained log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option(
+  ).addHelpText("after", renderRunLogsHelp()).option(
+    "--limit <count>",
+    "Text tail: default 200; search: default 100, max 200 (10 with --payloads)"
+  ).option("--out <path>", "Write the full retained log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option(
     "--log-level <level>",
     "Minimum severity: debug (default), info, warn, or error"
-  ).option("--logs", "Compatibility alias for --log-level debug").option("--debug", "Compatibility alias for --log-level debug").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--since <timestamp>", "Search events since this UTC timestamp").option("--until <timestamp>", "Search events before this UTC timestamp").option("--play <name>", "Filter events by Play name").option("--kind <kind>", "Filter events by kind").option(
+  ).option("--logs", "Compatibility alias for --log-level debug").option("--debug", "Compatibility alias for --log-level debug").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--since <timestamp>", "Search events since this UTC timestamp").option("--until <timestamp>", "Search events before this UTC timestamp").option("--play <name>", "Filter events by Play name").option(
+    "--kind <kind>",
+    "Search one exact event kind; complete catalog below"
+  ).option(
     "--where <jsonpath>",
-    'Bound JSONPath equality over event fields (for example $.provider == "apollo" && $.operation == "company_lookup")'
+    "Search indexed fields with == and &&; field types and availability below"
   ).option(
     "--payloads",
-    "Include full stored payloads (up to 10 events and 16 MiB)"
+    "Search with canonical eventPayload or receipt payload; max 10 events, 16 MiB"
   ).option("--cursor <token>", "Continue a bounded event search").option(
     "--runtime-namespace <name>",
     "Search an explicitly authorized Preview namespace"