@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/concepts/mounts.md

@@ -0,0 +1,314 @@
+# Mounts
+
+How a service that must be reachable from outside the board gets an address, and how another service points at it without knowing that address in advance.
+
+---
+
+## The problem
+
+Most services only talk to the service next to them in the pipeline. A few have
+to be reachable by something that is not part of the board at all: a webhook
+posted by someone else's product, a phone scanning a QR code, a PeerJS client
+looking for its signalling server, or a service on another runtime — possibly on
+another machine — calling in.
+
+Those services need an address, and originally each one bound a port it chose.
+That broke in three separate ways:
+
+- **Ports are a single machine-wide namespace.** With several tenants sharing one
+  hkp-node, a service asking for port 8081 is a land grab: the second claimant
+  fails to start, and whoever wins receives traffic the other one expected.
+- **Runtime ids are only unique per tenant.** Boards ship stable ids like `node`
+  or `chat-node`, and hkp-node namespaces runtimes by the authenticated user, so
+  two people can load the same board without colliding. Such an id cannot appear
+  in a publicly routable path.
+- **These endpoints are deliberately unauthenticated.** They exist to be called
+  by outside parties who hold no token, so something other than a credential has
+  to gate access.
+
+---
+
+## What a mount is
+
+A **mount** is an endpoint that a service's *runtime* assigns to it, rather than
+one the service claims for itself. The runtime serves it on its own server under
+an opaque path:
+
+```
+http://<host>:<port>/hosted/<mountId>
+```
+
+and publishes the resulting address in the service's own state, in the reserved
+field `__hkpMount`. The service never learns a port; it asks its host for a
+mount and gets back a URL.
+
+Because the endpoint is unauthenticated by design, **the unguessable id is the
+capability**: knowing the address is what it takes to reach it, and the address
+carries no user identifier that a public URL would otherwise leak.
+
+---
+
+## Why the id is derived, not drawn
+
+The id is an HMAC of everything that identifies the mount — the owner, the
+board, the runtime, and what the mount is called (`mountName`, defaulting to the
+service's uuid) — keyed by a secret only the server holds (`HKP_MOUNT_SECRET`,
+otherwise persisted per server at `~/.hkp/node-<instance>/mount-secret` or
+`~/.hkp/python/mount-secret`).
+
+Random ids were the first implementation. They were just as unguessable, but the
+address changed every time a board loaded — so a webhook configured by hand in
+somebody else's product broke on every restart, and a board could not be
+redeployed without reconfiguring its callers.
+
+Deriving the id keeps the address stable across reloads, restarts and redeploys
+while keeping the secret out of the board. The board says only what the mount is
+*called*, which is not sensitive. Renaming one mount rotates that one address;
+rotating the server's secret rotates all of them.
+
+---
+
+## More than one claim to an address
+
+Because the address is derived from what the mount is called, more than one
+runtime can derive the same one:
+
+- a runtime rebuilt under its id claims the address before the one it replaces
+  lets go;
+- a board that is deployed and also open in the playground has two copies of
+  each of its mounts on the server — the deployed board's runtimes and the
+  playground's are kept apart (`concepts/cloud-boards.md`), their addresses
+  are not.
+
+A runtime server keeps every claim and lets one answer: a **deployed board's
+before a client's**, and the newest of its kind. Releasing a claim releases
+that claim only, and the address stays with whoever still holds one. So
+opening a deployed board does not take its endpoint, closing it again does not
+take the endpoint away, and the playground's copy answers only where no
+deployed board claims the address.
+
+The same on all three: `hkp-node/src/mounts.ts`, `hkp-python/src/hkp/mounts.py`,
+`hkp-rt/lib/src/http/front_door.cpp`.
+
+---
+
+## What each runtime actually does
+
+"Mount" is the board-wide vocabulary. Every runtime server assigns a path on its
+own port; hkp-rt does so where its host has turned that on:
+
+| Runtime | How a hosted service becomes reachable | Published address |
+|---|---|---|
+| hkp-node | mount path on the runtime's shared server | `http://host:port/hosted/<mountId>` |
+| hkp-python | same | `http://host:port/hosted/<mountId>` |
+| hkp-rt, standalone or in a container | same | `http://host:port/hosted/<mountId>`, or under `HKP_EXTERNAL_URL` |
+| hkp-rt, embedded in an app | binds a port of its own | `http://<lan-ip>:<port>/` |
+| Browser | hosts nothing; it consumes mounts | — |
+
+Services that own a mount today: `http-server-subservices` (node, python,
+hkp-rt), `http-server` (hkp-rt), `peer-server` (node, hkp-rt) and
+`websocket-reader` (node).
+
+### hkp-rt
+
+The id is derived exactly as hkp-node derives it, with an empty tenant — hkp-rt
+has one — so the same board on the same secret gets the same address. The
+secret is `HKP_MOUNT_SECRET`, else kept at `~/.hkp/cpp/mount-secret`.
+
+How a mounted request is served differs from the other two, because an hkp-rt
+endpoint may hold a response open and stream into it, which the server's REST
+framework cannot do. So the server's port is a **front door**
+(`hkp-rt/lib/src/http/front_door.cpp`): a connection whose first request is for
+`/hosted/<id>` is handed, socket and all, to the service that owns the mount;
+anything else is passed through to the REST api, which listens on loopback on a
+port nobody is told. Two things follow:
+
+- **One request per connection.** Who a connection belongs to is decided once,
+  so what is passed through to the api is marked `Connection: close`. A
+  WebSocket upgrade is passed through as one.
+- **The api still knows who is calling.** It trusts the machine's own UI without
+  a token, by the caller's address — and passed through, everything comes from
+  the same process. The front door says who the caller was in a header the api
+  believes only beside a secret this process alone knows; both are removed from
+  anything a caller sent.
+
+Mounted, `host` and `port` in a board are accepted and not acted on.
+`mountName` names the mount, defaulting to the service's id.
+
+A host turns this on with `Server::enableMounts`. The standalone server does.
+**The apps do not yet**: there an endpoint still binds the port its board names,
+`"port": 0` asks the operating system for any free one, and whatever it got is
+what the service reports and a saved board records. See the gaps below.
+
+---
+
+## Pointing at a mount
+
+Since the address is assigned when the board loads, a board cannot hard-code it.
+So a board names the **service** instead, and the address is resolved at connect
+time.
+
+Two things, with one job each:
+
+| | Written by | Holds |
+|---|---|---|
+| the service's own target field (`url`, `peerHost`, …) | a person | a `hkp-mount://<runtimeId>/<serviceUuid>` reference, or a plain address |
+| `__hkpMount` | machinery | the address a mount currently has — published by the owner, written onto a consumer by the coordinator |
+
+```json
+{
+  "serviceId": "http-client",
+  "state": {
+    "url": "hkp-mount://endpoint-node/echo-server",
+    "path": "/hello"
+  }
+}
+```
+
+A consumer prefers `__hkpMount` when it holds an address and falls back to its
+own field; a reference in *either* means "not resolved yet" rather than
+something to dial. Because the two live in separate fields, resolution never
+overwrites what was written — so a board saves and reopens with its reference
+intact.
+
+References are found by their **scheme**, wherever they appear in a service's
+state, rather than by living in one agreed field. That is what lets a reference
+go in whatever field a service already calls its target, and it is safe because
+a `hkp-mount://` value cannot be mistaken for anything else — the same reason
+`{{secret.…}}` is resolved wherever it occurs. A bare
+`<runtimeId>/<serviceUuid>` would *not* be safe: it is indistinguishable from a
+relative URL, and the hosts these boards run on resolve those against a base
+that differs between builds (`hkp://` packaged, `http://` in dev). It is
+deliberately not a path under the existing `hkp://` scheme either — that one
+addresses servable resources, and a reference is not one.
+
+Boards written before the split put the reference in `__hkpMount` itself. Those
+keep working: it is a string in service state like any other, and it is found
+the same way.
+
+---
+
+## Who resolves a reference
+
+Resolving one needs a view of the **whole board** — a runtime sees only its own
+services, while a reference names a service somewhere else, possibly on another
+machine. That view belongs to the board's **coordinator**, the instance that
+owns the board: the browser for a playground or Readymade board, hkp-node for a
+cloud board.
+
+Two paths, depending on where the consumer lives:
+
+- **A service the browser hosts** asks the coordinator whenever it needs the
+  address (`coordinator.resolveMount`), and retries. Peer Socket does this at
+  connect time.
+- **A service on a remote runtime** cannot ask, so the coordinator pushes: as
+  soon as an address exists, it configures the consumer with the plain address —
+  the same value that service would have received had the board been exported.
+
+An unresolved reference is **normal, not an error**. A board restores its
+runtimes concurrently, so when a consumer is created its owner has usually not
+published anything yet; a mount can also appear much later, when someone
+unbypasses a server by hand. Consumers therefore wait rather than calling
+something else.
+
+---
+
+## Exporting, forking, and the reserved prefix
+
+- **Export** substitutes the resolved address into the same field. A board sent
+  to another device is not the board that holds the referenced runtime — a
+  partner board drops runtimes the partner cannot reach — so a reference sent as
+  such would leave the receiver waiting forever. Because both forms live in one
+  field, the receiving service reads it exactly as it always does and needs to
+  know nothing about export. References that cannot be resolved are left
+  untouched rather than blanked, so a board exported before its runtime came up
+  still describes what it wanted.
+- **Forking** a board regenerates every runtime id and service uuid, and rewrites
+  the ids *inside* mount references along with them, so the copy points at the
+  copy. An address rather than a reference is left alone: it may name something
+  outside this board entirely.
+- **The `__hkp` prefix** marks a state property whose meaning is defined outside
+  the service holding it — generic board machinery reads and rewrites it. The
+  name is reserved: services must not use it for anything else.
+
+---
+
+## Worked example
+
+`mounted-endpoint-demo-board.json`: one hkp-node runtime hosts an endpoint, another
+calls it, and no address appears anywhere in the board.
+
+```json
+{
+  "services": {
+    "endpoint-node": [
+      {
+        "uuid": "echo-server",
+        "serviceId": "http-server-subservices",
+        "state": { "bypass": false, "pipeline": [ … ] }
+      }
+    ],
+    "caller-node": [
+      {
+        "uuid": "call",
+        "serviceId": "http-client",
+        "state": { "__hkpMount": "hkp-mount://endpoint-node/echo-server" }
+      }
+    ]
+  }
+}
+```
+
+On load, `echo-server` receives a mount and publishes its address into its own
+`__hkpMount`. The coordinator sees both runtimes, matches the reference held by
+`call`, and configures it with that address. The client starts calling.
+
+---
+
+## Known gaps
+
+Current limitations, stated so a board author is not surprised by them:
+
+- **References name ids, not names.** `hkp-mount://<runtimeId>/<serviceUuid>`
+  only — a runtime's display name or a service's alias cannot be used, so
+  hand-written boards carry uuids.
+- **An unresolvable reference looks exactly like a slow one.** Both leave the
+  consumer waiting, so a typo in a reference produces no error, just silence.
+- **A board that still writes its reference into `__hkpMount` loses it on save.**
+  Serialization asks each service for its live state, and the coordinator has by
+  then written the resolved address into that field. Writing the reference in the
+  service's own field instead (`url`) avoids this entirely — nothing overwrites
+  it.
+- **One mount per consumer.** The resolved address has one field to go in, so a
+  service naming two mounts gets only the first resolved (and a warning). A
+  service that needs two should host a pipeline instead.
+- **hkp-rt embedded in an app still binds ports.** A standalone hkp-rt mounts
+  on its own port; the desktop and phone apps do not, because it changes who
+  can reach an endpoint. Today an endpoint in the desktop app binds every
+  interface whatever the app's *external access* setting says, and that is what
+  lets a phone reach it. Mounted, it would be reachable only as far as the
+  server's own port is — loopback, unless external access is on. Turning mounts
+  on there means the front door listening on every interface and refusing the
+  api to anyone but the machine itself, which is a decision about the app's
+  exposure and has not been taken.
+
+---
+
+## Where it lives in the code
+
+| Concern | File |
+|---|---|
+| Vocabulary: field, scheme, finding references | `hkp-frontend/src/runtime/board/mount.ts` (`parseMountRef`, `findMountRefs`) |
+| Resolution (browser as coordinator) | `hkp-frontend/src/core/coordinator.ts` |
+| Pushing addresses to remote consumers | `hkp-frontend/src/core/mountPublication.ts` |
+| Rewriting references when forking | `hkp-frontend/src/core/forkBoard.ts` |
+| Mount registry, id derivation | `hkp-node/src/mounts.ts`, `hkp-python/src/hkp/mounts.py` |
+| Resolution (hkp-node as coordinator) | `hkp-node/src/coordinator/session.ts` |
+| C++ vocabulary | `hkp-rt/lib/src/mount.h` |
+
+---
+
+See also: **Coordinator** (`concepts/coordinator.md`) for who resolves a
+reference, **Runtime** (`concepts/runtime.md`) for the host that assigns a
+mount, and **Units and compositions** (`concepts/units.md`) for what happens to
+a reference when a unit's runtime is renamed.

package/bundle/docs/content/concepts/presets.md

@@ -0,0 +1,360 @@
+# Presets
+
+A service's configuration as a file: written once, shared, and applied to any
+service of that kind on any runtime that hosts it.
+
+---
+
+## The problem
+
+Picking a service takes a second. Configuring it takes the afternoon.
+
+`http-client` is the clearest case. Adding one is trivial; making it call
+ElevenLabs is a URL, a path with a voice id in it, three headers one of which
+carries a key, a query parameter for the audio format, and a JSON body in the
+shape that API expects. None of that is *your* work — it is the same for
+everybody who calls that API, and it is written down in a reference manual
+somewhere. It is also, today, the part that cannot be handed to anyone:
+sharing it means sharing the whole board built around it.
+
+A board is the wrong unit for this. A board is an app. What a person wants to
+pass along is much smaller: *this service, set up this way.*
+
+---
+
+## What a preset is
+
+A JSON document naming a service and carrying its state:
+
+```json
+{
+  "preset": "v1",
+  "id": "elevenlabs-text-to-speech",
+  "name": "ElevenLabs — Text to speech",
+  "serviceId": "http-client",
+  "serviceName": "ElevenLabs TTS",
+  "description": "Renders text as speech …",
+  "runtimes": ["rest"],
+  "secrets": {
+    "elevenlabs": {
+      "label": "ElevenLabs API key",
+      "url": "https://elevenlabs.io/app/settings/api-keys"
+    }
+  },
+  "state": {
+    "url": "https://api.elevenlabs.io",
+    "path": "/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM",
+    "method": "post",
+    "query": { "output_format": "mp3_44100_128" },
+    "headers": {
+      "xi-api-key": "{{secret.elevenlabs}}",
+      "content-type": "application/json",
+      "accept": "audio/mpeg"
+    },
+    "body": "{\"text\": \"…\", \"model_id\": \"eleven_multilingual_v2\"}",
+    "timeoutMs": 30000
+  }
+}
+```
+
+| Field         | Required | What it is                                                                  |
+| ------------- | -------- | --------------------------------------------------------------------------- |
+| `preset`      | yes      | Format marker. `"v1"`, and how a preset file is recognised at all           |
+| `serviceId`   | yes      | The service this configures. Not a runtime                                  |
+| `name`        | yes      | What it is called in a menu                                                 |
+| `state`       | yes      | The service's **whole** configuration                                       |
+| `id`          | no       | Stable identity, unique per service. Derived from the name when absent      |
+| `serviceName` | no       | Names the instance when applied, and the palette card that offers it. Defaults to the preset's name when saved from a service |
+| `description` | no       | What it does, and what it expects on its input                              |
+| `version`     | no       | The author's revision of this preset. Not the format version                |
+| `author`, `homepage` | no | Who wrote it, and where the API is documented                          |
+| `tags`        | no       | What it *is* — the second axis the browser files it under                   |
+| `runtimes`    | no       | The runtime classes it suits — a hint shown to a person, never a restriction |
+| `secrets`     | no       | Display information for the aliases `state` refers to, keyed by alias       |
+| `params`      | no       | Defaults for the `{{param.name}}` references in `state`, substituted when the preset is applied |
+| `origin`      | no       | The URL it was imported from, as typed. Written on import; what *Update from source* reads again |
+
+A file holds one preset, or several under `{"presets": [ … ]}`.
+
+### It is keyed by service, not by runtime
+
+`http-client` exists on hkp-node and on hkp-rt with the same state contract, so
+one preset applies wherever the service is hosted. Matching is by the
+**canonical** service id: the browser's legacy `hookup.to/service/*` ids are
+aliases of the bare slugs the runtimes are converging on, and they stay, so both
+spellings name one service everywhere a preset is filed, listed or applied. `runtimes` says which side a
+preset is *meant* for — an API that sets no CORS headers, or a call carrying a
+credential, wants a remote runtime rather than the browser — but it is advice
+printed next to the name, not a rule that stops anything.
+
+### No runtime knows presets exist
+
+Applying one is an ordinary `configure` call. There is no preset support in
+hkp-node, hkp-rt, hkp-python or hkp-go, and none is needed: presets are a
+document format and a step in the playground.
+
+---
+
+## Applying replaces, it does not merge
+
+Applying a preset produces *exactly* the preset's configuration. Never a mix of
+it and whatever the service happened to hold.
+
+A half-applied preset is the worst of the available outcomes. A header or a
+body left behind from a previous API silently breaks the request, while the
+board looks exactly as the preset says it does. So `state` is the service's
+whole configuration, and applying one resets the service first.
+
+There is no cross-runtime "reset to defaults" call to do that with, and there
+should not be one — the runtime already knows how to build a fresh service, and
+that is what restoring a board does to every service it loads. Applying a
+preset therefore **recreates the instance**: removed, created again under the
+same uuid and at the same position, then configured. Facade widgets reference a
+service by uuid and a [mount](mounts.md) address is derived from one, so keeping
+it is what makes this an edit of a service rather than a replacement of it.
+
+**Order matters, and it is the part that breaks quietly.** The new instance is
+configured *before* the board is told it exists. A service panel initialises
+itself once per service object — it reads the configuration the first time it
+sees one, and after that only listens for notifications. Publish first and the
+panel meets the instance in the gap between its creation and its configuration:
+it shows the defaults, never hears the configure that follows, and the preset is
+applied while the panel says it is not.
+
+Two things survive that a preset does not touch:
+
+- **`__hkp*` state**, which belongs to board machinery rather than to the
+  service holding it — `__hkpMount` is an address a coordinator published onto
+  this instance. It is lifted off the old instance and put back on the new one.
+- **The service's name**, unless the preset gives a `serviceName`.
+
+---
+
+## Secrets travel as references
+
+A preset holds `{{secret.elevenlabs}}`, the same reference a board holds. The
+value is resolved at the point of use and never enters service state (see
+[secrets](../board-json.md)), which is what makes a preset safe to publish:
+there is nothing in the file to redact.
+
+The aliases a preset needs are **derived from its state**, not declared — the
+state is where an alias is actually used, so the list cannot fall out of step
+with what the preset does. The optional `secrets` block only says how to
+describe one to a person: what the key is called, and where to get one.
+
+A preset applies whether or not the key exists on this device. The panel says
+which alias is missing; it does not refuse to configure the service, because the
+preset is correct either way and the key is a separate errand.
+
+---
+
+## Where presets come from
+
+Two origins, no difference in how they apply:
+
+- **Built in** — shipped with the build, under `hkp-frontend/presets/<serviceId>/`
+  and listed in `hkp-frontend/src/presetRegistry.ts`. The equivalent of the demo
+  boards, and not deletable: there is nothing on the device to delete.
+- **Kept on this device** — imported from a disk or a URL, or saved from a
+  service that was already configured the way someone wanted to keep it.
+
+A preset fetched from a URL is fetched from whatever address serves the file; a
+GitHub page link is rewritten to the raw file behind it, so pasting the page you
+are looking at works.
+
+### Where the device keeps them
+
+Where is the host's business, the way where boards are saved is:
+
+| Host | Store |
+| --- | --- |
+| Web | `localStorage` |
+| Readymade desktop | `~/.hkp/presets/` |
+| Readymade iOS | `Documents/Presets/` in the app's container |
+| Readymade Android | `files/Presets/` in the app's storage |
+
+The native apps keep **files, one per preset** — the file as it was imported,
+or `<service>--<id>.json` for one saved from a service — served to the web app
+over `hkp://presets` (`GET` lists every file unparsed, `POST` and `DELETE` take
+a file name). So the folder *is* the library: it is read when the app starts,
+and a preset file put there by hand is in it the next time. A file holding
+several presets stays one file; changing or forgetting one of them rewrites it.
+A file that is not a preset is skipped and reported in the console, not
+refused. Presets an older build kept in `localStorage` are moved into the folder
+the first time; if the host cannot list its store they stay where they were.
+
+The seam is `PlatformCapabilities.presetStorage` (`platform/PlatformContext`),
+attached when the host's `PlatformProvider` renders; the store itself is in
+`core/presets.ts`.
+
+### Imported from a URL, updated when asked
+
+A preset imported from a URL remembers the address as `origin`, and the details
+column offers **Update from source**, which fetches it again and keeps the newer
+version in place of this device's copy. It never happens on its own: what an
+author publishes later reaches this device when someone decides to take it.
+A board that holds a copy of a block from the library keeps its copy either way.
+
+---
+
+## Two axes: the service, then what it is
+
+A preset is filed under **the service it configures**. That is the axis that
+decides what can be done with it — an `http-client` preset is applicable to an
+`http-client` and to nothing else — and it is the list a service's own menu
+shows.
+
+For most services that is the whole answer. Every `http-client` preset is a
+request to some API, so the service already says what its presets are.
+
+**It is not the answer for `sub-service`.** A sub-service's state *is* a
+pipeline, so a preset of one is a reusable building block made of other
+services — a meta-service. What those building blocks *do* varies completely: a
+Telegram responder, a spectral analyser, a geocoding lookup. They share a
+serviceId and nothing else. Filed by service alone they would be one
+undifferentiated bucket that only grows, and the more useful the mechanism is,
+the worse the bucket gets.
+
+So a preset says what it is, in `tags`:
+
+```json
+"tags": ["Messaging"]
+```
+
+and the browser puts a **tag column after the service column**:
+
+```
+Presets ▸ sub-service ▸ Messaging ▸ Telegram responder
+                      ▸ Audio     ▸ Spectral analyser
+```
+
+Tags work the way the folders in the board browser work: a preset with tags
+lives in each of its tag folders, and a preset with none sits in the service
+folder itself — the way an unfiled board sits at the root of its source. So the
+column appears exactly where someone has said something, and a service whose
+presets are untagged still reads as a plain list. That is why the presets this
+build ships carry no tags: a handful of `http-client` requests is a list, not a
+filing problem.
+
+Tags are compared without case — `Messaging` and `messaging` are one tag, not
+two folders that look alike — and kept in the spelling they first arrived in.
+
+**A tag is part of the file.** Refiling a preset rewrites it, which is what makes
+the filing travel: someone who imports your building block gets it filed the way
+you filed it. A preset is tagged when it is saved (the field is in the save
+dialog) and re-tagged in the details column; a shipped preset's tags are part of
+the build, like everything else about it.
+
+### What a sub-service preset is, and is not
+
+It is a pipeline, captured. Applying one rebuilds that pipeline inside the
+sub-service, because applying any preset replaces the service's whole state.
+
+It is less portable than a simple preset, for two reasons that are worth telling
+apart. The state names the nested services and carries their state, so a
+composed preset can only be applied where those services **exist** — that is
+real, and permanent, and `runtimes` is where to say which side it is meant for.
+
+The other reason is temporary: the browser's older service ids carry a
+`hookup.to/service/` prefix where the backend runtimes use a bare slug, so the
+same nested service is spelled two ways. The runtimes are converging on the bare
+slug, and the prefixed ids stay as aliases so existing boards keep loading.
+Anything asking *is this the same service* therefore asks it of the canonical id
+— which is what the Presets source files by, what a service's menu matches on,
+and what applying one checks — so a preset authored against either spelling
+applies to the other. Neither a board nor a preset is rewritten; they keep the
+id they were authored with.
+
+---
+
+## Where presets are used
+
+**Organising them is the start page's job.** The Presets source lists a folder
+per service that has one, and the presets themselves as the leaves — the same
+browser the boards are organised in, with a details column saying where a preset
+came from, what it needs, and what is in it, and the actions that belong to a
+file: export it, delete it. Importing one is the source's own action.
+
+**A composed preset is a building block, and sits in the palette.** A preset of
+`sub-service` is a pipeline someone built and kept — a service made of services
+— so the sidebar lists it beside the primitives, as a card of its own under its
+own name, dragged onto a runtime the same way. Dropping one creates the
+sub-service, names it after the preset and configures it from the preset, in
+that order: a panel reads a service's configuration once, when it first sees the
+instance, so the configure has to happen before the board is told the service
+exists.
+
+A card *is* the preset, so it carries the preset's name — not `serviceName`,
+which is the name a preset gives a service it is **applied** to, and which a
+preset captured from a service inherits from it (a second card called
+"SubService", beside the SubService primitive it came from).
+
+What is published to the board is the state the service holds after the
+configure, not the one its runtime answered the create with. A nested pipeline
+is rendered straight off the board's descriptor, so publishing the create's
+answer leaves a sub-service showing as empty while its runtime holds the whole
+pipeline — right in the configuration dialog, wrong on the board.
+
+A card appears only where the runtime has a `sub-service` to put it in, and only
+where the preset belongs — `runtimes` is how a composed preset says which side
+it was built for, since it names nested services that one registry has and
+another may not.
+
+**A composed preset with params is a block, and a drop uses it.** A
+sub-service preset that declares `params` is written to be placed several times
+with different values, so the palette marks it as a block and dropping it
+places a [use](blocks.md) rather than a copy: the preset's definition is copied
+into the board's own `blocks` — once; a second drop names the copy the board
+already holds — and the new entry is a use of it, varied from its bar. The board
+then opens anywhere, with or without this library. The library's card stays
+where it is and stands for the board's copy too; that copy gets a card of its
+own once it differs (after *Edit block*). Without `params` there is nothing to
+vary per use, and a drop applies the preset as above. The build ships one:
+**ntfy notification**, which sends its input as a push notification through
+[ntfy](https://ntfy.sh), with the topic, title, priority, tags and server as
+params. Its topic defaults to `readymade-{{random}}`: every use is given a
+topic of its own ([a value made for each use](blocks.md)), since anyone who
+knows an ntfy.sh topic can read it.
+
+**Picking one is the playground's job.** A service's menu has a *Presets*
+submenu listing what is available for that service and nothing else. The menu
+answers one question — which preset do I want on this service — and a list of
+names is the whole of that answer; a panel there would be a second place to
+manage the same files.
+
+The one action that cannot live on the start page is the reverse direction:
+what is worth keeping is a service someone has working in front of them, and
+that only exists in a board. So *Save configuration…* sits at the foot of the
+same submenu, and what it produces is an ordinary preset on this device — in the
+Presets source, in every menu for that service, and exportable as a file, which
+is the only form in which it reaches anybody else.
+
+On a phone both are one row of a service's sheet, **Presets**, which opens the
+list and the saving in one sheet; the add-service sheet offers composed presets
+and blocks behind its Building Blocks tab, from the same list the sidebar draws
+(`core/palette.ts`). The iOS and Android apps keep presets as files in their
+presets folder (`hkp://presets`), as the desktop does. A deployed board can be
+saved from but not applied to: applying recreates the service.
+
+The two surfaces read one list. The store says when it changes, because
+`localStorage` reports nothing to the tab that wrote it, a native host's folder
+is read after the app has started, and a preset imported on the start page has
+to appear in the playground's menu without a reload.
+
+---
+
+## Presets, sub-services and units
+
+A `SubService`'s state *is* its pipeline, so a preset of one is a reusable
+pipeline — several services, wired in order, as one file. This needs no second
+mechanism: it is an ordinary preset whose `state` happens to contain a list of
+services. What it needs is a way to say what it is, which is what tags are for.
+
+That is a different thing from [units](units.md), which assemble whole
+*runtimes* into a board. A preset never crosses a service boundary; a unit never
+reaches inside one.
+
+And it is the same document as a [block](blocks.md), with the other verb: a
+preset is *applied* — copied, independent from then on — while a block is
+*used*, and every use follows its definition. A block is read as a preset without
+the format marker, and `params` means the same in both.