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

package/docs/migrating-from-openai-assistant.md

@@ -0,0 +1,43 @@
+# Migrating from @boldare/openai-assistant
+
+`@boldare/openai-assistant` stopped working on 2026-08-26, when OpenAI shut down the Assistants API it was built on. askdare is its successor from the same team, but not a new version of it: the old library was a NestJS module with an Angular widget, and askdare is a Next.js library on the Responses API. There is no upgrade in place. You move your assistant's setup into a Next.js app instead.
+
+Most deployments take an afternoon. The assistant's instructions, its tools and its knowledge files carry over. Old conversations don't: they lived in Assistants API threads, which can no longer be read.
+
+## What maps to what
+
+| openai-assistant 1.x | askdare |
+|---|---|
+| `AssistantModule.forRoot(config)` in a NestJS app, plus `ASSISTANT_ID` | `defineBot({...})` in `askdare.config.ts`, served by `createChatHandler({ bots })` from one Next.js route. There is no assistant object at OpenAI to create or keep in sync. |
+| Agents extending `AgentBase`, with arguments as a raw JSON string | `defineTool` with a Zod schema. Arguments are validated before your code runs, and each call has a timeout. See [Tools](tools.md). |
+| Threads, `ThreadsController` | Conversations in the OpenAI Conversations API. The visitor's browser keeps only a signed token. No database. |
+| socket.io `ChatGateway`, raw Assistants stream events | Server-sent events over `POST`, in askdare's own versioned [protocol](protocol.md). |
+| Run polling | Streaming Responses API calls, with limits on tool steps and a deadline per turn. |
+| Knowledge files uploaded at startup, `.env` rewritten at runtime | `npx @boldare/askdare kb sync <folder>`, run when the files change. It prints the vector store ID once; the app only reads `KB_VECTOR_STORE_ID`. See [Knowledge base](knowledge-base.md). |
+| `FilesController` | Image and PDF attachments, checked by file type and size, and referenced by signed handles. See [Attachments](attachments.md). |
+| `whisper-1` speech to text | Voice input with a transcription model you choose. See [Voice input](voice-input.md). |
+| `tts-1` text to speech | Not available. OpenAI is retiring its text-to-speech models. |
+| Annotations resolved with a file lookup per citation | Citations with a title and a link to your page, set by `kb sync`. |
+| The `ai-embedded` iframe and its `postMessage` | One `<script>` tag. The chat runs in an iframe that only the sites in `allowedOrigins` may embed. See [Embedding](embedding.md). |
+| Angular widget configured at build time | Widget settings in `defineBot({ widget })`: four themes, English and Polish texts, your own CSS. See [Styling](styling.md) and [Themes](themes.md). |
+| No sign-in, CORS open to every origin | Short-lived session tokens, rate limits, daily token budgets and an origin allowlist by default. See [Going public](going-public.md). |
+
+## Steps
+
+1. **Pick the Next.js app** that will serve the chat: an existing Next.js 16 app with the App Router, or a new one from the [starter](https://github.com/boldare/askdare/tree/main/examples/starter). Your other sites embed the chat from there, so it needn't be the site visitors see.
+2. **Add askdare** as [Getting started](getting-started.md) describes: `npm install @boldare/askdare zod`, then `npx @boldare/askdare init`.
+3. **Move the assistant's setup** into `askdare.config.ts`:
+   - your instructions go into `instructions`;
+   - the model goes into `ASKDARE_MODEL`. Pick a current one: the models your old assistant used may be retired;
+   - the greeting, starter questions and colors go into `widget`.
+4. **Rewrite each agent as a tool.** The handler body usually stays as it is. Replace the JSON string parsing with a Zod schema, and return a plain object instead of a string. Read the [Tools](tools.md) guide first: a tool must never trust IDs that the model chose.
+5. **Sync the knowledge files:** `npx @boldare/askdare kb sync <folder>`, then set `KB_VECTOR_STORE_ID`. Add a `url` per file if citations should link to your pages.
+6. **Replace the embed code** on your sites with the askdare script tag, and list those sites in `security.allowedOrigins`.
+7. **Check and deploy.** `npx @boldare/askdare doctor` checks the key, the model and the headers. [Deployment](deployment.md) covers Vercel and Heroku.
+8. **Remove the old service** and its NestJS module. Delete the old assistant's files and vector stores in the OpenAI dashboard if you no longer need them.
+
+## What you lose
+
+- **Old conversations.** Threads from the Assistants API can't be read any more, so there is nothing to import.
+- **Text to speech.** Answers are text. Dictation (speech to text) is still there.
+- **Assistants edited in the OpenAI dashboard.** Instructions now live in your code, so they are versioned and reviewed like the rest of it.

package/docs/privacy.md

@@ -0,0 +1,175 @@
+# Privacy
+
+This page lists what data the chat handles, where it goes and how long it stays, so you can write your privacy notice. It describes what askdare does; it isn't legal advice. Your instructions, your tools and your hosting can add data of their own.
+
+## At a glance
+
+| Data | Where | How long |
+| --- | --- | --- |
+| A handle to the current conversation (resume token) | The visitor's browser: `localStorage` of your app's origin, inside the chat's iframe | Until the visitor starts a new conversation; it works for at most 30 days |
+| A session token | The iframe's memory, never stored | 15 minutes |
+| Messages, answers, page context, tool calls and their results | OpenAI, as a conversation in your project | Until deleted |
+| Model responses | OpenAI | OpenAI's retention for stored responses |
+| Uploaded images and PDFs | OpenAI, as files in your project | 30 days, or until the conversation is deleted |
+| Dictations | Sent to OpenAI for transcription | askdare keeps no audio |
+| IP addresses, visitor IDs, conversation IDs | Rate-limit counters, in your server's memory or in Upstash | IP addresses up to 2 days, conversation IDs up to 30 days |
+| An HMAC of the visitor or user ID (`safety_identifier`) | Sent to OpenAI with every model request | OpenAI's retention |
+| Error reports | Your server log, or your `onError` function | Your hosting's log retention |
+
+## In the visitor's browser
+
+The script on your site (`widget.js`) adds the chat button and an iframe. It stores nothing on your site and sets no cookies. The chat itself runs inside the iframe, on your app's origin:
+
+- Its Content Security Policy lets it load scripts, styles, fonts and images only from your app, and talk only to your app. Images in answers are never loaded; the chat shows their alt text.
+- The iframe is loaded with `referrerpolicy="strict-origin"`, so your app learns which site embeds the chat, but not which page.
+
+### What it stores
+
+After the visitor's first message, the chat writes one entry to `localStorage`, in the iframe's storage for your app's origin. Nothing is written before that.
+
+| | |
+| --- | --- |
+| Key | `askdare:<bot id>:resume` for an anonymous visitor; `askdare:<bot id>:resume:<key>` for a [signed-in visitor](identity.md), where `<key>` is 32 hexadecimal characters derived from the bot and user ID with `IDENTITY_SECRET`. It reveals nothing about the user |
+| Value | An encrypted token with the visitor ID and a reference to the conversation. The browser can't read it |
+| Purpose | To show and continue the conversation after a reload |
+| Lifetime | It works for 30 days after the last answer in the conversation: each answer renews it. It is removed when the visitor starts a new conversation, and when the server says the conversation is gone or the token expired |
+
+Everything else stays in memory and disappears with the page: the session token, which lasts 15 minutes, and a signed-in visitor's identity.
+
+The chat sets no cookies. Browsers may partition or block storage in iframes from other sites; then the conversation doesn't survive a reload, and the chat still works. There is no setting to turn the entry off.
+
+### Consent banners
+
+Whether this entry needs the visitor's consent under the rules that apply to you, such as the ePrivacy Directive in the EU, is for you and your legal advisers to decide. These facts are often relevant:
+
+- It is written only after the visitor sends a message, and only to continue that conversation.
+- It isn't used for tracking, analytics or advertising, and it isn't shared with other sites.
+- It contains no readable personal data, and it stops working after 30 days at most.
+
+## On your server
+
+askdare needs no database. Your app keeps only rate-limit counters.
+
+### IP addresses
+
+- The client IP is used for rate limits and budgets only, never to identify anyone.
+- It isn't hashed. IPv4 addresses are kept whole; IPv6 addresses are cut to their /64 network. They are part of counter names, such as `ask:ti:<bot id>:<ip>:<date>`.
+- The counters live in the server's memory by default, in your Upstash database with `@boldare/askdare-upstash`, or in your own [store](custom-store.md).
+- Each counter lasts as long as its window: from a minute up to 2 days for the daily budgets. Upstash deletes a counter when its window ends. The memory store drops expired counters within a minute, and everything when the process restarts.
+
+### Visitor IDs
+
+The server gives every new visitor a random ID: `v_` followed by 32 hexadecimal characters. It never comes from the browser, and it identifies a chat in one browser, not a person. It travels inside the encrypted tokens, names some rate-limit counters, and is stored with the conversation at OpenAI.
+
+### Logs
+
+- askdare never logs message contents, and cuts API keys down to their prefix.
+- It logs one line per server error: the error code, an explanation of setup problems, and the underlying error, such as OpenAI's status, error code and request ID. It also logs the ID of an uploaded file it couldn't delete.
+- Errors thrown by your own tools are logged as they are. Keep personal data out of their messages.
+- With `onError` in `createChatHandler`, the same reports go to your function, for example to Sentry, instead of the log.
+- Your hosting provider may log every request, IP addresses included, according to its own settings.
+
+### `safety_identifier`
+
+Every model request carries a `safety_identifier`, so OpenAI can trace abuse to one end user instead of to your whole project.
+
+- For an anonymous visitor, it is an HMAC of the random visitor ID.
+- For a signed-in visitor, it is an HMAC of `user:` followed by your user ID, so it is the same on every device.
+
+The HMAC key is derived from `CHAT_SECRET`, so knowing a user ID isn't enough to compute it. It is still a pseudonym, not anonymous data: with the secret, the link to a user can be restored. It changes when `CHAT_SECRET` rotates.
+
+## At OpenAI
+
+Everything below lives in the OpenAI project whose key the app uses. Name OpenAI in your privacy notice.
+
+### What each message sends
+
+- Your instructions for that request, with whatever you put in them, such as a signed-in user's name.
+- The visitor's message, and the page context from `askdare('configure')` if the bot has `pageContext: true`.
+- Attached files, by reference.
+- Your tools' definitions and, when the model calls them, their results.
+- The `safety_identifier`, and `prompt_cache_key: "askdare:<bot id>"`, which holds no personal data.
+
+### Conversations
+
+- Conversations are stored with OpenAI's Conversations API, in your project, **until they are deleted** ([ADR-0003](https://github.com/boldare/askdare/blob/main/docs/adr/0003-conversation-state.md)). Each one carries the bot ID and the visitor ID as metadata (`askdare_bot`, `askdare_visitor`).
+- A conversation holds the visitor's messages, the page context, the answers, and the tool calls with their results. The instructions are sent with each request rather than stored in the conversation.
+- **The visitor can delete it.** "Start a new conversation" asks "Start a new conversation? The current one will be deleted." and then deletes it at OpenAI. For bots with attachments, the files attached in it are deleted too; a file that fails to delete expires on its own.
+- **Nothing else deletes it.** When the browser's handle expires after 30 days, or the visitor clears the browser, the conversation stays in your project. askdare keeps no list of conversations, and OpenAI's API has no endpoint to list them, so there is no tool to find, export or delete one visitor's conversation. Take this into account in your retention decision ([Going public](going-public.md#6-privacy-and-transparency)).
+- **Who can read it:** whoever uses the same browser can continue an anonymous conversation and see its history while the handle works. On a shared computer, that includes the next person, unless the visitor started a new conversation. A conversation started while signed in is shown only to that user ([Signed-in visitors](identity.md)).
+
+### Responses
+
+askdare stores each model response (`store: true`), because a conversation needs it. A stored response includes the instructions it was given. OpenAI's [data controls](https://developers.openai.com/api/docs/guides/your-data) list 30 days by default for this stored state of the Responses API, and up to 30 days for abuse monitoring logs. Check that page for the current terms.
+
+### Uploaded files
+
+- Files are uploaded with purpose `user_data` and `expires_after` set to 30 days from the upload. OpenAI deletes them then, or askdare deletes them earlier with their conversation.
+- Files that are uploaded but never sent stay until they expire.
+- The widget re-encodes images in the browser, which drops EXIF data such as the GPS position. PDFs are uploaded as they are.
+- The file name goes to OpenAI too, cleaned of unusual characters.
+- Files are never served back to browsers. See [Attachments](attachments.md).
+
+### Dictations
+
+The recording goes to OpenAI's transcription API and nowhere else, and askdare stores no audio. The transcript lands in the message field; it reaches the conversation only if the visitor sends it. See [Voice input](voice-input.md).
+
+### Zero Data Retention
+
+askdare doesn't use Zero Data Retention. OpenAI grants it only after approval, and its data controls page lists the Conversations API as not eligible. Clients who need zero retention or data residency need the planned own-storage add-on.
+
+## AI disclosure
+
+By default, the chat shows under the message field: "You’re chatting with an AI assistant. It can make mistakes." (`disclosure.text`).
+
+```ts
+defineBot({
+  // …
+  widget: {
+    disclosure: { privacyUrl: 'https://www.example.com/privacy' }, // or a path such as '/privacy'
+  },
+});
+```
+
+- `privacyUrl` adds a "Privacy policy" link (`disclosure.privacy`). It must be an https URL or a path on your app.
+- You can change both texts with `widget.texts` ([Styling](styling.md#1-configuration)).
+- `disclosure: false` hides the note. Do that only when your page already tells visitors they are talking to an AI.
+
+The note exists for the transparency duty in Article 50 of the EU AI Act: people should know when they interact with an AI system, unless that is obvious from the context. Who carries the duty, and whether the default note is enough for your site, depends on your role and setup. Check with your legal advisers.
+
+## Subprocessors
+
+| Who | When | What they receive |
+| --- | --- | --- |
+| OpenAI | Always | Everything under [At OpenAI](#at-openai) |
+| Upstash | With `@boldare/askdare-upstash` | Rate-limit counters, whose names hold IP addresses, visitor IDs and conversation IDs |
+| Your hosting provider, such as Vercel or Heroku | Always | Every request to the app, with IP addresses, and the server log |
+| Your error monitoring | With `onError` | Error reports, without message contents or API keys |
+
+Your tools may send data to further services of your own.
+
+## Rotating secrets
+
+### `CHAT_SECRET`
+
+`CHAT_SECRET` encrypts the session tokens, the resume tokens in browsers and the handles of uploaded files.
+
+- **With `CHAT_SECRET_PREVIOUS`:** put the old secret there and set a new `CHAT_SECRET`. Existing tokens keep working, and new ones use the new secret. Remove the old one after 30 days, when the last resume tokens expire ([Going public](going-public.md#2-secrets-and-environment)).
+- **Without it:** every visitor loses access to their current conversation. The chat forgets it and starts a new one at the next message, and files uploaded but not yet sent must be attached again. The old conversations stay in your OpenAI project, and nobody can reach them through the chat any more.
+
+### `IDENTITY_SECRET`
+
+There is no previous-secret setting for `IDENTITY_SECRET`. When you change it:
+
+- Identity tokens signed with the old secret are refused, and those visitors continue anonymously. Change the secret in your site's backend and in the askdare app at the same time.
+- Signed-in visitors with an open chat become anonymous at the next session renewal, within about 15 minutes.
+- Conversations started while signed in are bound to the old secret. Their users can't resume, read or delete them in the chat any more, and they stay in your OpenAI project.
+
+## For your privacy notice
+
+- [ ] Name OpenAI, and Upstash if you use it, as processors, and your hosting provider.
+- [ ] Say that conversations, including what visitors type and attach, are stored by OpenAI until deleted, and how visitors delete them.
+- [ ] Describe the `localStorage` entry and its purpose.
+- [ ] Mention IP addresses in rate limits and their retention.
+- [ ] Decide on a retention policy for conversations.
+- [ ] Keep the AI disclosure, and link this notice from it with `privacyUrl`.

package/docs/protocol.md

@@ -0,0 +1,174 @@
+# Wire protocol (version 1)
+
+This is how the askdare server streams a chat turn to its clients: the embed iframe app now, `@boldare/askdare/react` later. The protocol belongs to askdare; raw OpenAI stream events are never forwarded ([ADR-0002](https://github.com/boldare/askdare/blob/main/docs/adr/0002-openai-only-no-leaked-types.md)).
+
+Source of truth: `packages/askdare/src/protocol/`.
+
+## Endpoints
+
+Every path sits under the route's base path: `/api/chat` by default, or `basePath` in `createChatHandler`. Any other path or method answers `404`.
+
+| Method and path | Token | Purpose |
+| --- | --- | --- |
+| `GET /widget.js` | None | The loader script for your pages. `?bot=<id>` adds that bot's launcher look |
+| `GET /embed/<bot>` | None | The chat document in the iframe. `?lang=<tag>` carries the embedding page's language for `locale: 'auto'`, and `?mode=inline` marks a chat inside the page |
+| `GET /theme/<bot>.css` | None | The bot's theme and `widget.css`, with a content hash in `?v=` |
+| `GET /assets/<file>` | None | The chat's script and stylesheet, and the preset fonts |
+| `POST /session` | None | Starts or renews a visitor's session and answers an access token ([Identity](#identity)) |
+| `POST /messages` | Access token | Sends a message and answers with the event stream ([Events](#events)) |
+| `POST /history` | Access token | The visible messages of the visitor's conversation |
+| `DELETE /conversation` | Access token | Deletes the visitor's conversation, and its files when the bot accepts attachments |
+| `POST /attachments` | Access token | Uploads one file ([Attachments](#attachments)) |
+| `POST /transcriptions` | Access token | Transcribes one dictation ([Dictation](#dictation)) |
+| `POST /doctor` | Doctor token | Checks the setup for `askdare doctor` ([Diagnostics](#diagnostics)) |
+
+- **`POST /messages`** takes `{ "botId", "text", "resumeToken"?, "attachments"?, "context"?, "locale"? }`. Without `resumeToken`, the server starts a new conversation and sends `conversation.created`. `locale` is the visitor's language tag, passed to the bot's instructions.
+- **`POST /history`** takes `{ "botId", "resumeToken" }` and answers `{ "messages": [{ "id", "role", "text", "citations", "attachments" }] }`, where `attachments` is a count.
+- **`DELETE /conversation`** takes the same body and answers `204` with no body.
+- **Same origin only.** Every `POST` and `DELETE` except `/doctor` refuses cross-site requests with `401`. The API serves the chat's own iframe, which runs on the same origin.
+
+## Transport
+
+- **Request:** `POST` with a JSON body and a `Bearer` access token. No cookies.
+- **Response:** Server-Sent Events. Clients read them with `fetch` and a `ReadableStream`, because `EventSource` can't send a POST body.
+- **Response headers:**
+  - `Content-Type: text/event-stream; charset=utf-8`
+  - `Cache-Control: no-cache, no-transform`
+  - `X-Accel-Buffering: no`
+  - `x-askdare-protocol: 1`
+- **Framing:** one event per frame, `event: <type>` followed by `data: <json>` and a blank line. The JSON always repeats `type`.
+- **First byte:** the server sends a comment (`: ok`) before contacting OpenAI. Heroku requires a first byte within 30 s.
+- **Heartbeat:** a `: ping` comment every 15 s, on a timer that is independent of model output. Heroku closes connections after 55 s without bytes.
+
+## Events
+
+| Type | Payload | Meaning |
+|---|---|---|
+| `conversation.created` | `resumeToken` | A new conversation started; store the token to resume it later |
+| `user.ack` | `messageId` | The server accepted the user's message and assigned it this ID |
+| `message.start` | `messageId` | The assistant started a reply |
+| `reasoning` | `messageId`, `state: started \| done` | The model is thinking; show a status, never content |
+| `text.delta` | `messageId`, `delta` | Append text to the reply (markdown) |
+| `citation` | `messageId`, `index`, `title`, `url?` | Source for marker `[index]`; `url` is http(s) only |
+| `tool.status` | `messageId`, `callId`, `name`, `state: running \| done \| error` | A tool ran; arguments and results stay on the server. `name: file_search` is the knowledge base search |
+| `message.end` | `messageId`, `reason`, `resumeToken?` | The reply finished. A resumed conversation gets a fresh `resumeToken`, so it stays reachable 30 days after its last message. Reasons: `completed`, `max_steps`, `max_output_tokens`, `timeout`, `content_filter`, `aborted` |
+| `error` | `code`, `message`, `retryAfterMs?`, `key?`, `params?` | The turn failed; `message` is safe to show ([keys and parameters](#error-keys-and-parameters)) |
+
+## Attachments
+
+When a bot has `attachments` enabled, files travel separately from the message:
+
+1. `POST /attachments` with the raw file as the body (`Content-Type: application/octet-stream`), the `Bearer` token, and two headers: `x-askdare-bot` (bot ID) and `x-askdare-filename` (URL-encoded name). The server detects the type from the bytes, uploads the file to OpenAI and answers `{ "attachment": { "id", "kind": "image" | "pdf", "name", "size" } }`.
+2. `POST /messages` with `"attachments": ["<id>", …]` next to `text`. `text` may be empty when files are attached.
+
+`id` is an encrypted handle bound to the bot and the visitor, valid for 1 hour. OpenAI file IDs never reach clients, and the server refuses raw file IDs. History (`POST /history`) reports only how many files a message had.
+
+## Dictation
+
+When a bot has `voice` enabled, `POST /transcriptions` takes a recording as the raw body (`Content-Type: application/octet-stream`) with the `Bearer` token and two headers: `x-askdare-bot` (bot ID) and `x-askdare-languages` (comma-separated language tags, used as hints). It answers `{ "text": "…" }`. Clients put the text in the message field for the visitor to check; nothing is sent to the model.
+
+## Identity
+
+`POST /session` takes an optional `identityToken`: the JWT from `askdare('identify')`, or `null` to sign out. Without it, a renewal keeps the identity the previous access token had. Widgets send the page's latest token with every session request. The answer adds `identified` (boolean), `identityKey` (an HMAC that tells users apart without revealing them; widgets keep one conversation handle per key), `resumeToken` when signing in adopted an anonymous conversation, and `identityProblem` when a token was refused. A signed-in access token expires with the identity token. Identities travel inside the encrypted access token; clients never see the claims ([ADR-0009](https://github.com/boldare/askdare/blob/main/docs/adr/0009-visitor-identity.md)).
+
+## Diagnostics
+
+`POST /doctor` serves `npx @boldare/askdare doctor`. It takes a 2-minute token that the CLI encrypts with `CHAT_SECRET` and answers with a report on each bot: whether the server's key, models, vector store and permissions work. The report format is internal and may change in any release.
+
+## Error codes
+
+These codes are stable and safe to branch on in the UI:
+
+| Code | Meaning |
+|---|---|
+| `invalid_input` | The request was rejected as malformed or too long |
+| `unauthorized` | The access token is missing or invalid |
+| `session_expired` | The access token expired; refresh it and retry |
+| `not_found` | Unknown bot or conversation (also returned for conversations you don't own) |
+| `rate_limited` | Too many requests; wait `retryAfterMs` |
+| `budget_exceeded` | The bot's daily budget is spent |
+| `bot_unavailable` | The bot is disabled (kill switch) or misconfigured |
+| `content_blocked` | Reserved for moderation; this version never sends it |
+| `timeout` | The turn exceeded the server deadline |
+| `upstream_error` | OpenAI failed |
+| `internal_error` | Unexpected server error |
+
+## Error keys and parameters
+
+Next to `code` and `message`, an `error` event can carry:
+
+| Field | Meaning |
+| --- | --- |
+| `retryAfterMs` | How long to wait before retrying, in milliseconds |
+| `key` | The [text key](texts.md) for this error, such as `error.messageLength`, so a client can show it in the visitor's language |
+| `params` | Values for the placeholders in that text, such as `{ "max": 4000 }` |
+
+`message` is the English text. The widget looks `key` up in the bot's texts, overrides included, fills in `params`, and shows `message` when it has no text for the key.
+
+`key` is absent in two cases:
+
+- **Explained in development.** When `NODE_ENV` is `development`, as under `next dev`, a `bot_unavailable` error caused by the setup carries a description for you in `message` instead of a key: a missing or weak secret, a missing `OPENAI_API_KEY`, a key OpenAI rejects, a model the project can't use. The widget shows that description as it is. In production, the server never sends one.
+- **Messages for developers.** Some refusals carry only a plain English `message`, such as `Expected an application/json body.`, `Malformed JSON.`, `Request body is too large.` and `Cross-origin requests are not allowed.`
+
+Error responses outside the stream have the same fields, inside `error`:
+
+```json
+{
+  "error": {
+    "code": "invalid_input",
+    "message": "Messages must be between 1 and 4000 characters.",
+    "key": "error.messageLength",
+    "params": { "max": 4000 }
+  }
+}
+```
+
+## HTTP status codes
+
+| Status | Code | When |
+| --- | --- | --- |
+| `200` | | Success. For `POST /messages`, the stream has started, and later failures arrive as an `error` event |
+| `204` | | `DELETE /conversation` succeeded, also when the conversation was already gone |
+| `400` | `invalid_input` | The body is not what the endpoint expects (wrong `Content-Type`, malformed JSON, a JSON body over 256 KB), or the message, file or recording is refused, including when it is too large |
+| `401` | `unauthorized` | The `Bearer` token is missing or invalid, or the request is cross-site |
+| `401` | `session_expired` | The access token expired; renew it with `POST /session` and retry |
+| `404` | `not_found` | An unknown path, bot or asset; a resume token that is invalid or belongs to someone else; a conversation that no longer exists |
+| `429` | `rate_limited` | A rate limit was reached, the conversation reached `maxTurns`, or another dictation is still being transcribed |
+| `429` | `budget_exceeded` | A daily token or speech budget is spent |
+| `500` | `internal_error` | Unexpected server error |
+| `502` | `upstream_error` | OpenAI failed or could not be reached |
+| `503` | `bot_unavailable` | The kill switch (`ASKDARE_DISABLED=true`) is on, a secret or `OPENAI_API_KEY` is missing or invalid, or OpenAI refused the key or the model |
+| `504` | `timeout` | OpenAI did not answer in time |
+
+An error response with `retryAfterMs` also has a `Retry-After` header, in whole seconds rounded up. For `budget_exceeded`, it lasts until the next midnight UTC.
+
+| Endpoint | Statuses |
+| --- | --- |
+| `GET /widget.js` | `200` |
+| `GET /embed/<bot>`, `GET /theme/<bot>.css`, `GET /assets/<file>` | `200`, `404` |
+| `POST /session` | `200`, `400`, `401`, `404`, `429`, `503` |
+| `POST /messages` | `200`, `400`, `401`, `404`, `429`, `503` |
+| `POST /history` | `200`, `400`, `401`, `404`, `429`, `502`, `503`, `504` |
+| `DELETE /conversation` | `204`, `400`, `401`, `404`, `429`, `502`, `503`, `504` |
+| `POST /attachments`, `POST /transcriptions` | `200`, `400`, `401`, `404`, `429`, `502`, `503`, `504` |
+| `POST /doctor` | `200`, `401`, `429`, `503` |
+
+Any endpoint can also answer `500`.
+
+## Protocol version
+
+`PROTOCOL_VERSION`, exported from `@boldare/askdare`, is the version of this protocol: `1`. Every event stream (`POST /messages` answered with `200`) carries it in the `x-askdare-protocol` response header. Other responses don't have this header.
+
+The widget compares the header with the version it was built with. On a mismatch, it doesn't read the stream and shows `error.updated` ("The assistant was updated. Please reload the page.").
+
+## Client rules
+
+- **Tolerate the unknown.** Ignore unknown event types and unknown fields. Newer servers may add them within the same protocol version.
+- **Check the version.** Compare `x-askdare-protocol` with the version the client supports. On a mismatch, show a "please reload" state.
+- **Run a watchdog.** If no bytes (events or comments) arrive for 45 s, abort and re-fetch the conversation history.
+- **Render text safely.** Treat `text.delta` content as untrusted markdown and sanitize it before rendering.
+
+## Versioning
+
+- **Adding** an event type or an optional field is not breaking.
+- **Removing or renaming** an event or field, or changing a field's meaning, is breaking. It bumps the protocol version and requires a minor release of `@boldare/askdare` (ADR-0006).

package/docs/styling.md

@@ -0,0 +1,166 @@
+# Styling and customization
+
+Three levels, each with more freedom than the last ([ADR-0008](https://github.com/boldare/askdare/blob/main/docs/adr/0008-ui-customization-and-themes.md)). Streaming, security and limits stay in the library whatever you change.
+
+| Level | How | For |
+| --- | --- | --- |
+| 1. Configuration | `widget: { … }` in `defineBot` | Texts, language, theme, suggestions, avatar, disclosure |
+| 2. Your own CSS | `widget.css`, plus `::part()` for the launcher | Any look, on top of the parts and tokens below |
+| 3. Page JavaScript | `askdare(…)` and attributes on the script tag | Your own button, the chat inside your page, per-page texts and context |
+
+## 1. Configuration
+
+```ts
+defineBot({
+  // …
+  widget: {
+    title: 'Brightloop assistant',
+    subtitle: 'Answers from our help center',
+    greeting: 'Hi! How can I help?',
+    starters: ['What does the Business plan include?'],
+    avatar: '/assistant.png',
+    locale: 'auto', // the page's language, else the visitor's browser
+    texts: { 'composer.placeholder': 'Ask about plans, support or security…' },
+    disclosure: { privacyUrl: 'https://www.example.com/privacy' },
+    theme: 'aura', // see docs/themes.md
+    colorScheme: 'auto',
+  },
+});
+```
+
+- **Language.** Texts ship in English and Polish. `locale: 'auto'` follows the `lang` of the page that embeds the chat, else the visitor's browser; any other language shows English unless you set `texts`. The locale is also the default answer language.
+- **Bold words.** In a greeting, `**words**` are shown in bold. Aura uses this for its two-weight headline.
+- **Texts.** Every text has a key; `texts` overrides any of them. `title`, `greeting`, `placeholder` and `launcherLabel` are shortcuts for `header.title`, `welcome.greeting`, `composer.placeholder` and `launcher.label`, and a configured text is used in every language. The full list, with plurals and how to add a language, is in [Texts](texts.md); the keys are public API.
+- **Disclosure.** By default the chat says, under the message field, that the visitor is talking to an AI (EU AI Act, art. 50). Add `privacyUrl` for a link to your privacy policy. `disclosure: false` hides it; only do that when your page already says so.
+
+## 2. Your own CSS
+
+```ts
+widget: {
+  css: `
+    [data-ask-part="bubble"] { border-radius: 6px; }
+    [data-ask-part="message"][data-role="user"] [data-ask-part="bubble"] { font-weight: 500; }
+    :root { --ask-color-accent: #0f766e; }
+  `,
+}
+```
+
+Your CSS loads after the theme. The library's styles are in `@layer askdare`, so yours wins without `!important`. The chat's Content Security Policy still applies: images load only from your app or as `data:` and `blob:` URLs, and fonts only from your app.
+
+A full example is the demo site's BLDR theme, in Boldare's style: `defineTheme` over Halo for colors, type and square corners, a few lines of `widget.css` for the hard shadows and highlights, and `::part(launcher)` on the page for the button. The code is in [Themes: a theme in your brand](themes.md#example-a-theme-in-your-brand).
+
+**Tokens:** the `--ask-*` variables listed in [Themes](themes.md#tokens). Only those are public API. The chat's stylesheet also defines the variables below; they are internal and can change in any release, so don't build on them.
+
+| Internal variable | What it holds |
+| --- | --- |
+| `--ask-space` | The spacing unit: 8px, or 6px with the `compact` density |
+| `--ask-radius-small` | A smaller radius, 0.6 × `--ask-radius` |
+| `--ask-shadow` | The shadow of raised elements, mixed from `--ask-color-text` |
+| `--ask-ring` | The ring around the focused message field, mixed from `--ask-color-accent` |
+| `--ask-glass` | The translucent surface of the `glass` variant, mixed from `--ask-color-surface` |
+| `--ask-ease` | The easing curve of transitions |
+| `--ask-level` | The microphone level while recording, set by the chat |
+| `--ask-aura-gradient-end` | Where Aura's gradient on the visitor's bubbles and the send button ends |
+
+The launcher's short variables on your page (`--a`, `--o` and the like) are internal too.
+
+**Parts** (`[data-ask-part="…"]`, public API): `panel`, `header`, `identity`, `identity-text`, `title`, `subtitle`, `actions`, `new-conversation`, `close`, `avatar`, `orb`, `messages`, `welcome`, `greeting`, `starters`, `starter`, `persona`, `persona-name`, `presence`, `intro`, `intro-card`, `message`, `message-body`, `bubble`, `image-alt`, `typing`, `citations`, `citation`, `attachments-note`, `status`, `error`, `composer`, `composer-box`, `input`, `attach`, `voice`, `send`, `attachments`, `message-attachments`, `attachment`, `attachment-preview`, `attachment-badge`, `attachment-name`, `attachment-status`, `attachment-remove`, `recorder`, `recorder-level`, `recorder-label`, `recorder-time`, `recorder-cancel`, `recorder-done`, `send-label` (shown by Aura), `disclosure`, and the question before a new conversation: `confirm-backdrop`, `confirm`, `confirm-icon`, `confirm-text`, `confirm-actions`, `confirm-cancel`, `confirm-accept`.
+
+`identity-text` holds the title and subtitle in the header. `image-alt` stands in for an image in a reply: the chat never loads images that the model writes, so it shows their alt text in brackets.
+
+**States** are attributes on the parts:
+
+| Part | Attribute | Values |
+| --- | --- | --- |
+| `panel` | `data-busy` | Present while the assistant answers or a dictation runs |
+| `panel` | `data-dragging` | Present while files are dragged over the chat (only when the bot accepts attachments) |
+| `message` | `data-role` | `user`, `assistant` |
+| `message` | `data-status` | `streaming`, `done`, `error` |
+| `attachment` | `data-status` | `uploading`, `ready`, `error`, on files not sent yet; absent in sent messages |
+| `attachment` | `data-kind` | `image`, `pdf`; absent until the chat has recognized the file |
+| `recorder` | `data-state` | `recording`, `transcribing` |
+| `avatar` | `data-kind` | `orb`, `icon`, `initials`, `image` |
+| `avatar` | `data-size` | `small` in the header, next to the assistant's messages and in the `intro` welcome; `large` in the `hero` and `persona` welcome |
+| `welcome` | `data-layout` | `hero`, `persona`, `intro` |
+
+Select a present-or-absent attribute by its name alone, such as `[data-ask-part="panel"][data-dragging]`.
+
+**Variants** of the theme are attributes on `<html>`: `data-ask-preset`, `data-ask-scheme`, `data-ask-avatar`, `data-ask-welcome`, `data-ask-launcher`, `data-ask-bubbles`, `data-ask-surface`, `data-ask-density`, `data-ask-composer`.
+
+**The launcher** follows the theme's `launcher` variant: `circle` is a chat icon, `pill` the bot's picture or initials with its label, and `orb` the theme's orb with its label (Aura and Halo). The label is `launcherLabel`. It lives in a shadow root on your page. Style it from your own CSS with `::part`:
+
+```css
+[data-askdare]::part(launcher) { right: 32px; bottom: 32px; }
+[data-askdare]::part(panel) { border-radius: 8px; }
+```
+
+The shadow root has three parts: `launcher`, `panel` (the dialog that holds the chat) and `unavailable` (the notice in the panel when the chat doesn't load). The element that holds the shadow root has `data-askdare` set to the bot ID, so `[data-askdare="support"]::part(launcher)` styles one bot's launcher only.
+
+### Brand fonts
+
+The chat's Content Security Policy allows fonts and stylesheets only from your app's own origin (`font-src 'self'`, `style-src 'self'`). So:
+
+- Serve the font files from your app, for example from `public/fonts/` in Next.js.
+- Declare them with `@font-face` in `widget.css`. Use a path that starts with `/`: `widget.css` is served from under the chat's base path, so a relative URL would point there.
+- Fonts and stylesheets from other origins, such as a font CDN, are blocked, and so are fonts in `data:` URLs.
+
+```ts
+widget: {
+  css: `
+    @font-face {
+      font-family: "Brand Sans";
+      src: url("/fonts/brand-sans.woff2") format("woff2");
+      font-display: swap;
+    }
+    :root {
+      --ask-font-family: "Brand Sans", system-ui, sans-serif;
+      --ask-font-family-heading: "Brand Sans", system-ui, sans-serif;
+    }
+  `,
+}
+```
+
+Every preset sets both font tokens, so set both. You can also set them as the `fontFamily` and `headingFamily` tokens of a theme ([Themes](themes.md#adjust-a-preset)) and keep only the `@font-face` rule in `widget.css`. The launcher is on your page, not in the chat, so it can use your page's fonts through `::part(launcher)`.
+
+## 3. Page JavaScript
+
+```html
+<!-- Your own button instead of the launcher -->
+<button onclick="askdare('open')">Chat with us</button>
+<script src="https://app.example.com/api/chat/widget.js?bot=support" data-launcher="none" async></script>
+
+<!-- The chat inside your page -->
+<div id="chat" style="height: 600px"></div>
+<script src="https://app.example.com/api/chat/widget.js?bot=support" data-mode="inline" data-target="#chat" async></script>
+```
+
+| Call | Effect |
+| --- | --- |
+| `askdare('open')`, `askdare('close')`, `askdare('toggle')` | Shows or hides the chat. Closing returns focus to whatever opened it. |
+| `askdare('identify', token)` | Signs the visitor in with a token from your backend, or out with `null`; see [Signed-in visitors](identity.md). |
+| `askdare('configure', { greeting, starters, context })` | Per-page greeting and suggestions, and `context`: a short description of the page (up to 1000 characters) for the assistant. |
+
+`configure` accepts only those three fields: never the model, instructions or tools. The context is off unless the bot opts in with `pageContext: true` in `defineBot`. It then travels with the visitor's message, as a marked part of their own turn: anyone can set it from their browser, so it gets no more trust than what the visitor types, and it never becomes part of the bot's instructions. It is sent again only when it changes, and the visitor's history doesn't show it. Define the small queue first, then call it any time:
+
+```html
+<script>
+  // Safe to call before the script has loaded: calls queue up and run once it is ready.
+  window.askdare = window.askdare || function () {
+    (window.askdare.q = window.askdare.q || []).push(arguments);
+  };
+  askdare('configure', {
+    greeting: 'Questions about our prices?',
+    starters: ['How much is the Business plan?'],
+    context: 'Pricing page listing the Free, Team and Business plans.',
+  });
+</script>
+<script src="https://app.example.com/api/chat/widget.js?bot=support" async></script>
+```
+
+An inline chat loads with the page without taking focus or scrolling to itself.
+
+In a React app, Next.js included, add the script after hydration, for example from a `useEffect` in a small client component. The loader adds the chat inside your element, and React must not find it there while it hydrates. The demo site's [`chat-script.tsx`](https://github.com/boldare/askdare/blob/main/site/app/chat-script.tsx) does this. The chat loads once per page load and lives as long as its element: put the element in a layout that stays, or link to the page with full page loads, because a client-side navigation away and back leaves the element empty.
+
+## Accessibility
+
+Accessibility is not configurable away. The focus ring is always visible, motion follows `prefers-reduced-motion`, the chat is a labelled dialog, and Escape closes it (or cancels a dictation). Every preset passes axe in every state, and its colors pass WCAG AA (AAA for text in Care); a customized theme with weak contrast triggers a warning in development.

package/docs/support.md

@@ -0,0 +1,48 @@
+# Support
+
+What askdare is tested with and promises to keep working. The reasoning is in [ADR-0006](https://github.com/boldare/askdare/blob/main/docs/adr/0006-support-matrix-and-versioning.md).
+
+## Your app
+
+| | Supported | Not supported |
+| --- | --- | --- |
+| Node.js | 22 and 24 | 20 and older |
+| Next.js | 16.x with the App Router, on the Node.js runtime; Turbopack and `next build --webpack` | Pages Router, Edge runtime, static export |
+| React | 19 | 18 |
+| zod | 4.1 or later | 3 |
+| TypeScript | 5.9, 6.0 and 7.0 | |
+| Hosting | Vercel and Heroku | Other hosts that run `next start` should work, but aren't tested |
+
+## Visitors' browsers
+
+The current and previous major versions of Chrome, Edge, Firefox and Safari, on desktop and mobile, at least:
+
+| Browser | Version |
+| --- | --- |
+| Chrome, Edge | 111 |
+| Firefox | 121 |
+| Safari (macOS and iOS) | 16.4 |
+
+Older browsers may show the chat with a plainer look or not at all. Dictation also needs a microphone and `MediaRecorder`, which all of these have.
+
+Every release is tested in Chromium, Firefox and WebKit: embedding, the page API and accessibility (axe). Safari on iOS, dictation in Safari and screen readers (VoiceOver, NVDA) are checked by hand before each release candidate.
+
+## What a visitor downloads
+
+| | Gzipped | Budget |
+| --- | --- | --- |
+| The loader (`widget.js`), on every page | about 3 KB | 5 KB |
+| The chat itself, when the visitor opens it | about 34 KB, plus 5 KB of styles | 50 KB and 8 KB |
+| One theme's fonts, from your app | up to 82 KB | 82 KB |
+
+The build fails when one of these grows past its budget.
+
+## How we keep it working
+
+- **Every change:** lint, types, unit and browser tests, the package checks (publint, are-the-types-wrong), the size budgets, and a snapshot of the published types. A change to the public API has to update the snapshot on purpose and come with a changeset.
+- **Every night:** the same against `next@canary` and the newest `openai` SDK, so a breaking release shows up before it reaches you.
+- **Every day:** a live test against the real OpenAI API with a cheap model: text, a tool call, file search and an image. It catches retired models and API changes.
+
+## Versions
+
+askdare is in 0.x. Minor releases may break things; patch releases never do. A removal is announced by a deprecation warning one minor release earlier, and every release lists its changes.