@localhostdevs/sdk 0.17.0 → 0.19.0

package/README.md

@@ -1,356 +1,383 @@
-# @localhostdevs/sdk
-
-The JavaScript SDK for building bots on **[localhostdevs](https://localhostdevs.com)** — run your app on your own laptop and publish it as a command-driven bot that anyone can use through a chat-style interface.
-
-> Pre-1.0: API surface may break in minor versions (`0.x → 0.y`). Once the platform launches with external users, we'll cut a 1.0 that promises stability.
-
-## Install
-
-```bash
-npm install @localhostdevs/sdk
-```
-
-## Quickstart
-
-After creating a bot in the [dashboard](https://localhostdevs.com/dashboard/bots) and copying your API key, write this to `app.js`:
-
-```js
-import { Bot } from '@localhostdevs/sdk';
-
-const bot = new Bot({
-  id: 'price-bot', // your bot's handle (matches the @handle on the marketplace)
-  // apiKey: process.env.BOT_SECRET,  // optional; auto-read from env if unset
-});
-
-bot.cmd({ name: 'ping' }, async (ctx) => {
-  await ctx.reply({ text: 'pong' });
-});
-
-bot.cmd({ name: 'echo' }, async (ctx) => {
-  await ctx.reply({ text: `echo: ${JSON.stringify(ctx.args)}` });
-});
-
-await bot.connect();
-console.log('bot online — waiting for commands');
-```
-
-Then:
-
-```bash
-BOT_SECRET=<your Bot Secret from the dashboard> node app.js
-```
-
-The bot stays online for as long as the process runs. The gateway keeps the connection healthy via heartbeats; consumers see your bot as **online** while it's connected.
-
-## API
-
-### `new Bot(opts)`
-
-| Option               | Type                | Default                                                           | Notes                                                                                             |
-| -------------------- | ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `id`                 | `string` (required) | —                                                                 | Your bot's handle. Lowercase letters / digits / dashes.                                           |
-| `apiKey`             | `string` (required) | `process.env.BOT_SECRET`                                          | Per-bot **Bot Secret** from the dashboard. The gateway validates it and scopes you to your own bot only. The constructor option name stays `apiKey` for backward compatibility with older SDK versions; the dashboard label and env var moved to "Bot Secret" / `BOT_SECRET` to disambiguate from user-level API keys (`lhduser_…`) used against the public REST API. |
-| `serverUrl`          | `string`            | `wss://bot-api.localhostdevs.com/bot` (override with `LHD_SERVER_URL`)  | Production gateway is baked in — most users leave this alone. Only override for local dev or self-hosted gateways.                  |
-| `idempotencyLruSize` | `number`            | `1024`                                                            | How many recent message IDs to remember for deduplication.                                        |
-
-### `bot.cmd(def, handler)`
-
-Register a handler for a command. Must be called before `connect()`. The first argument is a **command definition object** with the following fields:
-
-| Field         | Type                                       | Notes                                                                                                                                           |
-| ------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`        | `string` (required)                        | Command name consumers dispatch (e.g. `'ping'`, `'topic'`).                                                                                     |
-| `description` | `string`                                   | Human-readable description shown on the marketplace/workflow picker.                                                                             |
-| `args`        | `Record<string, ArgSpec>`                  | Declare the expected arguments (see below). **Advertise-only** by default — fills the marketplace and workflow picker but does NOT validate at runtime unless `validate: true`. |
-| `returns`     | `{ kind: ReplyKind, data?: Record<string, 'string' \| 'number' \| 'boolean'> }` | Declare the reply kind. Enforced: the handler must call the matching reply method or the SDK throws (see Reply-kind enforcement below).           |
-| `validate`    | `boolean`                                  | When `true`, the SDK validates `ctx.args` against the declared `args` before running your handler. A bad dispatch is rejected with a structured `invalid_args` error. Also narrows TypeScript types: `required` fields become typed-present in `ctx.args`. Without `validate`, all arg fields are typed optional. |
-| `streaming`   | `boolean`                                  | Override the bot-level streaming flag for this command only.                                                                                     |
-| `mimeType`    | `string`                                   | MIME-type hint advertised in IDENTIFY (advertising-only, doesn't affect runtime).                                                                |
-
-#### `ArgSpec` shape
-
-```ts
-interface ArgSpec {
-  type: 'string' | 'number' | 'boolean' | 'enum';
-  required?: boolean;
-  description?: string;
-  values?: readonly string[];   // required when type === 'enum'
-}
-```
-
-#### `returns.kind` vocabulary
-
-`'text'` | `'list'` | `'table'` | `'image'` | `'buttons'` | `'collect'`
-
-The declared kind is **enforced at runtime**: if the handler calls a reply method that doesn't match the declaration (e.g. `returns: { kind: 'list' }` but the handler calls `ctx.reply()`), the SDK throws a hard error. TypeScript also narrows `ctx`'s available reply methods to just the ones valid for the declared kind.
-
-#### Example
-
-```ts
-bot.cmd({
-  name: 'topic',
-  description: 'Scrape trends for a query, then pick one',
-  args: {
-    query:  { type: 'string', required: true, description: 'Search query' },
-    format: { type: 'string', description: 'e.g. short_30s' },
-    voice:  { type: 'enum', values: ['on', 'off'] },
-  },
-  returns: { kind: 'list', data: { jobId: 'string', state: 'string' } },
-  validate: false,   // opt-in: when true, args are validated AND required fields typed-present
-}, async (ctx) => {
-  // ctx.args is typed from `args`; ctx reply methods are narrowed to returns.kind
-  await ctx.replyList([{ title: ctx.args.query ?? '' }]);
-});
-```
-
-Handler receives a `CommandContext`:
-
-```ts
-bot.cmd({ name: 'greet' }, async (ctx) => {
-  // ctx.args:    parsed args from the consumer
-  // ctx.command: 'greet'
-  // ctx.msgId:   unique id for this invocation
-
-  await ctx.reply({ text: `Hello, ${ctx.args.name ?? 'world'}!` });
-
-  // ctx.reply also supports:
-  //   data: any                — structured payload alongside text
-  //   dispatch: { to, command, args }  — chain to another bot (max depth 5)
-});
-```
-
-### `await bot.connect()`
-
-Open the WebSocket to the gateway, authenticate, and start receiving commands. Resolves after the gateway sends `HELLO` (the SDK is ready for traffic).
-
-### `await bot.disconnect()`
-
-Close the WebSocket cleanly.
-
-## Idempotency
-
-Every command from the gateway carries a `msgId`. The SDK deduplicates redelivered messages via a fixed-size LRU keyed by `msgId`. If the gateway happens to deliver the same command twice, your handler runs once.
-
-## Online / offline status
-
-The gateway pings the bot every 30 seconds and the SDK responds. If the gateway stops hearing from you for >60 seconds it marks the bot offline. Reconnect simply by starting the process again.
-
-## Bot-to-bot composition
-
-A reply can carry a `dispatch` directive to chain a command to another bot:
-
-```js
-bot.cmd({ name: 'summary' }, async (ctx) => {
-  await ctx.reply({
-    text: 'fetching price first…',
-    dispatch: { to: 'price-bot', command: 'price', args: { ticker: 'AAPL' } },
-  });
-});
-```
-
-Chains run up to depth 5 with loop detection. The original consumer pays for every step.
-
-## Structured replies (0.5.0+)
-
-By default `ctx.reply({ text })` sends a plain-text body — the consumer
-renders it as text. To get richer rendering (source-badge lists, striped
-tables) on the dashboard Test Console and the public Try widget, return a
-**kinded** body via the helpers:
-
-```js
-// List output
-bot.cmd({
-  name: 'headlines',
-  returns: { kind: 'list' },
-}, async (ctx) => {
-  await ctx.replyList(
-    [
-      { label: 'AP',     title: 'Story one', secondary: '2m', href: '…' },
-      { label: 'Reuters', title: 'Story two', secondary: '5m' },
-    ],
-    { header: '2 headlines · global' }, // optional
-  );
-});
-
-// Table output
-bot.cmd({
-  name: 'top5',
-  returns: { kind: 'table' },
-}, async (ctx) => {
-  await ctx.replyTable({
-    headers: ['ticker', 'price', 'change'],
-    rows: [
-      ['AAPL', 188.12, 1.4],
-      ['MSFT', 412.50, null],
-    ],
-  });
-});
-```
-
-**Body shapes on the wire** (the gateway also wraps legacy `{ text }`
-replies in `{ kind: 'text', text }` so consumers always see a
-discriminated union):
-
-```ts
-type BotResponse =
-  | { kind: 'text';  text: string;  mimeType?: string; data?: unknown }
-  | { kind: 'list';  header?: string; items: ListItem[] }
-  | { kind: 'table'; headers: string[]; rows: Array<Array<string | number | null>> };
-
-interface ListItem {
-  label?: string;     // small badge on the left, e.g. "AP"
-  title: string;      // primary line
-  secondary?: string; // trailing text, e.g. "2m"
-  href?: string;      // optional click-through
-}
-```
-
-**Validation.** `replyList()` rejects empty `items` and items missing a
-`title`. `replyTable()` rejects empty `headers` and rows whose cell count
-doesn't match `headers.length`. Validation runs BEFORE the once-only reply
-guard flips, so if you catch the error you can still send a corrected
-`ctx.reply()`. After a successful reply (via any of the three methods),
-further reply calls throw — the SDK guarantees exactly-one reply per
-command.
-
-**Reply-kind enforcement.** When `returns.kind` is declared on the command
-definition, the SDK enforces it at runtime: calling a mismatched reply
-method (e.g. `ctx.reply()` when `returns: { kind: 'list' }`) throws a hard
-error. TypeScript also narrows `ctx`'s available reply methods to the ones
-valid for the declared kind, so mismatches are caught at compile time.
-
-## Streaming progress (`ctx.update`)
-
-Long-running commands can emit intermediate progress frames before the
-final reply. Enable per-bot or per-command:
-
-```js
-const bot = new Bot({
-  id: 'analyze-bot',
-  streaming: true,             // enables ctx.update across all commands
-});
-
-bot.cmd({ name: 'analyze' }, async (ctx) => {
-  await ctx.update({ progress: 10, text: 'Fetching…' });
-  await ctx.update({ progress: 60, text: 'Crunching…' });
-  await ctx.reply({
-    text: 'done',
-    mimeType: 'image/png',
-    data: chartBytesBase64,
-  });
-});
-```
-
-Or per-command using `streaming` in the definition:
-
-```js
-bot.cmd({ name: 'analyze', streaming: true }, async (ctx) => { /* … */ });
-bot.cmd({ name: 'ping' }, async (ctx) => { /* no ctx.update here */ });
-```
-
-**Progress shapes** (use whichever fits the work):
-
-- `number` — percent (0–100). Renders as a horizontal bar.
-- `{ current, total }` — step counter. Renders as "5 / 30".
-- `{ label: string }` — indeterminate. Renders as a spinner + label.
-
-**MIME-type hints** (`mimeType` on both update and reply bodies) let the
-consumer choose how to render the body. v1 chat UI handles
-`text/plain` (default) and `text/markdown`; others fall back to a code
-block of the data field.
-
-**Consumer contract**: when the public REST API caller hits
-`POST /api/v1/bots/{handle}/dispatch` with
-`Accept: text/event-stream` or `Accept: application/x-ndjson`, they
-receive each frame as it arrives. Default `Accept: application/json`
-(or no Accept) returns only the final frame as a single JSON — backward
-compatible with everything written before this release. See
-`/docs/api` on localhostdevs.com for full details.
-
-### Declaring mimeType per command (0.4.1+)
-
-Tell the platform what each command's reply looks like so the bot
-detail page can show consumers what to expect:
-
-```js
-bot.cmd({ name: 'chart', streaming: true, mimeType: 'image/png' }, async (ctx) => {
-  await ctx.reply({ data: chartBytes, mimeType: 'image/png' });
-});
-
-bot.cmd({ name: 'summarize', mimeType: 'text/markdown' }, async (ctx) => {
-  await ctx.reply({ text: '# Summary\n…', mimeType: 'text/markdown' });
-});
-
-bot.cmd({ name: 'ping' }, async (ctx) => {   // no mimeType — displays as text/plain
-  await ctx.reply({ text: 'pong' });
-});
-```
-
-The declaration is **advertising-only** — the actual mimeType on the
-wire is whatever `ctx.reply({ mimeType })` passes. Mismatches don't
-crash anything; the bot detail page shows the declared value and the
-consumer renders whatever the runtime reply specifies.
-
-## v0.3.5: Bot Secret env-var rename
-
-The env var name moved from `LHD_API_KEY` to `BOT_SECRET` to disambiguate from
-user-level public-API keys (`lhduser_…`). Rename the env var in your bot's
-deployment — no code change needed if you used the env-var path:
-
-```diff
-- LHD_API_KEY=lhd_live_… node app.js
-+ BOT_SECRET=lhd_live_… node app.js
-```
-
-If you pass `apiKey` explicitly into the constructor, no change at all —
-the option name on `BotOptions` is preserved.
-
-## Migrating from v0.2 → v0.3 (gateway pivot)
-
-v0.3 is a breaking change vs v0.2 — the SDK no longer talks to NATS directly. It opens a WebSocket to the managed gateway and auths with a per-bot Bot Secret:
-
-| Was (v0.2)                             | Now (v0.3+)                    |
-| -------------------------------------- | ------------------------------ |
-| `new Bot({ id, natsUrl: 'nats://…' })` | `new Bot({ id, apiKey: '…' })` |
-| `LHD_NATS_TOKEN=… node app.js`         | `BOT_SECRET=… node app.js`     |
-
-Drop the `natsUrl` and `natsToken` options entirely — the SDK figures out the right gateway URL on its own. Use your bot's **Bot Secret** from the dashboard (not the old shared broker token).
-
-## v0.3.x → v0.4 (streaming opt-in)
-
-v0.4 is additive — nothing breaks for bots calling only `ctx.reply()`.
-New surface:
-
-- `new Bot({ …, streaming: true })` to enable `ctx.update()`
-- `streaming: true` inside the command definition to flip the flag per command
-- `ctx.update({ progress?, text?, data?, mimeType? })` — send 1+
-  intermediate frames before `ctx.reply()`
-- `mimeType` on `ctx.reply()` for the existing final-reply path
-
-No env-var changes, no protocol breakage, no upstream re-auth.
-
-## v0.4.0 → v0.4.1 (per-command mimeType)
-
-Additive — no breaking changes. The `mimeType?` field in the command definition
-is optional; bots that ignore it work exactly the same. The SDK auto-builds an
-IDENTIFY-time `commands` array from your registered handlers so the platform can
-display them on the bot detail page.
-
-## v0.14 → v0.15 (object `cmd()`)
-
-**Breaking.** See [MIGRATION.md](./MIGRATION.md) for the full guide.
-
-`cmd()` now takes a **command definition object** as its first argument. The
-string-form is removed.
-
-```diff
-- bot.cmd("ping", async (ctx) => { … })
-+ bot.cmd({ name: "ping" }, async (ctx) => { … })
-
-- bot.cmd("analyze", { streaming: true }, async (ctx) => { … })
-+ bot.cmd({ name: "analyze", streaming: true }, async (ctx) => { … })
-```
-
-## License
-
-MIT
+# @localhostdevs/sdk
+
+The JavaScript SDK for building bots on **[localhostdevs](https://localhostdevs.com)** — run your app on your own laptop and publish it as a command-driven bot that anyone can use through a chat-style interface.
+
+> Pre-1.0: API surface may break in minor versions (`0.x → 0.y`). Once the platform launches with external users, we'll cut a 1.0 that promises stability.
+
+## Install
+
+```bash
+npm install @localhostdevs/sdk
+```
+
+## Quickstart
+
+After creating a bot in the [dashboard](https://localhostdevs.com/dashboard/bots) and copying your API key, write this to `app.js`:
+
+```js
+import { Bot } from '@localhostdevs/sdk';
+
+const bot = new Bot({
+  id: 'price-bot', // your bot's handle (matches the @handle on the marketplace)
+  // apiKey: process.env.BOT_SECRET,  // optional; auto-read from env if unset
+});
+
+bot.cmd({ name: 'ping' }, async (ctx) => {
+  await ctx.reply({ text: 'pong' });
+});
+
+bot.cmd({ name: 'echo' }, async (ctx) => {
+  await ctx.reply({ text: `echo: ${JSON.stringify(ctx.args)}` });
+});
+
+await bot.connect();
+console.log('bot online — waiting for commands');
+```
+
+Then:
+
+```bash
+BOT_SECRET=<your Bot Secret from the dashboard> node app.js
+```
+
+The bot stays online for as long as the process runs. The gateway keeps the connection healthy via heartbeats; consumers see your bot as **online** while it's connected.
+
+## API
+
+### `new Bot(opts)`
+
+| Option               | Type                | Default                                                           | Notes                                                                                             |
+| -------------------- | ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `id`                 | `string` (required) | —                                                                 | Your bot's handle. Lowercase letters / digits / dashes.                                           |
+| `apiKey`             | `string` (required) | `process.env.BOT_SECRET`                                          | Per-bot **Bot Secret** from the dashboard. The gateway validates it and scopes you to your own bot only. The constructor option name stays `apiKey` for backward compatibility with older SDK versions; the dashboard label and env var moved to "Bot Secret" / `BOT_SECRET` to disambiguate from user-level API keys (`lhduser_…`) used against the public REST API. |
+| `serverUrl`          | `string`            | `wss://bot-api.localhostdevs.com/bot` (override with `LHD_SERVER_URL`)  | Production gateway is baked in — most users leave this alone. Only override for local dev or self-hosted gateways.                  |
+| `idempotencyLruSize` | `number`            | `1024`                                                            | How many recent message IDs to remember for deduplication.                                        |
+
+### `bot.cmd(def, handler)`
+
+Register a handler for a command. Must be called before `connect()`. The first argument is a **command definition object** with the following fields:
+
+| Field         | Type                                       | Notes                                                                                                                                           |
+| ------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | `string` (required)                        | Command name consumers dispatch (e.g. `'ping'`, `'topic'`).                                                                                     |
+| `description` | `string`                                   | Human-readable description shown on the marketplace/workflow picker.                                                                             |
+| `args`        | `Record<string, ArgSpec>`                  | Declare the expected arguments (see below). **Advertise-only** by default — fills the marketplace and workflow picker but does NOT validate at runtime unless `validate: true`. |
+| `returns`     | `{ kind: ReplyKind, data?: Record<string, 'string' \| 'number' \| 'boolean'> }` | Declare the reply kind. Enforced: the handler must call the matching reply method or the SDK throws (see Reply-kind enforcement below).           |
+| `validate`    | `boolean`                                  | When `true`, the SDK validates `ctx.args` against the declared `args` before running your handler. A bad dispatch is rejected with a structured `invalid_args` error. Also narrows TypeScript types: `required` fields become typed-present in `ctx.args`. Without `validate`, all arg fields are typed optional. |
+| `streaming`   | `boolean`                                  | Override the bot-level streaming flag for this command only.                                                                                     |
+| `mimeType`    | `string`                                   | MIME-type hint advertised in IDENTIFY (advertising-only, doesn't affect runtime).                                                                |
+
+#### `ArgSpec` shape
+
+```ts
+interface ArgSpec {
+  type: 'string' | 'number' | 'boolean' | 'enum';
+  required?: boolean;
+  description?: string;
+  values?: readonly string[];   // required when type === 'enum'
+}
+```
+
+#### `returns.kind` vocabulary
+
+`'text'` | `'list'` | `'table'` | `'image'` | `'buttons'` | `'collect'`
+
+The declared kind is **enforced at runtime**: if the handler calls a reply method that doesn't match the declaration (e.g. `returns: { kind: 'list' }` but the handler calls `ctx.reply()`), the SDK throws a hard error. TypeScript also narrows `ctx`'s available reply methods to just the ones valid for the declared kind.
+
+#### Example
+
+```ts
+bot.cmd({
+  name: 'topic',
+  description: 'Scrape trends for a query, then pick one',
+  args: {
+    query:  { type: 'string', required: true, description: 'Search query' },
+    format: { type: 'string', description: 'e.g. short_30s' },
+    voice:  { type: 'enum', values: ['on', 'off'] },
+  },
+  returns: { kind: 'list', data: { jobId: 'string', state: 'string' } },
+  validate: false,   // opt-in: when true, args are validated AND required fields typed-present
+}, async (ctx) => {
+  // ctx.args is typed from `args`; ctx reply methods are narrowed to returns.kind
+  await ctx.replyList([{ title: ctx.args.query ?? '' }]);
+});
+```
+
+Handler receives a `CommandContext`:
+
+```ts
+bot.cmd({ name: 'greet' }, async (ctx) => {
+  // ctx.args:    parsed args from the consumer
+  // ctx.command: 'greet'
+  // ctx.msgId:   unique id for this invocation
+
+  await ctx.reply({ text: `Hello, ${ctx.args.name ?? 'world'}!` });
+
+  // ctx.reply also supports:
+  //   data: any                — structured payload alongside text
+  //   dispatch: { to, command, args }  — chain to another bot (max depth 5)
+});
+```
+
+### `bot.register(...descriptors)`
+
+Register one or more commands from **descriptor objects** — the composition-root
+API. A descriptor is `{ command, handler }`, where `command` is the same object
+`cmd()` takes and `handler` is the same handler. This lets a command live in its
+own file and `app.js` just wire it up:
+
+```js
+// commands/ping.js
+export default {
+  command: { name: 'ping', description: 'Replies with pong', returns: { kind: 'text' } },
+  handler: async (ctx) => { await ctx.reply({ text: 'pong' }) },
+}
+
+// app.js — the composition root
+import ping from './commands/ping.js'
+import echo from './commands/echo.js'
+
+const bot = new Bot({ id: 'my-bot' })
+bot.register(ping).register(echo)   // chainable; or bot.register(ping, echo)
+await bot.connect()
+```
+
+`register` is chainable (returns the bot) and variadic. It forwards to `cmd()`,
+so all the same rules apply (must be called before `connect()`; duplicate names
+throw). `cmd()` remains fully supported for inline commands.
+
+### `await bot.connect()`
+
+Open the WebSocket to the gateway, authenticate, and start receiving commands. Resolves after the gateway sends `HELLO` (the SDK is ready for traffic).
+
+### `await bot.disconnect()`
+
+Close the WebSocket cleanly.
+
+## Idempotency
+
+Every command from the gateway carries a `msgId`. The SDK deduplicates redelivered messages via a fixed-size LRU keyed by `msgId`. If the gateway happens to deliver the same command twice, your handler runs once.
+
+## Online / offline status
+
+The gateway pings the bot every 30 seconds and the SDK responds. If the gateway stops hearing from you for >60 seconds it marks the bot offline. Reconnect simply by starting the process again.
+
+## Bot-to-bot composition
+
+A reply can carry a `dispatch` directive to chain a command to another bot:
+
+```js
+bot.cmd({ name: 'summary' }, async (ctx) => {
+  await ctx.reply({
+    text: 'fetching price first…',
+    dispatch: { to: 'price-bot', command: 'price', args: { ticker: 'AAPL' } },
+  });
+});
+```
+
+Chains run up to depth 5 with loop detection. The original consumer pays for every step.
+
+## Structured replies (0.5.0+)
+
+By default `ctx.reply({ text })` sends a plain-text body — the consumer
+renders it as text. To get richer rendering (source-badge lists, striped
+tables) on the dashboard Test Console and the public Try widget, return a
+**kinded** body via the helpers:
+
+```js
+// List output
+bot.cmd({
+  name: 'headlines',
+  returns: { kind: 'list' },
+}, async (ctx) => {
+  await ctx.replyList(
+    [
+      { label: 'AP',     title: 'Story one', secondary: '2m', href: '…' },
+      { label: 'Reuters', title: 'Story two', secondary: '5m' },
+    ],
+    { header: '2 headlines · global' }, // optional
+  );
+});
+
+// Table output
+bot.cmd({
+  name: 'top5',
+  returns: { kind: 'table' },
+}, async (ctx) => {
+  await ctx.replyTable({
+    headers: ['ticker', 'price', 'change'],
+    rows: [
+      ['AAPL', 188.12, 1.4],
+      ['MSFT', 412.50, null],
+    ],
+  });
+});
+```
+
+**Body shapes on the wire** (the gateway also wraps legacy `{ text }`
+replies in `{ kind: 'text', text }` so consumers always see a
+discriminated union):
+
+```ts
+type BotResponse =
+  | { kind: 'text';  text: string;  mimeType?: string; data?: unknown }
+  | { kind: 'list';  header?: string; items: ListItem[] }
+  | { kind: 'table'; headers: string[]; rows: Array<Array<string | number | null>> };
+
+interface ListItem {
+  label?: string;     // small badge on the left, e.g. "AP"
+  title: string;      // primary line
+  secondary?: string; // trailing text, e.g. "2m"
+  href?: string;      // optional click-through
+}
+```
+
+**Validation.** `replyList()` rejects empty `items` and items missing a
+`title`. `replyTable()` rejects empty `headers` and rows whose cell count
+doesn't match `headers.length`. Validation runs BEFORE the once-only reply
+guard flips, so if you catch the error you can still send a corrected
+`ctx.reply()`. After a successful reply (via any of the three methods),
+further reply calls throw — the SDK guarantees exactly-one reply per
+command.
+
+**Reply-kind enforcement.** When `returns.kind` is declared on the command
+definition, the SDK enforces it at runtime: calling a mismatched reply
+method (e.g. `ctx.reply()` when `returns: { kind: 'list' }`) throws a hard
+error. TypeScript also narrows `ctx`'s available reply methods to the ones
+valid for the declared kind, so mismatches are caught at compile time.
+
+## Streaming progress (`ctx.update`)
+
+Long-running commands can emit intermediate progress frames before the
+final reply. Enable per-bot or per-command:
+
+```js
+const bot = new Bot({
+  id: 'analyze-bot',
+  streaming: true,             // enables ctx.update across all commands
+});
+
+bot.cmd({ name: 'analyze' }, async (ctx) => {
+  await ctx.update({ progress: 10, text: 'Fetching…' });
+  await ctx.update({ progress: 60, text: 'Crunching…' });
+  await ctx.reply({
+    text: 'done',
+    mimeType: 'image/png',
+    data: chartBytesBase64,
+  });
+});
+```
+
+Or per-command using `streaming` in the definition:
+
+```js
+bot.cmd({ name: 'analyze', streaming: true }, async (ctx) => { /* … */ });
+bot.cmd({ name: 'ping' }, async (ctx) => { /* no ctx.update here */ });
+```
+
+**Progress shapes** (use whichever fits the work):
+
+- `number` — percent (0–100). Renders as a horizontal bar.
+- `{ current, total }` — step counter. Renders as "5 / 30".
+- `{ label: string }` — indeterminate. Renders as a spinner + label.
+
+**MIME-type hints** (`mimeType` on both update and reply bodies) let the
+consumer choose how to render the body. v1 chat UI handles
+`text/plain` (default) and `text/markdown`; others fall back to a code
+block of the data field.
+
+**Consumer contract**: when the public REST API caller hits
+`POST /api/v1/bots/{handle}/dispatch` with
+`Accept: text/event-stream` or `Accept: application/x-ndjson`, they
+receive each frame as it arrives. Default `Accept: application/json`
+(or no Accept) returns only the final frame as a single JSON — backward
+compatible with everything written before this release. See
+`/docs/api` on localhostdevs.com for full details.
+
+### Declaring mimeType per command (0.4.1+)
+
+Tell the platform what each command's reply looks like so the bot
+detail page can show consumers what to expect:
+
+```js
+bot.cmd({ name: 'chart', streaming: true, mimeType: 'image/png' }, async (ctx) => {
+  await ctx.reply({ data: chartBytes, mimeType: 'image/png' });
+});
+
+bot.cmd({ name: 'summarize', mimeType: 'text/markdown' }, async (ctx) => {
+  await ctx.reply({ text: '# Summary\n…', mimeType: 'text/markdown' });
+});
+
+bot.cmd({ name: 'ping' }, async (ctx) => {   // no mimeType — displays as text/plain
+  await ctx.reply({ text: 'pong' });
+});
+```
+
+The declaration is **advertising-only** — the actual mimeType on the
+wire is whatever `ctx.reply({ mimeType })` passes. Mismatches don't
+crash anything; the bot detail page shows the declared value and the
+consumer renders whatever the runtime reply specifies.
+
+## v0.3.5: Bot Secret env-var rename
+
+The env var name moved from `LHD_API_KEY` to `BOT_SECRET` to disambiguate from
+user-level public-API keys (`lhduser_…`). Rename the env var in your bot's
+deployment — no code change needed if you used the env-var path:
+
+```diff
+- LHD_API_KEY=lhd_live_… node app.js
++ BOT_SECRET=lhd_live_… node app.js
+```
+
+If you pass `apiKey` explicitly into the constructor, no change at all —
+the option name on `BotOptions` is preserved.
+
+## Migrating from v0.2 → v0.3 (gateway pivot)
+
+v0.3 is a breaking change vs v0.2 — the SDK no longer talks to NATS directly. It opens a WebSocket to the managed gateway and auths with a per-bot Bot Secret:
+
+| Was (v0.2)                             | Now (v0.3+)                    |
+| -------------------------------------- | ------------------------------ |
+| `new Bot({ id, natsUrl: 'nats://…' })` | `new Bot({ id, apiKey: '…' })` |
+| `LHD_NATS_TOKEN=… node app.js`         | `BOT_SECRET=… node app.js`     |
+
+Drop the `natsUrl` and `natsToken` options entirely — the SDK figures out the right gateway URL on its own. Use your bot's **Bot Secret** from the dashboard (not the old shared broker token).
+
+## v0.3.x → v0.4 (streaming opt-in)
+
+v0.4 is additive — nothing breaks for bots calling only `ctx.reply()`.
+New surface:
+
+- `new Bot({ …, streaming: true })` to enable `ctx.update()`
+- `streaming: true` inside the command definition to flip the flag per command
+- `ctx.update({ progress?, text?, data?, mimeType? })` — send 1+
+  intermediate frames before `ctx.reply()`
+- `mimeType` on `ctx.reply()` for the existing final-reply path
+
+No env-var changes, no protocol breakage, no upstream re-auth.
+
+## v0.4.0 → v0.4.1 (per-command mimeType)
+
+Additive — no breaking changes. The `mimeType?` field in the command definition
+is optional; bots that ignore it work exactly the same. The SDK auto-builds an
+IDENTIFY-time `commands` array from your registered handlers so the platform can
+display them on the bot detail page.
+
+## v0.14 → v0.15 (object `cmd()`)
+
+**Breaking.** See [MIGRATION.md](./MIGRATION.md) for the full guide.
+
+`cmd()` now takes a **command definition object** as its first argument. The
+string-form is removed.
+
+```diff
+- bot.cmd("ping", async (ctx) => { … })
++ bot.cmd({ name: "ping" }, async (ctx) => { … })
+
+- bot.cmd("analyze", { streaming: true }, async (ctx) => { … })
++ bot.cmd({ name: "analyze", streaming: true }, async (ctx) => { … })
+```
+
+## License
+
+MIT