@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/telegram-listener.md

@@ -0,0 +1,76 @@
+# Telegram Listener
+
+Listens for incoming Telegram messages via a bot and pushes each text message into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| hkp-node | `telegram-listener` |
+
+---
+
+## What it does
+
+The Telegram Listener service connects to the Telegram Bot API using long polling (`getUpdates` with a 25-second timeout). Each incoming text message is parsed and emitted downstream as a structured object — making it a **source service** that drives the pipeline without an upstream trigger.
+
+Pending updates accumulated while the bot was offline are drained silently on connect, so only messages sent after the connection is established are forwarded.
+
+Optionally restrict reception to a single chat by setting `allowedChatId` to your personal Telegram chat ID — useful when you share the bot with no one else but still want to prevent accidental input.
+
+---
+
+## Setup
+
+1. Open Telegram and message **@BotFather** → `/newbot` → follow the prompts.
+2. Copy the bot token BotFather gives you into the **Bot Token** field.
+3. To find your chat ID: message the bot once, then call `https://api.telegram.org/bot<TOKEN>/getUpdates` — your numeric ID appears in `result[].message.chat.id`.
+4. Paste that ID into **Allowed Chat ID** to restrict the service to your messages only.
+5. Click **Connect**.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `botToken` | `string` | `""` | Telegram Bot API token from @BotFather |
+| `allowedChatId` | `string` | `""` | If set, only messages from this chat ID are forwarded |
+| `connect` | `boolean` | — | Send `{ connect: true }` to start polling |
+| `disconnect` | `boolean` | — | Send `{ disconnect: true }` to stop polling |
+
+### Read-only state fields
+
+| Field | Type | Description |
+|---|---|---|
+| `running` | `boolean` | Whether the polling loop is active |
+| `error` | `string` | Last error message, if any |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — passed through unchanged when the pipeline is triggered externally |
+| **Output (push)** | `{ text, from, chatId, messageId, date }` — emitted for each incoming text message |
+
+### Output object fields
+
+| Field | Description |
+|---|---|
+| `text` | The message text |
+| `from` | Sender's `@username` or first name |
+| `chatId` | Telegram chat ID as a string |
+| `messageId` | Telegram message ID |
+| `date` | ISO 8601 timestamp of the message |
+
+---
+
+## Typical uses
+
+- Telegram Listener → Monitor — display every message you send from your phone
+- Telegram Listener → Map → HTTP Client — forward messages to a webhook
+- Telegram Listener → Filter → Timer — trigger a pipeline only on specific commands

package/bundle/docs/content/services/text-generation.md

@@ -0,0 +1,390 @@
+# Text Generation
+
+Generates text with a large language model — a local one via an OpenAI-compatible server or in-process, or a hosted one.
+
+---
+
+## Available in
+
+| Runtime | Service ID | Backends |
+|---|---|---|
+| Python (hkp-python) | `text-generation` | `server`, `local` |
+| C++ (hkp-rt) | `text-generation` | `server`, `local` |
+| Node.js (hkp-node) | `text-generation` | `server`, `anthropic` |
+
+All three expose the same state keys, the same input shapes, and the same
+output JSON, so a board can move the service between them unchanged. Which
+backends a runtime offers differs: every runtime can talk to a **server**,
+hkp-python and hkp-rt can additionally load a GGUF **in-process**, and hkp-node
+can additionally call a **hosted API**.
+
+---
+
+## What it does
+
+Text Generation takes a prompt, runs it through an LLM, and emits the answer as
+JSON to the next service or runtime.
+
+On **hkp-python** and **hkp-rt** everything runs locally — no text leaves your
+machine — through one of two backends selected by the `backend` state:
+
+- **`server`** (default) — the service is a thin client to any locally
+  running server that speaks the OpenAI chat-completions API
+  (`llama-server`, Ollama, vLLM, LM Studio, ...). Use this for quants that
+  need a custom llama.cpp build, such as the 1-bit Bonsai 27B reference
+  model via the PrismML fork.
+- **`local`** — the service loads a standard GGUF (Qwen, Llama, Mistral, ...)
+  directly into the runtime process — via `llama-cpp-python` in hkp-python,
+  via embedded llama.cpp in hkp-rt. No external server process is needed.
+
+**hkp-node** offers `server` and, instead of `local`, **`anthropic`**: a hosted
+Claude model, reached over the network. Text does leave the machine, and in
+exchange the service needs no model on disk, no GPU, and no server process —
+which is what makes it the one that works on a board deployed to a coordinator
+with nobody watching. It also adds images in the input and extended reasoning,
+which the local backends have no equivalent for.
+
+Node cannot load a GGUF in-process the way the other two can, which is why it
+has no `local`. On this runtime, local means a server next door — the same
+`server` backend, pointed at `127.0.0.1`. A board therefore moves between a
+model on your desk and a hosted one by changing two fields:
+
+```json
+{ "backend": "server",    "serverUrl": "http://127.0.0.1:8081", "model": "qwen3-0.6b" }
+{ "backend": "anthropic", "model": "claude-sonnet-5" }
+```
+
+The natural producer is the **Speech To Text** service — its output JSON
+carries a `text` key that pipes straight in — and the natural consumer is
+**Text To Speech**, completing a fully local voice loop.
+
+---
+
+## Prerequisites
+
+**Server backend** — no extra Python dependencies; start any
+OpenAI-compatible server, e.g.:
+
+```
+llama-server -m Bonsai-27B-Q1_0.gguf --port 8081 -ngl 99
+```
+
+**Local backend (hkp-python)** — the in-process engine is an optional extra:
+
+```
+uv sync --extra llm    # in hkp-python
+```
+
+**Local backend (hkp-rt)** — llama.cpp is embedded at build time. It is on by
+default on macOS, Linux, and Windows, and off for iOS and Android builds, which
+would otherwise pay its compile time and binary size:
+
+```
+cmake -B build -DHKP_LLAMA_ENABLED=ON ..
+```
+
+On Apple silicon the Metal shaders are embedded in the binary, so nothing has
+to sit next to the runtime at load time. When the flag is off the service still
+loads and the server backend still works; only `backend: "local"` reports that
+it was not compiled in.
+
+Either way you also need a GGUF file on disk (e.g. `Qwen3-0.6B-Q8_0.gguf` from
+Hugging Face).
+
+**Anthropic backend (hkp-node)** — an API key, and nothing else. The service
+reads it from its own `apiKey` and from nowhere else: **not from the
+environment the runtime starts in.** A server is shared — by the people who
+own boards on it, and by everyone a deployed board admits — and a key in its
+environment would be the operator's, spent by every board on it and sent
+wherever a board's `serverUrl` points.
+
+`apiKey` is write-only — the service accepts it and never gives it back, the
+same way `smtp-email` treats its password — but a key typed straight into it is
+still a credential inside the board, and a board can be downloaded, shared as a
+link, or sent through the AI Refiner. A secret reference is in none of those
+places, which is why it is the one to use.
+
+### A secret reference
+
+Add the key under **Settings → Secrets** with a name of your choosing, and
+refer to it from the board by that name instead of pasting the value:
+
+```json
+{ "backend": "anthropic", "model": "claude-sonnet-5", "apiKey": "{{secret.anthropic}}" }
+```
+
+The board says *which* secret the field needs and never what it is. The value
+is substituted in as the board loads, before any service is configured — so it
+reaches `apiKey` the same way a typed one does, and the file on disk still
+holds no credential and stays safe to save, share, or hand to the AI Refiner.
+The store is the app's own (`~/.hkp/vault.json` on desktop) and the settings
+dialog only ever lists names, never values. The browser playground has no such
+store, so a board opened there — or anywhere the secret is not configured —
+loads with the field unset and names the alias it was missing.
+
+References work in any service field on any runtime — `smtp-email`'s password,
+an `http-client` header — not just this one.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `backend` | `string` | `"server"` | `server` (OpenAI-compatible HTTP) or `local` (in-process GGUF) |
+| `serverUrl` | `string` | `"http://127.0.0.1:8081"` | Server backend: base URL of the OpenAI-compatible server |
+| `model` | `string` | `""` | Server backend: optional model name passed through to the server |
+| `modelPath` | `string` | `""` | Local backend: path to the `.gguf` file (`~` expands) |
+| `contextSize` | `number` | `4096` | Local backend: context window in tokens |
+| `gpuLayers` | `number` | `-1` | Local backend: layers to offload to GPU (`-1` = all) |
+| `systemPrompt` | `string` | `"You are a helpful assistant"` | Prepended when the input has no system message |
+| `temperature` | `number` | `0.7` | Sampling temperature |
+| `topP` | `number` | `0.95` | Nucleus sampling |
+| `topK` | `number` | `20` | Top-k sampling |
+| `maxTokens` | `number` | `512` | Completion token budget |
+| `timeoutSec` | `number` | `300` | Server backend: request timeout |
+| `thinking` | `bool\|null` | `null` | Server backend: force thinking on/off, for a server whose chat template takes the flag; `null` sends nothing |
+| `stream` | `bool` | `true` | Generate token by token and notify the growing text as `{streamText}` (final notification carries `streamDone: true`) for live chat-bot-style display; the pipeline output is unaffected and still emitted once, when generation finishes. Set `false` for servers without SSE support |
+
+In local mode the model loads lazily on first use and reloads when
+`modelPath`, `contextSize`, or `gpuLayers` change. For thinking models in
+local mode, add `/no_think` to the system prompt to suppress reasoning
+(the `thinking` toggle is a llama-server chat-template extension).
+
+### hkp-node
+
+Alongside `systemPrompt`, `temperature`, `topP`, `topK`, `maxTokens`,
+`timeoutSec` and `stream`, which mean what they mean everywhere else — except
+that the `anthropic` backend sends sampling settings only to the older Claude
+models that take them (see below):
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `backend` | `string` | `"anthropic"` | `anthropic` (hosted) or `server` (OpenAI-compatible HTTP) |
+| `apiKey` | `string` | `""` | Write-only; takes a `{{secret.…}}` reference. The runtime's environment is never read |
+| `apiKeyConfigured` | `bool` | — | Read-only: whether a key is configured |
+| `serverUrl` | `string` | `""` | Empty means the backend's own address; set it for a proxy, or for a hosted OpenAI-compatible endpoint |
+| `endpoint` | `string` | — | Read-only: the URL this configuration actually reaches |
+| `model` | `string` | `"claude-sonnet-5"` | Any model the API accepts |
+| `thinking` | `bool\|null` | `null` | `true` asks for reasoning, `false` for none, `null` leaves the model to its default; reasoning is reported in `thinking` |
+| `thinkingBudgetTokens` | `number` | `1024` | Tokens reasoning may use, for a Claude model that thinks on a budget; `maxTokens` is lifted above it when it is not already |
+| `effort` | `string` | `""` | Claude only: `low`, `medium`, `high`, `xhigh` or `max` — how much the model reasons and writes. Empty is the model's own default |
+| `jsonSchema` | `object\|string\|null` | `null` | Constrains the answer to a shape — see below |
+
+**One address field, for both backends.** `serverUrl` left empty means "wherever
+this backend lives" — `https://api.anthropic.com` or `http://127.0.0.1:8081` —
+and the default is resolved when the request is made rather than written into
+the board, so switching backends carries nothing stale across. Set it to point
+at a proxy, or at a hosted OpenAI-compatible endpoint. `endpoint` reports where
+a configuration actually reaches, including the API version, which is the one
+question the address alone does not answer:
+
+```json
+{ "backend": "server", "serverUrl": "https://inference.example.com/api/v1" }
+→ endpoint: "https://inference.example.com/api/v1/chat/completions"
+```
+
+A base URL already carrying a version keeps it; a bare origin gets `/v1` added,
+because that is how the two kinds of server hand their address out.
+
+A server that wants a token gets the configured `apiKey` as a bearer; one that
+does not is reached with none.
+
+**A reasoning model needs `thinking: false` to answer inside a schema.** Qwen3
+and its relatives reason before answering by default, and a `jsonSchema`
+constrains output from the first token — leaving nowhere to reason. What comes
+back is a well-formed response that spent its whole `maxTokens` budget and
+carries no answer. Setting `thinking: false` sends
+`chat_template_kwargs: {enable_thinking: false}`, which those templates honour;
+raising `maxTokens` works too, more slowly. A generation that produces neither
+text nor `json` is reported as a failure and stops the pipeline rather than
+being passed on, so a board that settles its work at the end cannot mark an
+item done having produced nothing.
+
+Two behaviours worth knowing:
+
+- **Little sampling on `anthropic`.** `temperature`, `topP` and `topK` are kept
+  for the `server` backend. Of Claude models, only Haiku 4.5, Sonnet 4.6 and
+  Opus 4.6 are sent `temperature` and `topK` (never `topP` beside them, and
+  neither while they think): current Claude models refuse any value but their
+  own, and API version 2026-10-21 refuses the fields on every model.
+- **`jsonSchema` turns streaming off** for that call. A constrained answer
+  arrives as arguments rather than prose, and half of a JSON object is of no
+  use to anything.
+
+### One board, many Claude models
+
+The Claude models disagree on how reasoning and shape are asked for, and a
+request one accepts another refuses. A board states what it wants — `thinking`,
+`effort`, `jsonSchema` — and the request is built from what the configured
+model accepts, so a board keeps working when its `model` changes. Nothing here
+applies to the `server` backend, whose request is built as it always was.
+
+| The board says | A current model (Haiku 5.5, Sonnet 5.5, Opus 5.5, …) | An older model (Haiku 4.5, …) |
+|---|---|---|
+| `thinking: true` | `thinking: {type: "adaptive"}`; effort sets how much | `thinking: {type: "enabled", budget_tokens}` |
+| `thinking: null` | nothing — current models think by default | nothing — no reasoning |
+| `thinking: false` | `{type: "disabled"}`, or `{type: "between_tools"}` on Sonnet 5.5; not sent to a model that always thinks (Opus 5.5, Fable) or at an effort it is refused at | nothing |
+| `effort` | `output_config: {effort}`, at the levels the model takes | not sent |
+| `temperature`, `topK` | not sent | sent while the model is not thinking |
+| `jsonSchema` | a forced tool, or structured outputs on the models that refuse one (Opus 5.5, Sonnet 5.5, Fable 5.1) | a forced tool |
+
+What a model accepts comes from the Models API (`GET /v1/models/{id}`), asked
+once per model and address, where it reports it — which thinking a model takes,
+which effort levels, and whether it has structured outputs. What it does not
+report, how "do not think" is said, whether a forced tool is accepted and
+whether sampling settings are, comes
+from a table in `hkp-node/src/services/claudeModels.ts`, which also stands in
+when the API cannot be asked. A model in neither gets the oldest form of each,
+and no sampling settings.
+
+**A current model's thinking counts against `maxTokens`.** It thinks before it
+answers whatever the board says, and a ceiling sized for the answer alone can
+go entirely on thinking. Such a call fails with *the model used all N tokens
+without answering*; raise `maxTokens`, or lower `effort`. A setting the model
+does not use is marked in the service's state (`__meta__`), with the reason.
+
+---
+
+## Constrained output
+
+Set `jsonSchema` to a JSON Schema and the answer comes back in that shape. The
+parsed object is emitted as `json`, and `text` carries the same object
+serialized, so a board that only knows the shared output contract still has
+something to route.
+
+Available on hkp-node, on either of its backends.
+
+```json
+{
+  "serviceId": "text-generation",
+  "state": {
+    "systemPrompt": "Extract the booking request. Leave a field out when the message does not state it — never guess.",
+    "jsonSchema": {
+      "type": "object",
+      "properties": {
+        "hotel": { "type": "string" },
+        "rooms": { "type": "integer" },
+        "arrival": { "type": "string", "description": "ISO date" }
+      },
+      "required": ["hotel", "rooms"]
+    }
+  }
+}
+```
+
+How the schema is sent depends on the backend, and so does how much it
+guarantees:
+
+| Backend | Sent as | Guarantee |
+|---|---|---|
+| `anthropic` | a single tool the model is required to call, or structured outputs (`output_config.format`) on the models that refuse a forced tool | the shape is enforced by the API |
+| `server` | `response_format: { type: "json_schema" }` | enforced by servers that implement it — llama.cpp compiles the schema to a grammar |
+
+Structured outputs take a stricter schema than a tool does: every object is
+sent closed (`additionalProperties: false`), and numeric and length bounds
+(`minimum`, `maxLength`, …) are left out. The shape is enforced; those bounds
+are not. The board's schema itself is never changed.
+
+Not every OpenAI-compatible server implements `response_format`, and one that
+does not answers in prose while reporting nothing unusual. When that happens
+the answer is still handed on with `text` set and `json` absent, and the
+runtime logs a `service.degraded` warning naming the likely cause — so a board
+sees what came back rather than an empty result it has to guess about.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `String` prompt, or JSON with `prompt`, `text`, or a full `messages` array |
+| **Output** | `{ "text": string, "json"?: any, "thinking"?: string, "model": string, "durationMs": number, "usage": { "promptTokens": number, "completionTokens": number } }` |
+
+The `anthropic` backend also reads **images** out of the input, so a scan or a
+photo that arrived from `http-client`, an email attachment, or a `file-pick`
+widget can be asked about directly:
+
+| Input carries | Becomes |
+|---|---|
+| `{ meta: { contentType: "image/png" }, binary }` — what `http-client` and `http-server-subservices` produce | one image, plus `prompt`/`text` as the question |
+| `{ images: [{ contentType, data }, ...] }` — `data` as bytes or base64 | one part each |
+
+Images are placed before the question, which is how the model reads them best.
+
+**The answer is the service's answer, however long it takes.** Generation
+takes seconds, and the runtime awaits it, so the services after it run with the
+result — and a [Join](./join.md) around it comes back with the answer beside the
+question rather than instead of it.
+
+For thinking models the reasoning is split off into the `thinking` field;
+`text` carries only the answer. Unsupported input, an unreachable server,
+or a local backend that is unavailable produce `{ "error": "..." }` with a
+hint instead of crashing the pipeline.
+
+In `local` mode `model` reports the GGUF path rather than a server-assigned
+model name. Streamed `streamText` notifications carry the raw model output, so
+for a thinking model the live view briefly shows the `<think>` block; the final
+result always has it split into `thinking`.
+
+---
+
+## Status notifications
+
+| `status` | Meaning |
+|---|---|
+| `idle` | Ready; last generation finished |
+| `loading` | Local backend: loading the GGUF (see `detail`) |
+| `generating` | Inference in progress |
+| `error` | Something failed (input, backend, or model) |
+
+A facade `status-indicator` widget can bind to `path: "status"` and
+color-map these values directly.
+
+---
+
+## Example
+
+The attached demo board uses the server backend (Injector → text-generation
+→ monitor). A local-backend variant that needs no external server lives at
+`boards/text-generation-local-demo-board.json` — it loads
+`Qwen3-0.6B-Q8_0.gguf` in-process:
+
+```json
+{
+  "python": [
+    {
+      "serviceId": "text-generation",
+      "state": {
+        "backend": "local",
+        "modelPath": "~/models/Qwen3-0.6B-Q8_0.gguf",
+        "systemPrompt": "You are a helpful assistant. /no_think"
+      }
+    },
+    { "serviceId": "monitor" }
+  ]
+}
+```
+
+Start the Python runtime (`hkp-python`), keep it under the name `python` in
+*Manage runtime servers*, open the board,
+and inject a prompt.
+
+For hkp-rt the equivalent runtime config ships as
+`boards/runtime-configs/text-generation-example.json`:
+
+```
+./build/hkp-rt/exe/Debug/hkp-rt 5556 127.0.0.1 boards/runtime-configs/text-generation-example.json
+curl -X POST http://127.0.0.1:5556/runtimes/text-generation-example \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Name three primary colors."}'
+```
+
+For the Anthropic backend, `boards/text-generation-anthropic-demo-board.json`
+turns a booking enquiry into structured fields (Injector → text-generation with
+a `jsonSchema` → monitor). Store the key under Settings → Secrets as
+`anthropic.key` — the name the board's `apiKey` refers to — start hkp-node and
+inject the message.
+
+The monitor shows the extracted object, not prose — which is what makes the
+next service in a board able to act on it.

package/bundle/docs/content/services/text-to-speech.md

@@ -0,0 +1,130 @@
+# Text To Speech
+
+Synthesizes speech from text with a local open-source model — Kokoro, running in the Python runtime via kokoro-onnx or in the C++ runtime via embedded sherpa-onnx.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Python (hkp-python) | `text-to-speech` |
+| C++ (hkp-rt) | `text-to-speech` |
+
+Both runtimes take text in and emit a `FloatRingBuffer` of audio, so a board can
+move the service between them unchanged. The hkp-rt version adds a `server`
+backend (an OpenAI-compatible speech endpoint) alongside its in-process `local`
+backend.
+
+---
+
+## What it does
+
+Text To Speech receives a text string (or JSON `{text}` / `{prompt}`), runs it
+through a Kokoro model, and emits the synthesized audio as a `FloatRingBuffer`
+(mono float32, typically 24 kHz) to the next service or runtime. Everything runs
+locally — no text leaves your machine.
+
+The `{text}` input shape is deliberate: the **Text Generation** service's output
+pipes straight in, completing the local voice loop
+**speech-to-text → text-generation → text-to-speech**. Feed the result to an
+audio-output service to hear it.
+
+---
+
+## Status notifications
+
+| `status` | Meaning |
+|---|---|
+| `idle` | Ready; last synthesis finished |
+| `loading` | Loading the model (see `detail`) |
+| `generating` | Synthesis in progress |
+| `error` | Something failed (input, dependency, or model) |
+
+A facade `status-indicator` widget can bind to `path: "status"` and color-map
+these values directly. On success the service also notifies audio metadata
+(`voice`, `sampleRate`, `samples`, `audioMs`, `generationMs`).
+
+---
+
+## hkp-python
+
+The Python runtime synthesizes with Kokoro-82M via
+[kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx). The ML dependencies
+are an optional extra:
+
+```
+uv sync --extra tts    # in hkp-python
+```
+
+Model files (~310 MB ONNX + ~27 MB voices) download lazily on first use into
+`~/.cache/hkp-python/kokoro`.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `model` | `string` | `"kokoro-v1.0"` | `kokoro-v1.0` or `kokoro-v1.0-int8` |
+| `voice` | `string` | `"af_heart"` | Kokoro voice name |
+| `speed` | `number` | `1.0` | 0.5–2.0 |
+| `lang` | `string` | `"en-us"` | Language |
+| `modelDir` | `string` | cache dir | Where model files are stored |
+
+Output is a `FloatRingBuffer` at 24 kHz.
+
+---
+
+## hkp-rt (C++ runtime)
+
+The C++ runtime runs the same service with two backends selected by the
+`backend` state:
+
+- **`local`** (default) — a Kokoro ONNX model runs in-process via embedded
+  [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx). Compiled in when the
+  runtime is built with `-DHKP_SPEECH_ENABLED=ON` (the default on desktop;
+  off for iOS/Android, which fall back to the server backend).
+- **`server`** — a thin client for an OpenAI-compatible `POST /v1/audio/speech`
+  endpoint. Always available.
+
+### Model
+
+Download a sherpa-onnx Kokoro model and point the path keys at its files:
+
+```
+curl -sL https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-en-v0_19.tar.bz2 | tar xj
+```
+
+### Configuration (hkp-rt)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `backend` | `string` | `"local"` | `local` or `server` |
+| `serverUrl` | `string` | `"http://127.0.0.1:8081"` | Server backend: base URL |
+| `model` | `string` | `"tts-1"` | Server backend: model name |
+| `voice` | `string` | `"af_heart"` | Server backend: voice name |
+| `modelPath` | `string` | `""` | Local backend: Kokoro ONNX (`~` expands) |
+| `voicesPath` | `string` | `""` | Local backend: voices file |
+| `tokensPath` | `string` | `""` | Local backend: tokens file |
+| `dataDir` | `string` | `""` | Local backend: `espeak-ng-data` directory |
+| `speakerId` | `number` | `0` | Local backend: speaker index |
+| `speed` | `number` | `1.0` | 0.5–2.0 |
+| `numThreads` | `number` | `2` | Local backend: inference threads |
+
+A single `FloatRingBuffer` hop carries at most ~88200 samples (the runtime's
+fixed ring-buffer size), i.e. ~3.67 s at 24 kHz; longer synthesis is truncated
+to that and a `truncated` count is reported in the audio-metadata notification.
+
+### Example (hkp-rt)
+
+`boards/runtime-configs/text-to-speech-example.json` wires `text-to-speech` (local) →
+`core-output`, so a POST of text is spoken through the speakers.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `string` / `TextData`, or JSON `{ "text": string }` / `{ "prompt": string }` |
+| **Output** | `FloatRingBuffer` — mono float32 audio (24 kHz for Kokoro) |
+
+Non-text input produces `{ "error": "..." }` instead of crashing the pipeline;
+a missing dependency or unavailable local backend is reported the same way.