@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/rss.md

@@ -0,0 +1,232 @@
+# RSS
+
+Several syndication feeds read as one list, newest first.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Node.js (hkp-node) | `rss` |
+
+---
+
+## What it does
+
+RSS holds a list of feed URLs, fetches them, and emits their articles as one
+array sorted newest first. RSS 2.0, RSS 1.0 (RDF) and Atom all read the same
+way: the three formats say the same few things under different names, and the
+service reduces them to one article shape.
+
+A reader's unit is not the feed, it is the article. The question being asked is
+*what is new*, and the answer spans everything subscribed to — so the feeds are
+fetched together and merged rather than read one after another. A board that
+wants one feed asks for one feed; nothing about the contract changes.
+
+### Why it is not a browser service
+
+A feed is served by whoever publishes it, and almost none of them send the
+`Access-Control-Allow-Origin` header a browser would need to read one. Fetching
+arbitrary feeds is therefore something a board can only do from a runtime that
+is not a browser. That is a fact about how feeds are published, not a
+preference — a browser-side version of this service would work for the handful
+of feeds whose publisher happened to opt in, and fail for the rest.
+
+### One slow feed costs its own rows
+
+The feeds are fetched concurrently and their failures are kept apart. A feed
+that is down, slow, or no longer a feed produces an entry in `errors` and the
+others still arrive. A reader missing one source is still a reader; one showing
+nothing because a single site is having a bad morning is not.
+
+---
+
+## The article shape
+
+| Field | What it is |
+|---|---|
+| `id` | The feed's own identity for the item — `guid`, `id`, or the link |
+| `title` | The headline |
+| `link` | Where to read it; `""` when the feed offered no readable address |
+| `author` | Who wrote it, where the feed says |
+| `summary` | A line about it, with its markup stripped, trimmed to `summaryChars` |
+| `published` | When, ISO 8601; `""` when the feed did not say |
+| `publishedMs` | The same instant in epoch milliseconds — what the sort uses |
+| `publishedLabel` | The same instant as `YYYY-MM-DD HH:mm`, in UTC |
+| `feed` | What the source is called |
+| `feedUrl` | Which feed it came from |
+
+An item with no date sorts **last** rather than as *now*, so a feed that omits
+dates cannot crowd out the ones that keep them.
+
+`publishedLabel` exists because a merged list shows a date on every row, and a
+board has no date formatter to derive one with. It is UTC, because the
+formatting happens wherever the runtime is and that is not where the reader is.
+
+Atom entries carry both a publication and an update date, and the publication
+date wins: a list sorted by *last touched* reorders itself when a publisher
+fixes a typo in something from last week, which is not what a reader looking
+for what is new is asking to see.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `feeds` | `array` | `[]` | The subscriptions. Each entry is a URL string, or `{ url, name }` |
+| `limit` | `number` | `60` | Most articles to emit, after merging and sorting |
+| `timeoutMs` | `number` | `10000` | How long one feed gets to answer |
+| `summaryChars` | `number` | `240` | Longest summary kept; `0` drops summaries |
+| `fetching` | `boolean` | — | Read-only: whether a round is in flight |
+
+A feed's `name` is what the list shows as the source. Left empty, the feed's own
+title is used, and failing that its host.
+
+### Commands
+
+Three configure keys are instructions rather than settings, because a facade
+has a field and a button rather than an editor for a whole list:
+
+| Key | What it does |
+|---|---|
+| `addFeed` | Subscribes to a URL (or `{ url, name }`); a feed already on the list is not added twice |
+| `removeFeed` | Unsubscribes the URL given |
+| `refresh` | Fetches now — the same work `process` does |
+
+`refresh` exists because a panel is the one caller that cannot use `process`: a
+service on a remote runtime has no local instance for its UI to call, so
+`configure` is the only verb that reaches it. Injector's `inject` is the same
+arrangement for the same reason.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — it is a trigger, and its content is ignored |
+| **Output** | `null` immediately; the article array is pushed through the rest of the pipeline once the feeds answer |
+
+The articles do not exist when `process` returns, so they cannot be returned
+from it. Returning `null` stops the synchronous push and the rest of the
+pipeline is called with the list when it arrives — the inversion-of-control
+path a fetching service takes.
+
+### What it says while it works
+
+| Notification | When |
+|---|---|
+| `{ fetching: true, sources }` | A round has started |
+| `{ fetching: false, fetchedAt, sources, count, error, errors, items }` | It finished |
+| `{ feeds }` | The subscription list changed |
+
+`items` is notified but deliberately **not** part of the state a board is saved
+with: the articles are a fetch's result rather than a setting, they are large,
+and they are stale the moment they are written.
+
+The feed list is announced whenever it changes, not only returned to whoever
+changed it — a panel and a facade both render it, and only one of them made the
+call.
+
+---
+
+## A feed on this board
+
+A feed one unit publishes and another reads has no address until the board
+loads, so it is named the way every other endpoint is:
+
+```json
+{ "feeds": [{ "url": "hkp-mount://reader.node/feed-serve", "name": "Reading list" }] }
+```
+
+The board's coordinator resolves the reference and hands the address over; until
+it does, that feed reports `Waiting for …` in `errors` and the round carries on
+with whatever else is subscribed. One address per service, so one feed of a list
+may be a reference — the rest are URLs, which is what they are anyway.
+
+## Publishing one
+
+There is no service for this, and there does not need to be one: a feed is a
+document, and the statement that reads the rows can build it.
+
+```
+sql (the document) → map (an envelope) → http-server-subservices (publishes it)
+```
+
+- **`sql`** concatenates the rows into one document —
+  `group_concat(item, '' ORDER BY …)` does the joining that a Map cannot, since
+  the expression dialect has no reduce over an array.
+- **`map`** wraps it as
+  `{ meta: { status: 200, contentType: "application/rss+xml" }, body: … }`, which
+  is what makes the answer XML rather than JSON describing it.
+- **`http-server-subservices`** holds the last document it was handed in a slot
+  and serves that to every caller: an `onProcess` pipeline with a
+  [Hold](./hold.md) writing the slot, an `onRequest` pipeline with one reading
+  it. See [publishing a document](./http.md#publishing-a-document).
+
+Two things to get right, both of which are silent when wrong:
+
+- **Escape every interpolated field.** A `&` in a link — almost every feed URL
+  has one — is not XML. `CDATA` covers the text fields with a single `replace`
+  of `]]>`; a `replace` chain covers the URLs.
+- **`||` propagates NULL**, so one absent column removes the whole item from the
+  document rather than producing an empty element. `IFNULL` anything nullable.
+
+The document is rebuilt by the **act of changing the rows**, not per request: a
+save runs the chain, the chain hands the endpoint a new document, and every
+subscriber after that is answered from the slot. So a hundred subscribers cost
+one SQL pass between them — and a pass that stops before reaching the endpoint
+(an `iterator` with nothing to iterate) leaves it serving the previous document,
+which is why the boards that publish this way give the publishing side a clock
+of its own.
+
+The services after an endpoint still run on every request, so a board that
+publishes two documents gives each its own runtime rather than putting both
+chains in one: a request should not drag a tail of SQL behind it.
+
+See `rss-radio-board.json` for both halves: a reading list published as a feed,
+and a second board reading it as one.
+
+---
+
+## Reading a feed without a parser
+
+The feed is read by a scanner over the markup rather than by a general XML
+parser. That is the honest description of its range: it finds the element
+boundaries the three formats use, unwraps CDATA, and decodes the entities that
+appear in feed text — including the doubly-escaped ones publishing systems
+produce, and HTML that arrives escaped rather than in CDATA. A document that
+would need a real parser to read is out of its range, and the answer for one is
+a parser, not more regular expressions.
+
+A document with no items reads as **no items**, not as an error: a board shows
+that as a feed that said nothing, which is something it can act on.
+
+---
+
+## Typical uses
+
+A reader, with a database behind it:
+
+```
+Timer → RSS → Stopper                    (the refresh, which is a read)
+        SQL (insert) → SQL (query)       (what a facade's Save button processes)
+```
+
+The refresh ends in a [Stopper](./stopper.md) so the article list is notified
+and goes no further; without it every refresh would push the whole list into
+the insert. See `boards/rss-demo-board.json`.
+
+Watching one feed for something in particular:
+
+```
+Timer → RSS → Filter → Telegram Sender
+```
+
+Feeding a model what a field is saying today:
+
+```
+Injector → RSS → Map → Text Generation
+```

package/bundle/docs/content/services/select.md

@@ -0,0 +1,47 @@
+# Select
+
+Picks a single element from an array by zero-based index.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/select` |
+
+---
+
+## What it does
+
+Select returns the element at position `arrayIndex` from an array input. If the input is not an array, or if `arrayIndex` has not been configured, the input is returned unchanged with a console warning.
+
+Use Select after services that emit arrays (e.g. [Buffer](./buffer.md), [Filter](./filter.md), [Sort](./sort.md)) when you want to extract a specific element for downstream processing.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `arrayIndex` | `number` | `undefined` | Zero-based index of the element to return |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Array (preferred); any value |
+| **Output** | `params[arrayIndex]` for array inputs; original value otherwise |
+
+---
+
+## Example
+
+```json
+{ "arrayIndex": 0 }
+```
+
+Input: `["first", "second", "third"]`
+Output: `"first"`

package/bundle/docs/content/services/sign.md

@@ -0,0 +1,53 @@
+# Sign
+
+Computes an HMAC signature of any pipeline value using the Web Crypto API.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/sign` |
+
+---
+
+## What it does
+
+Sign stringifies the incoming value (or uses raw bytes for typed arrays), computes an HMAC over the data using the configured secret, and emits the digest as a hex or base64 string.
+
+A **progressive mode** (`HmacSHA256p`) buffers successive inputs and produces the HMAC over all accumulated data when `configure({ finalize: true })` is called.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `method` | `string` | `"HmacSHA256"` | HMAC algorithm. One of `"HmacSHA256"`, `"HmacSHA512"`, `"HmacSHA1"`, `"HmacSHA256p"` |
+| `encoding` | `"hex"` \| `"base64"` | `"hex"` | Output encoding for the signature |
+| `secret` | `string` | `"secret key 123"` | Shared secret used as the HMAC key |
+| `finalize` | `boolean` | — | **Progressive mode only** — computes and emits the HMAC over all buffered chunks |
+
+### Progressive mode (`HmacSHA256p`)
+
+1. Set `method: "HmacSHA256p"` and configure `secret`.
+2. Send successive values through `process()` — each chunk is buffered.
+3. Call `configure({ finalize: true })` to compute the HMAC over all chunks and emit the result via `app.next()`.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — stringified with `JSON.stringify`; `Uint8Array`/`ArrayBuffer` used directly |
+| **Output** | Hex or base64 HMAC string |
+
+In `HmacSHA256p` mode, `process()` returns `null` and the final signature is emitted asynchronously after `finalize`.
+
+---
+
+## Pairing with Hash
+
+Use **Sign** when you need authenticity (HMAC requires a shared secret). Use **Hash** when you only need integrity (no secret).

package/bundle/docs/content/services/skill-router.md

@@ -0,0 +1,154 @@
+# Skill Router
+
+Matches free-form text — e.g. a voice transcript — against a configured set of skills with a local LLM and dispatches the matched skill's board with extracted parameters.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Python (hkp-python) | `skill-router` |
+
+---
+
+## What it does
+
+Skill Router takes a request in natural language, asks a locally hosted LLM
+which configured skill it matches, extracts the skill's parameters from the
+request, and emits `{ "board": ..., "payload": ... }`. A browser
+**Board-Service** in `input` board-source mode then plays that saved board
+with the payload. Everything runs locally.
+
+A skill is described declaratively:
+
+```json
+{
+  "action": "send notification",
+  "board": "send ntfy",
+  "payload": { "topic": "the ntfy topic", "message": "the message text" }
+}
+```
+
+The payload template's keys are the parameter names; its values describe to
+the model what to extract from the request.
+
+On a match the routing decision is final: the result is early-returned,
+skipping any services after the router in the same runtime. The `noMatch`
+config decides the other branch: `stop` (default) ends the pipeline,
+`forward` passes the original input on to the remaining services — e.g. a
+**Text Generation** fallback that answers requests no skill covers.
+
+The same two LLM backends as Text Generation are available, selected by the
+`backend` state: `server` (default, any OpenAI-compatible local server) or
+`local` (in-process GGUF via `llama-cpp-python`).
+
+---
+
+## Live visibility
+
+The service has a dedicated UI panel built around a single **process view**
+that shows each routing run end to end as it happens:
+
+- the composed **prompt** (system instructions + skills + request),
+- the **model output** as it is being generated, chat-bot style (the
+  service consumes the model stream token by token — `stream` state,
+  default on — and notifies the growing text as `{streamText}`),
+- the final **decision** — matched action, target board, extracted payload —
+  or "no match".
+
+The pipeline output is unaffected by streaming: the routing decision is
+still emitted once, when generation finishes. Set `stream: false` for
+servers that do not support server-sent events; the process view then
+shows the output once it is complete.
+
+The panel also contains a **visual skill editor**: each skill shows as a
+compact card (action, target board, parameter names). Clicking a card — or
+**Add Skill** — opens an edit dialog with `action` and `board` input fields
+and a JSON editor for the payload template. **Apply** validates the entry,
+reconfigures the router, and closes the dialog; **Delete** removes the
+skill; closing the dialog discards the draft.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `skills` | `array` | `[]` | Skills as `{action, board, payload}`; malformed entries are dropped |
+| `noMatch` | `string` | `"stop"` | `stop` ends the pipeline; `forward` passes the input to the services after the router |
+| `stream` | `bool` | `true` | Stream the model output token by token into the UI |
+| `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) |
+| `temperature` | `number` | `0.1` | Sampling temperature (routing wants determinism) |
+| `maxTokens` | `number` | `256` | Completion token budget |
+| `timeoutSec` | `number` | `120` | Server backend: request timeout |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `String` request, or JSON with `text` or `prompt` (the Speech To Text output pipes straight in) |
+| **Output** | Match: `{ "board": string, "payload": object }` (early-returned). No match: pipeline stops, or the original input is forwarded (`noMatch: "forward"`) |
+
+Only parameters the skill declares are kept in the payload; extra fields
+the model invents are filtered out. Backend errors produce
+`{ "error": "..." }` with a hint instead of crashing the pipeline.
+
+---
+
+## Notifications
+
+| Key | Meaning |
+|---|---|
+| `status` | `idle`, `loading` (local model load), `routing`, `error` |
+| `lastRequest`, `lastPrompt` | The request text and the composed chat messages |
+| `streamText` | The model output accumulated so far (`streamDone: true` on the last one) |
+| `lastOutput` | The complete model output, thinking stripped |
+| `matched` | Final decision: the matched action (with `board`, `payload`, `durationMs`) or `null` |
+
+`lastRequest`, `lastPrompt`, `lastOutput`, and `lastMatch` are also part of
+the service state, so the panel restores the most recent run when reopened.
+
+---
+
+## Example
+
+`boards/voice-assistant-skills-local-demo-board.json` wires the full loop:
+speech-to-text → skill-router (with a text-generation fallback via
+`noMatch: "forward"`) → board dispatch. A minimal text-only version:
+
+```json
+{
+  "python": [
+    {
+      "serviceId": "skill-router",
+      "state": {
+        "backend": "local",
+        "modelPath": "~/models/Qwen3-0.6B-Q8_0.gguf",
+        "skills": [
+          {
+            "action": "send notification",
+            "board": "send ntfy",
+            "payload": { "topic": "the ntfy topic", "message": "the message text" }
+          }
+        ]
+      }
+    }
+  ],
+  "ui": [
+    { "serviceId": "hookup.to/service/board", "state": { "boardSource": "input" } }
+  ]
+}
+```
+
+Start the Python runtime (`hkp-python`), keep it under the name `python` in
+*Manage runtime servers*, open the board,
+and inject a request like *"send a notification to topic home saying dinner
+is ready"*.

package/bundle/docs/content/services/smooth.md

@@ -0,0 +1,59 @@
+# Smooth
+
+Applies an exponential moving average (EMA) to numeric pipeline values to reduce noise and sharp transitions.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/smooth` |
+
+---
+
+## What it does
+
+Smooth maintains a running `current` value. On each tick it blends the incoming value toward `current` using the formula:
+
+```
+current += (target - current) * factor
+```
+
+- `factor = 0` — frozen (current never changes)
+- `factor = 1` — instant tracking (output equals input)
+- `factor = 0.1` — slow, heavily smoothed follow
+
+On the very first tick the `current` is initialised directly to the input (no blending).
+
+For object inputs, the EMA is applied independently to each numeric property. Non-numeric properties are copied as-is.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `factor` | `number` | `0.1` | EMA blend factor, clamped to [0, 1] |
+| `reset` | `boolean` | — | When `true`, clears `current` so the next tick re-initialises from scratch |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `number` or object with numeric fields |
+| **Output** | Same shape as input, with values blended toward the target |
+
+`null` inputs are returned as-is without affecting the running average.
+
+---
+
+## Example: smooth a noisy sensor reading
+
+```json
+{ "factor": 0.05 }
+```
+
+A `factor` of `0.05` produces a very sluggish follow suitable for dampening jittery sensor data or camera-based position estimates.

package/bundle/docs/content/services/smtp-email.md

@@ -0,0 +1,129 @@
+# SMTP Email
+
+Sends mail. Addressed by its configuration, or by whatever the pass is carrying.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| hkp-node | `smtp-email` |
+
+---
+
+## Two ways of being addressed
+
+The board says which, with `mode`.
+
+**`configured`** is a fixed destination — an alert sink, a daily digest, one
+address written down once. The input is the body and nothing else: a string is
+sent as-is, anything else is JSON-serialised. The input is then passed on
+unchanged, because this is a step in a pipeline that is about something else.
+
+**`envelope`** is a reply. The recipient, subject and body all come from the
+input, because they belong to whichever exchange this pass is about. What comes
+out is the message that was sent.
+
+Keeping that behind a mode, rather than letting the input win wherever it says
+something, is deliberate. Everywhere else in HKP the input decides over the
+configuration — `conversations` resolves a conversation id that way, `store` a
+key. Mail is the exception: a `to` field drifting down a pipeline must not be
+able to redirect a message that was addressed by configuration.
+
+---
+
+## Sending is awaited
+
+In both modes. A send is not a notification that can be left to happen.
+
+What follows it in a pipeline may file the message, mark a draft as sent, or
+move a conversation on — and every one of those would be recording something
+that had not happened yet, or had failed. **A failed send produces nothing**, so
+the pipeline stops rather than continuing on that basis.
+
+---
+
+## Threading
+
+`envelope` mode carries `inReplyTo` and `references` through to the message.
+These are not decoration.
+
+A reply that omits them starts a new thread in the recipient's client. Worse,
+when they answer it, their `In-Reply-To` names a message that
+[Conversations](./conversations.md) has never seen — so `threadOf` matches
+nothing and **one exchange quietly becomes two conversations**, days later and
+nowhere near the mistake that caused it.
+
+The other half of that is filing what was sent. The message this service
+answers with is already in the shape `conversations` ingests, so the two wire up
+with nothing in between:
+
+```
+map (build the envelope) → smtp-email (envelope) → conversations (ingest, outbound)
+```
+
+Angle brackets are header syntax: they go on at the transport and come off in
+the answer, so the same message compares equal wherever it was read from.
+
+---
+
+## Who it may write to
+
+`allowedRecipients` is a list of addresses, or of domains written as
+`@example.com`. An empty list allows everything, which is what a board that has
+not thought about it gets.
+
+Worth thinking about when the address is **data** — when it came out of a thread,
+or the step that sends was chosen by a model. A person approving a draft is
+approving the text; nobody approved the destination.
+
+A message with several recipients is refused whole if any one of them is not
+allowed.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `string` | `"configured"` | `configured` or `envelope` |
+| `host` | `string` | `""` | SMTP server hostname |
+| `port` | `number` | `587` | SMTP server port |
+| `username` | `string` | `""` | SMTP authentication username |
+| `password` | `string` | `""` | Write-only: never echoed back. `passwordConfigured` says whether one is set |
+| `tls` | `boolean` | `true` | Use TLS (`secure` in nodemailer) |
+| `from` | `string` | `""` | Sender address; `envelope` mode may override it per message |
+| `to` | `string` | `""` | Recipient — `configured` mode only |
+| `subject` | `string` | `""` | Subject — `configured` mode only, and the fallback in `envelope` mode |
+| `allowedRecipients` | `array` | `[]` | Addresses or `@domains` this may send to. Empty = unrestricted |
+
+---
+
+## Input / Output
+
+**`configured`**
+
+| | Shape |
+|---|---|
+| **Input** | any value — strings sent as-is, anything else JSON-serialised |
+| **Output** | the same input, once it has been sent |
+
+**`envelope`**
+
+| | Shape |
+|---|---|
+| **Input** | `{ to, subject, body, from?, inReplyTo?, references? }` — `to` may be a list |
+| **Output** | `{ messageId, from, to, subject, body, date, direction: "outbound", inReplyTo?, references? }` |
+
+Either mode produces **nothing** when the send failed, or when it has not been
+given enough to send with.
+
+---
+
+## Typical uses
+
+- Timer → SMTP Email — periodic digest from a scheduled ping
+- HTTP Server → SMTP Email → Monitor — an alert on every inbound request
+- Conversations → Map → SMTP Email → Conversations — reply to a thread and file
+  the reply back into it