@boldare/askdare 0.0.0-stage → 0.1.0-rc.1

package/docs/costs.md

@@ -0,0 +1,181 @@
+# Costs
+
+Every message in the chat spends tokens in your OpenAI project, and anyone on the internet can send messages. This page shows the most a deployment can spend under the default limits, and the settings that change that number.
+
+Prices change often, so this page counts tokens, seconds and files. To turn them into money, multiply by your model's current prices on [OpenAI's pricing page](https://developers.openai.com/api/docs/pricing).
+
+## What you pay for
+
+| What | OpenAI bills | What bounds it in askdare |
+| --- | --- | --- |
+| Messages | Input and output tokens. Reasoning tokens are billed as output tokens | Daily token budgets per bot, per IP and optionally for all bots |
+| Knowledge base | Retrieved chunks as input tokens, a fee per file search call, and vector store storage per GB per day above a free allowance | Only the tokens are in the budgets |
+| Attachments | Images and PDF pages as input tokens, when they are sent | The token budgets, plus upload limits |
+| Voice input | Transcription, per minute of audio (some models bill by tokens instead) | Daily speech budgets in seconds |
+| `askdare doctor` | A 16-token response, plus one second of transcription for bots with voice, per bot and run | 3 runs a minute for the whole app |
+
+## The worst case under the default limits
+
+These defaults bound spending. All of them can be changed in `limits` ([Configuration](configuration.md#limits)).
+
+| Limit | Default | Counted per |
+| --- | --- | --- |
+| `dailyTokens` | 2,000,000 input plus output tokens | bot, per UTC day |
+| `dailyTokensPerIp` | 200,000 input plus output tokens | client IP and bot, per UTC day |
+| `globalDailyTokens` (in `createChatHandler`) | none | all bots, per UTC day |
+| `maxOutputTokens` | 1,024 | model call |
+| `maxSteps` | 5 model calls | message |
+| `maxInputChars` | 4,000 characters | message |
+| `maxTurns` | 50 messages | conversation |
+| `messagesPerVisitorPerMinute` | 10 | visitor |
+| `messagesPerIpPerMinute` | 30 | client IP |
+| `voiceSecondsPerDay` | 3,600 seconds | bot, per UTC day |
+| `voiceSecondsPerIpPerDay` | 600 seconds | client IP and bot, per UTC day |
+| `uploadsPerDay` | 500 files | bot, per UTC day |
+| `attachments.maxBytes` | 4,000,000 bytes | file |
+
+### Tokens
+
+The bot's daily budget is the ceiling, however many visitors there are:
+
+```text
+one bot, one day           2,000,000 tokens
+one IP, one day              200,000 tokens  (10 IPs use up the bot's budget)
+one bot, 30 days      30 × 2,000,000 = 60,000,000 tokens
+three bots, one day    3 × 2,000,000 =  6,000,000 tokens  (unless you set globalDailyTokens)
+```
+
+The budget counts input, cached input and output tokens alike, but OpenAI prices them differently. For a ceiling in money, use the highest per-token price of your model:
+
+```text
+ceiling per bot per day    = 2,000,000 / 1,000,000 × highest price per 1M tokens
+                           = 2 × highest price per 1M tokens
+ceiling per bot per 30 days = 60 × highest price per 1M tokens
+```
+
+Real spending is lower whenever some of the tokens are cheaper input or cached input. The ceiling is what an attacker with ten or more IP addresses can make you pay every day.
+
+### Speech
+
+```text
+one bot, one day            3,600 seconds = 60 minutes
+one IP, one day               600 seconds = 10 minutes
+one bot, 30 days       30 × 60 minutes    = 1,800 minutes
+```
+
+Multiply by the transcription model's price per minute.
+
+### Files
+
+Uploads cost no tokens until they are sent, and sent files count against the token budgets. They do take up storage in your OpenAI project:
+
+```text
+one bot, one day      500 files × 4 MB = 2 GB
+files expire after 30 days, so at most 30 × 500 = 15,000 files (60 GB) per bot at once
+```
+
+Check OpenAI's pricing page for how file storage is billed.
+
+## When spending can go over the budget
+
+The budgets are checked before each message. A few things let the real number end up higher:
+
+- **Several instances with the default store.** Counters live in each instance's memory, so every instance allows the full budget, and a restart or deployment resets them. With more than one instance, use `@boldare/askdare-upstash` ([Going public](going-public.md#4-rate-limits-across-instances)).
+- **A message can use somewhat more than it reserved.** Before each model call, askdare reserves an estimate of that call against every budget:
+
+  ```text
+  one call = input tokens of the previous message in this conversation
+           + characters of the instructions, message and page context / 2
+           + maxOutputTokens
+           + tokens of the attached files
+           + maxResults × 800 (with a knowledge base)
+  ```
+
+  The first call is reserved before the message starts. A bot with tools reserves one more call before each round of tool calls; when a budget can't hold it, the model answers without tools instead. When the message ends, the reservations are replaced by the real usage. Tool results and the model's own earlier output in the same message aren't in the estimate, so the counter can end slightly above the budget; the next message is then refused.
+- **A message that fails, or is cut off by `turnTimeoutMs`, stays charged at its estimate,** whatever it really cost.
+- **Dictations in progress** can go over the day's speech budget once, before further dictation is blocked.
+- **The budgets count tokens only.** File search call fees, vector store storage, file storage, `doctor` runs and `kb sync` are not in them.
+
+## The OpenAI hard limit
+
+The budgets are the main cost control. The backstop is a **monthly budget with "Enforce a hard limit"** on the OpenAI project, with email alerts ([Going public](going-public.md#1-openai-project)). Set it a little above what your askdare budgets allow in a month, so that the budgets stop spending first and the hard limit catches anything they miss.
+
+When the project reaches its limit, OpenAI refuses requests. Visitors see "The assistant is temporarily unavailable. Please try again." (`upstream_error`), and `npx @boldare/askdare doctor` reports "The OpenAI project is out of credit or reached its spend limit."
+
+## Budgets reset at midnight UTC
+
+Daily budgets count per UTC day and reset at 00:00 UTC, not at midnight where you are. A visitor who hits one sees "The assistant is unavailable for the rest of the day." (`budget_exceeded`), with a `Retry-After` header that counts down to 00:00 UTC.
+
+Rate limits work differently: each window (a minute or an hour) starts with the first request it counts.
+
+## Setting the budgets
+
+1. Decide what a day may cost, per bot.
+2. Divide it by your model's highest per-token price. That is `dailyTokens`.
+3. Decide how much of it one visitor's IP may take. The default is a tenth (`dailyTokensPerIp`).
+4. With several bots, cap them together with `globalDailyTokens` in `createChatHandler`.
+5. Run a few typical conversations and compare the usage in the OpenAI dashboard with your estimate. Adjust after the first days of real traffic.
+
+```ts
+defineBot({
+  // …
+  limits: { dailyTokens: 1_000_000, dailyTokensPerIp: 50_000 },
+});
+
+export const { GET, POST, DELETE } = createChatHandler({
+  bots,
+  limits: { globalDailyTokens: 3_000_000 },
+});
+```
+
+## Choosing a model
+
+The model decides most of the bill, which is why askdare never picks one for you.
+
+- **Smaller, cheaper models** are often enough for answers from your documents and short questions. Start with the cheapest model that answers your test questions well.
+- **Reasoning models** think before they answer. Their reasoning tokens are billed as output tokens and count toward `maxOutputTokens`. askdare doesn't set a reasoning effort, so the model's default applies.
+- Put only the model you chose on the project's model allowlist, so a changed config can't switch to a more expensive one by accident.
+
+## `maxOutputTokens` and reasoning
+
+`limits.maxOutputTokens` (default 1,024) caps each model call's output, reasoning included.
+
+- Raising it raises the most a single call can cost, and the reservation of every message.
+- Lowering it too far cuts answers off. With a reasoning model, the reasoning can use up the whole limit before any visible text: OpenAI still bills the input and reasoning tokens, and the visitor gets an empty or cut-off answer.
+
+## Long conversations
+
+A conversation is stored by OpenAI, and every message sends the whole conversation to the model as input. Each message therefore costs more than the one before.
+
+- `maxTurns` (default 50) ends a conversation: the visitor is asked to start a new one.
+- askdare sends `truncation: 'auto'`. When a conversation outgrows the model's context window, OpenAI drops the oldest items instead of failing.
+- askdare doesn't compact or summarize conversations yet. OpenAI's server-side compaction is planned for 0.2.
+- Attached files and your tools' results stay in the conversation, so every later message reads them again. Keep tool results small ([Tools](tools.md)).
+
+## Prompt caching
+
+OpenAI caches the beginning of prompts automatically on supported models, and cached input tokens are billed at a lower rate. A cached part can only be reused when everything before it is identical.
+
+- askdare sends `prompt_cache_key: "askdare:<bot id>"`, the same for every visitor of a bot, so their requests can share a cache.
+- Start the instructions with text that is the same for every visitor. Put what varies, such as the locale or a signed-in user's name, at the end.
+- Keep the tool list stable. askdare already keeps it the same on every model call of a message.
+
+askdare's budgets count cached tokens in full, so they overestimate the cost when caching works. OpenAI's [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) lists the minimum prompt length that can be cached.
+
+## Knowledge base
+
+- `knowledge.maxResults` (default 5) is how many chunks the model reads per search. askdare reserves 800 tokens per chunk, 4,000 per message by default.
+- Each file search call has its own fee, and the vector store is billed for storage per GB per day above a free allowance. Neither is in askdare's budgets. askdare doesn't limit how many searches the model makes per message; the token budget limits them indirectly, because every search adds input tokens.
+- See [Knowledge base](knowledge-base.md).
+
+## Attachments
+
+- askdare reserves about 1,500 tokens per image and 2,000 per PDF page before the message. A 50-page PDF reserves 100,000 tokens, half of the default `dailyTokensPerIp`.
+- Every model call reads the files again. A bot with tools reserves the files once per call it actually makes, so a large PDF can mean the model answers without calling tools when the visitor's budget can't hold another call.
+- Keep attachments off for bots that don't need them, and lower `maxPdfPages` if long PDFs aren't expected. See [Attachments](attachments.md).
+
+## Voice input
+
+- Transcription is billed per minute of audio for models that report a duration. askdare reserves `voice.maxSeconds` (default 60) per dictation and then charges the duration OpenAI reports.
+- Models billed by tokens report no duration. askdare then charges the longest audio the recording could hold, so prefer a model billed by duration.
+- A dictation OpenAI refuses with an error isn't charged against the speech budget. See [Voice input](voice-input.md).

package/docs/custom-store.md

@@ -0,0 +1,259 @@
+# Custom rate-limit store
+
+Rate limits and budgets are counters, and the counters live in a store. The default store keeps them in the memory of each server process. That works for one instance. With more instances (Vercel, several Heroku dynos, autoscaling), each one counts on its own, so visitors get a multiple of every limit.
+
+`@boldare/askdare-upstash` is the shared store that askdare ships. Write your own when you want the counters in a database you already run.
+
+`RateLimitStore` and `CounterHit` are public API ([ADR-0006](https://github.com/boldare/askdare/blob/main/docs/adr/0006-support-matrix-and-versioning.md)). Import them as types from `@boldare/askdare`.
+
+## The interface
+
+```ts
+interface RateLimitStore {
+  hit(key: string, windowMs: number, amount: number): Promise<CounterHit>;
+  readonly shared: boolean;
+}
+
+interface CounterHit {
+  /** Counter value after the increment. */
+  readonly count: number;
+  /** Milliseconds until the window resets. */
+  readonly resetMs: number;
+}
+```
+
+## `hit(key, windowMs, amount)`
+
+Each key is one counter with a fixed window. `hit` adds `amount` to the counter and returns the result.
+
+| Situation | What `hit` does |
+| --- | --- |
+| No open window for `key` (a new key, or its window has ended) | Starts a new counter at `amount`, with a window that ends `windowMs` milliseconds from now. |
+| An open window | Adds `amount`. The window keeps its end, whatever `windowMs` this call passes. |
+| `amount` is `0` | Reads. Returns the count without changing it, `0` when no window is open. |
+| `amount` is negative | Refunds: the count goes down by that much. Don't clamp it at zero. |
+
+The result:
+
+| Field | Meaning |
+| --- | --- |
+| `count` | The counter after this call's `amount` is added. askdare compares it with the limit. |
+| `resetMs` | Milliseconds until the window ends: more than 0, and at most `windowMs` for a window that this call opened. askdare uses it for the `Retry-After` of a `rate_limited` answer, and waits at least one second. |
+
+askdare uses refunds to give back a reservation. A turn reserves an estimate against each token budget. When the turn ends, askdare adds the difference between the real usage and the estimate, which is often negative. When a reservation would cross a budget, askdare refunds it from every budget it has already charged.
+
+### Rules
+
+- **Atomic per key.** Concurrent calls for the same key must all count, and each must see its own result. askdare reserves budgets with `hit` and checks the returned count, so a lost update lets concurrent turns overshoot a budget. Use one atomic operation, such as Redis `INCRBY` or an SQL upsert with `RETURNING`.
+- **Keys are independent.** askdare never needs a change across several keys at once.
+- **Whole numbers.** Amounts are always integers. Token budgets reach millions, so store counts as 64-bit integers.
+- **Opaque keys.** Don't parse keys: their format is internal and may change. Some are longer than 100 characters. Some contain client IP addresses, so treat the store as personal data and keep keys out of your logs.
+- **Windows** range from one minute to 30 days. You can delete a counter once its window has ended.
+- **Fail loudly.** If `hit` throws or rejects, the request fails with `internal_error` (status 500), and `onError` receives it. Never catch an error and return a zero count: that turns every limit off. The default store does the same when it runs out of room: it drops expired and short-lived counters first, and refuses requests rather than forget what a budget has spent.
+- **One round trip.** Each message calls `hit` several times, mostly one after another. Keep each call to one request to your database.
+
+## The `shared` flag
+
+`shared` says whether every server instance sees the same counters. It doesn't change how limits are enforced. It only changes two warnings:
+
+- When `shared` is `false` and `NODE_ENV` is `production`, `createChatHandler` logs a warning as the route loads: `[askdare] Rate limits are kept in memory, per instance. With more than one instance, use a shared store such as @boldare/askdare-upstash.`
+- `npx @boldare/askdare doctor` warns that rate limits and budgets are kept per instance, unless the app runs in development.
+
+Set `shared: true` only when every instance reaches the same counters, such as a database they all connect to. A store that keeps counters inside the process is `shared: false`, even if you wrote it.
+
+## Example: PostgreSQL
+
+A sketch with the `pg` client. One table holds every counter:
+
+```sql
+CREATE TABLE askdare_counters (
+  key      text        PRIMARY KEY,
+  total    bigint      NOT NULL,
+  reset_at timestamptz NOT NULL
+);
+```
+
+One upsert per call opens, adds to or restarts a window. PostgreSQL locks the row for it, so concurrent calls for a key never lose an update:
+
+```ts
+// lib/postgres-store.ts
+import type { CounterHit, RateLimitStore } from '@boldare/askdare';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const HIT = `
+  INSERT INTO askdare_counters AS c (key, total, reset_at)
+  VALUES ($1, $2, now() + make_interval(secs => $3::float8 / 1000))
+  ON CONFLICT (key) DO UPDATE SET
+    total    = CASE WHEN c.reset_at > now() THEN c.total + EXCLUDED.total ELSE EXCLUDED.total END,
+    reset_at = CASE WHEN c.reset_at > now() THEN c.reset_at ELSE EXCLUDED.reset_at END
+  RETURNING total, ceil(extract(epoch FROM reset_at - now()) * 1000) AS reset_ms`;
+
+export function postgresStore(): RateLimitStore {
+  return {
+    shared: true,
+    async hit(key, windowMs, amount): Promise<CounterHit> {
+      const { rows } = await pool.query<{ total: string; reset_ms: string }>(HIT, [
+        key,
+        amount,
+        windowMs,
+      ]);
+      const row = rows[0];
+      if (!row) throw new Error('postgresStore: the counter upsert returned no row.');
+      return { count: Number(row.total), resetMs: Number(row.reset_ms) };
+    },
+  };
+}
+```
+
+Expired rows do no harm: the next `hit` restarts them. To keep the table small, delete them from a scheduled job:
+
+```sql
+DELETE FROM askdare_counters WHERE reset_at < now();
+```
+
+## Plug it in
+
+Pass the store to `createChatHandler` as `limits.store`:
+
+```ts
+// app/api/chat/[...path]/route.ts
+import { createChatHandler } from '@boldare/askdare/next';
+import { bots } from '@/askdare.config';
+import { postgresStore } from '@/lib/postgres-store';
+
+export const maxDuration = 300;
+
+export const { GET, POST, DELETE } = createChatHandler({
+  bots,
+  limits: { store: postgresStore() },
+});
+```
+
+One store serves every bot of the handler. If several apps share one database, give each its own key prefix, as `upstashStore({ prefix })` does. [Configuration](configuration.md#handler-limits) lists the other `limits` options.
+
+## Test it
+
+The built-in stores share a contract test, but the package doesn't export it. Copy the cases into your own tests:
+
+| Case | Expected |
+| --- | --- |
+| Adds within a window | `hit(k, 60_000, 1)` returns a count of 1, then `hit(k, 60_000, 5)` returns 6. |
+| Reads with `0` | After `hit(k, 60_000, 2)`, two calls of `hit(k, 60_000, 0)` both return 2. |
+| Keeps keys apart | After `hit(c, 60_000, 3)`, `hit(d, 60_000, 1)` returns 1. |
+| Reports the time left | A new window's `resetMs` is more than 0 and at most `windowMs`. |
+| Refunds | After `hit(k, 60_000, 3)`, `hit(k, 60_000, -1)` returns 2. |
+| Restarts after the window | Once the window has passed, the next `hit` starts again from its `amount`. |
+| Never loses an update | 50 parallel calls of `hit(k, 60_000, 1)` return each count from 1 to 50 exactly once. |
+
+The first four are the contract that `@boldare/askdare-upstash` and the in-memory store pass. The rest are tested on the in-memory store and the limits that use it. With Vitest:
+
+```ts
+// lib/postgres-store.test.ts
+import { randomUUID } from 'node:crypto';
+import type { RateLimitStore } from '@boldare/askdare';
+import { describe, expect, it } from 'vitest';
+import { postgresStore } from './postgres-store';
+
+function rateLimitStoreContract(name: string, create: () => RateLimitStore): void {
+  describe(`${name} (RateLimitStore contract)`, () => {
+    // A fresh prefix per run, so counters from earlier runs don't interfere.
+    const run = randomUUID();
+    const key = (id: string): string => `contract:${run}:${id}`;
+
+    it('adds amounts within a window', async () => {
+      const store = create();
+      expect((await store.hit(key('a'), 60_000, 1)).count).toBe(1);
+      expect((await store.hit(key('a'), 60_000, 5)).count).toBe(6);
+    });
+
+    it('reads without changing when the amount is 0', async () => {
+      const store = create();
+      await store.hit(key('b'), 60_000, 2);
+      expect((await store.hit(key('b'), 60_000, 0)).count).toBe(2);
+      expect((await store.hit(key('b'), 60_000, 0)).count).toBe(2);
+    });
+
+    it('keeps keys independent', async () => {
+      const store = create();
+      await store.hit(key('c'), 60_000, 3);
+      expect((await store.hit(key('d'), 60_000, 1)).count).toBe(1);
+    });
+
+    it('reports the time left in the window', async () => {
+      const store = create();
+      const { resetMs } = await store.hit(key('e'), 60_000, 1);
+      expect(resetMs).toBeGreaterThan(0);
+      expect(resetMs).toBeLessThanOrEqual(60_000);
+    });
+
+    it('refunds negative amounts', async () => {
+      const store = create();
+      await store.hit(key('f'), 60_000, 3);
+      expect((await store.hit(key('f'), 60_000, -1)).count).toBe(2);
+    });
+
+    it('starts a new window once the old one has passed', async () => {
+      const store = create();
+      await store.hit(key('g'), 1_000, 3);
+      await new Promise((resolve) => setTimeout(resolve, 1_100));
+      expect((await store.hit(key('g'), 1_000, 1)).count).toBe(1);
+    });
+
+    it('never loses a concurrent update', async () => {
+      const store = create();
+      const hits = await Promise.all(
+        Array.from({ length: 50 }, () => store.hit(key('h'), 60_000, 1)),
+      );
+      expect(hits.map((hit) => hit.count).sort((a, b) => a - b)).toEqual(
+        Array.from({ length: 50 }, (_, index) => index + 1),
+      );
+    });
+  });
+}
+
+rateLimitStoreContract('postgresStore', () => postgresStore());
+
+describe('postgresStore', () => {
+  it('is shared across instances', () => {
+    expect(postgresStore().shared).toBe(true);
+  });
+});
+```
+
+Run these tests against a real database. A mock can't show that concurrent updates are atomic.
+
+## The reference implementation
+
+`@boldare/askdare-upstash` stores the counters in Upstash Redis over HTTPS, so it works on Vercel and Heroku alike. Read it before you write your own.
+
+```bash
+npm install @boldare/askdare-upstash @upstash/redis
+```
+
+```ts
+import { createChatHandler } from '@boldare/askdare/next';
+import { upstashStore } from '@boldare/askdare-upstash';
+import { bots } from '@/askdare.config';
+
+export const { GET, POST, DELETE } = createChatHandler({
+  bots,
+  limits: { store: upstashStore() },
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `redis` | created from `url` and `token` | An existing `@upstash/redis` client. |
+| `url` | `UPSTASH_REDIS_REST_URL`, else `KV_REST_API_URL` | The database's REST URL. |
+| `token` | `UPSTASH_REDIS_REST_TOKEN`, else `KV_REST_API_TOKEN` | The database's REST token. |
+| `prefix` | `'askdare:'` | Key prefix, to share one database between apps. |
+
+How it meets the rules:
+
+- Each `hit` runs one Lua script in one round trip. Redis runs a script atomically.
+- The script adds `amount` with `INCRBY`, then reads the key's time to live with `PTTL`. Only a key without one gets `PEXPIRE` with `windowMs`. So an open window keeps its end, and a key that expired starts again.
+- It returns the count and the time to live as `resetMs`.
+- It reads the URL and token on first use, not at import, so `next build` doesn't need them. Without them, the first `hit` throws, and the request fails.
+- `shared` is `true`.

package/docs/deployment.md

@@ -0,0 +1,76 @@
+# Deployment
+
+askdare runs wherever Next.js runs on Node.js. It needs no database: conversations live in OpenAI, and your app only stores signed tokens in the visitor's browser. These are the steps for Vercel and Heroku. Before the chat is public, also work through the [going-public checklist](going-public.md).
+
+## What every deployment needs
+
+| Variable | Notes |
+|---|---|
+| `OPENAI_API_KEY` | A key from the OpenAI project for **this** environment. Use separate projects for development and production. |
+| `CHAT_SECRET` | A new secret per environment: `openssl rand -base64 32`. Don't reuse the one from `.env.local`. |
+| `ASKDARE_MODEL` | If your config reads the model from it, as the `init` template does. |
+| `IDENTITY_SECRET` | Only for [signed-in visitors](identity.md). Shared with your site's backend, different from `CHAT_SECRET`. |
+| `KB_VECTOR_STORE_ID` | Only with a knowledge base. Vector stores belong to one OpenAI project, so run `kb sync` with the production key to get the production store. |
+
+Set them in your host's settings, never in files you commit.
+
+## Vercel
+
+1. Import the repository in Vercel. The defaults for Next.js are right.
+2. Add the variables above under **Settings → Environment Variables**, for Production and Preview. `next build` fails without `ASKDARE_MODEL`, so every environment that builds the app needs it. `vercel env pull .env.local` copies the development values to your machine.
+3. **Share the rate limits.** Vercel runs many instances at once, and the default limits are kept per instance. Create a Redis database at [Upstash](https://upstash.com/) (also available in the Vercel Marketplace) and use the add-on:
+
+   ```bash
+   npm install @boldare/askdare-upstash
+   ```
+
+   ```ts
+   // app/api/chat/[...path]/route.ts
+   import { upstashStore } from '@boldare/askdare-upstash';
+
+   export const { GET, POST, DELETE } = createChatHandler({
+     bots,
+     limits: { store: upstashStore() }, // UPSTASH_REDIS_REST_URL and _TOKEN, or KV_REST_API_URL and _TOKEN
+   });
+   ```
+
+4. Keep `export const maxDuration = 300` in the route file. That is the longest a streamed answer may take; each bot's `limits.turnTimeoutMs` (120 s by default) must stay below it.
+5. Deploy, then check the live app:
+
+   ```bash
+   npx @boldare/askdare doctor --url https://your-app.vercel.app --env-file .env.production.local
+   ```
+
+   `doctor` signs its request with `CHAT_SECRET`, so the file must hold the production secret. Keep it out of git; `init` already ignores `.env*.local`.
+
+Requests to Vercel functions can be at most 4.5 MB, so keep `attachments.maxBytes` at its default of 4 MB or lower.
+
+## Heroku
+
+1. Create the app and set the Node.js version in `package.json`:
+
+   ```json
+   { "engines": { "node": "24.x" } }
+   ```
+
+2. Add a `Procfile`. The longer keep-alive outlasts Heroku's router, so connections aren't cut mid-answer:
+
+   ```text
+   web: next start --port $PORT --keepAliveTimeout 95000
+   ```
+
+3. Set the variables above under **Settings → Config Vars** in the dashboard. Typing the key into `heroku config:set` would leave it in your shell history.
+4. **One dyno** works with the default limits. With more dynos, share the limits with `@boldare/askdare-upstash`, as for Vercel.
+5. Deploy, then check it:
+
+   ```bash
+   npx @boldare/askdare doctor --url https://your-app.herokuapp.com --env-file .env.production.local
+   ```
+
+Heroku closes a request that sends nothing for 30 seconds at first, and 55 seconds after that. askdare sends the first byte at once and a heartbeat every 15 seconds, so slow answers survive.
+
+## Behind another proxy or CDN
+
+- Don't buffer `text/event-stream` responses; askdare sends `X-Accel-Buffering: no` for nginx.
+- Each proxy adds itself to `X-Forwarded-For`. With more than the host's own proxy in front of the app, set `limits.trustProxy` in `createChatHandler` to the number of proxies, or per-IP limits count the proxy instead of the visitor.
+- Leave `/api/chat` out of `proxy.ts`, of `headers()` in `next.config`, and of any CDN rule that sets `X-Frame-Options`, a Content Security Policy or cookies. `doctor` reports each of these.