@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/testing.md

@@ -0,0 +1,263 @@
+# Testing
+
+What runs where — the per-area suites that check the parts, and the end-to-end suite that checks the thing a person actually touches.
+
+---
+
+## Two layers, two different questions
+
+The suites answer different questions, and knowing which is which saves writing
+a test in the wrong place:
+
+| | Asks | Runs in | Takes |
+|---|---|---|---|
+| **Per-area suites** | Does this part behave? | its own process — jsdom, pytest, ctest | seconds to a couple of minutes |
+| **End-to-end** | Does the app a person opens work? | a real browser, on each host it ships inside | minutes |
+
+A rule that follows: anything expressible without a browser belongs in a
+per-area suite, because that is where a failure names the function that broke.
+The end-to-end suite is for what only exists once everything is assembled — a
+board opening, a shell mounting, a pipeline actually running.
+
+---
+
+## The per-area suites
+
+`run-all-tests.sh` at the root runs all seven, in order:
+
+| Area | Framework | Its own command | What it holds |
+|---|---|---|---|
+| hkp-python | pytest | `./run_tests.sh` | runtime, services, auth, mounts, the board log |
+| hkp-node | vitest | `npm test` | the same ground, plus the coordinator and its stores |
+| hkp-rt | Catch2 + ctest | `./run-tests.sh` | the C++ runtime and its services |
+| Readymade app backend | Catch2 | `./run-tests.sh` | the desktop shell's rules — routing, settings, grants, the share inbox |
+| hkp-frontend demo boards | vitest | `npm run test -- src/runtime/browser/tests/demo-boards.regression.test.tsx` | every board in `boards/`, checked against the registry |
+| hkp-frontend | vitest | `npm run test -- --exclude …` | everything else in the frontend |
+| readymade-mcp | tsc + vitest | `npm run typecheck && npm test` | the MCP knowledge server: its index of `docs/content` and `boards/`, path confinement, contracts — including that every service page is readable as one |
+
+Two things about the runner are deliberate. It **does not stop at the first
+failure** — it records a pass or fail per suite and prints the table at the end,
+so one run tells you everything that is broken rather than the first thing. And
+each suite is also runnable on its own, from its own directory, which is what
+you want while working inside one.
+
+The desktop backend's suite is built **without saucer, vcpkg or hkp-rt** on
+purpose: it covers rules the backend keeps apart from its webview-facing code,
+so it compiles in seconds instead of requiring a full app build. That separation
+is the reason those rules have tests at all.
+
+`run-all-cpp-tests.sh` is the C++ half on its own, against an existing `./build`.
+
+---
+
+## End-to-end
+
+`e2e/` holds one Playwright suite that drives the **same webapp as each of the
+hosts it ships inside**:
+
+| Project | App | Engine | Platform host |
+|---|---|---|---|
+| `web` | `hkp-frontend` | Chromium | none — signed out, no capabilities |
+| `desktop` | `meander/frontend` | Chromium | fake saucer + `hkp://` scheme |
+| `mobile` | `meander/frontend` | WebKit, iPhone descriptor | the same fake, mounting `MobileApp` |
+
+```
+cd e2e
+npm install && npx playwright install chromium webkit
+npm test                 # all three profiles
+npm run test:desktop     # one of them
+npm run test:ui          # pick, watch, time-travel
+npm run report           # the last run
+```
+
+The dev servers start themselves (`webServer` in `e2e/playwright.config.ts`) and
+an already-running one is reused, so a `vite` you already have is picked up
+rather than fought over.
+
+A profile is a **host**, not a screen size. `mobile` runs WebKit on an iPhone
+device descriptor because that is what the iOS app is — a WKWebView with real
+touch — and the shell has gesture code that a synthetic click would skip
+entirely. Writing a spec once and telling it which host it is on is what keeps
+three targets from becoming three suites.
+
+### Standing in for the native side
+
+`e2e/support/fakeNativeHost.ts` implements both surfaces the Readymade shells
+reach the platform through: `window.saucer.exposed.*` (file dialogs, the secret
+store) and `fetch("hkp://…")` (boards, remotes, settings, the start-page tree).
+
+Two consequences worth knowing before writing a spec:
+
+- **It is installed as a page init script, and has to be.** The app decides what
+  host it is on *while its modules evaluate* — `isMeanderApp()` memoises a single
+  `hkp://boards/` probe, and `MeanderPlatformProvider` reads `saucer.exposed` at
+  module scope. Anything installed after the first navigation produces a
+  confusing half-native app rather than a clean failure.
+- **`page.route` cannot serve any of it.** `hkp://` is not http, so it never
+  reaches Playwright's proxy; wrapping `window.fetch` is the only way in.
+
+What the host was asked to store is mirrored on `window.__HKP_FAKE_HOST__` and
+reachable through the `hostState()` fixture, so a spec can assert on what the app
+handed the platform rather than only on what the UI shows.
+
+**The blind spot is the boundary itself.** Rename a `saucer.exposed` function or
+change an `hkp://` route and this suite stays green while the shipped app
+breaks. The fake is written against `BackendAdapter`, so TypeScript catches a
+changed *shape* — a changed *route* needs a manual pass, done by hand.
+
+### The shipped-board sweep
+
+`e2e/tests/smoke/shipped-boards.spec.ts` opens every browser-only board in
+`boards/` and asserts that each service it declares renders a frame,
+with no uncaught exception. `web` profile only — it asks about board JSON, not
+about a host.
+
+The bug it exists for is **drift**: when a board names a `serviceId` the registry
+no longer has, `createService` logs an error and returns null, so the board still
+opens looking fine, minus a piece. Nobody notices, including a person opening it
+casually. Hence an assertion per declared uuid rather than "the page rendered".
+
+It deliberately does not claim those boards *work* — many want a camera, a key or
+a network — only that every part they are made of still exists. Boards with a
+`rest` runtime are excluded, since a sweep has no business starting an hkp-node.
+Known-broken boards are listed with a reason and marked `test.fail()` rather than
+skipped: a listed board is *expected* to fail, so fixing one turns the run red
+until its entry is removed. That is the only way a known failure ever gets
+cleaned up.
+
+### Two checks on the same anxiety
+
+Board drift is covered twice, at different depths, and both are worth keeping:
+
+| | `demo-boards.regression.test.tsx` (vitest) | `shipped-boards.spec.ts` (Playwright) |
+|---|---|---|
+| Where | jsdom, no browser | the real app in a real browser |
+| Asserts | the JSON is a valid descriptor, ids and uuids are unique, every browser `serviceId` resolves in the registry — nested ones too, as the board's blocks expand to them — and the board restores through `BoardProvider` | every declared service actually renders, and nothing threw |
+| Costs | seconds | about a minute |
+
+The first fails with the name of the service that went missing; the second
+catches what only appears once a board is really mounted.
+
+### Capability checks
+
+`e2e/tests/capabilities/` holds environment probes rather than product tests —
+things the real specs stand on, worth failing in isolation instead of inside a
+board. `webrtc.spec.ts` establishes a data channel between two browser contexts
+with no signalling server, and is why `CHROMIUM_ARGS` exists: without
+`--disable-features=WebRtcHideLocalIpsWithMdns`, Chrome hands out `.local`
+candidates that two isolated contexts cannot resolve for each other, and pairing
+never completes — silently.
+
+### The cloud specs
+
+`e2e/tests/cloud/` deploys boards for real: a playground, a runtime server and a
+coordinator. They need a third process, so they have a config of their own —
+the fast suite above starts nothing but the two dev servers, and ignores this
+directory.
+
+```bash
+cd e2e
+npm run test:cloud       # playwright.cloud.config.ts
+```
+
+That config starts one hkp-node on loopback as both runtime server and
+coordinator, with every directory it would write to pointed at nowhere, and
+runs the desktop shell against it. The shell is signed in by seeding the session
+it reads at boot, and knows the runtime server as a remote through the fake
+native host (`hostConfig.remotes`).
+
+What it covers is what no mock can: a board that names a remote is resolved,
+checked, introduced and registered; the runtime server connects to the
+coordinator, which is told no address; an attached browser is told when that
+server leaves and when it returns.
+
+Across runtime servers the same path is covered below the browser:
+`hkp-node/tests/coordinator-python.test.ts` starts hkp-python as its own process
+and runs one board over both — skipped where hkp-python has no virtualenv.
+`coordinator-rt.test.ts` does the same with the hkp-rt binary
+(`hkp-rt/build-tests/exe/hkp-rt`, which `hkp-rt/run-tests.sh` builds; skipped
+where it is absent), and also calls an endpoint mounted on it. Both pass bytes,
+bytes with JSON beside them and a ring buffer through the other server and
+compare what comes back.
+
+### People who sign in
+
+The cloud specs run hkp-node without authentication, so everybody is the one
+anonymous tenant and there is nobody to share a board with. Journeys that need
+two people use real verification instead: `e2e/support/jwks-server.mjs` makes a
+key pair per start and serves its public half, hkp-node is pointed at it with
+`HKP_TEST_JWKS_URI` (honoured only from a checkout and only on loopback), and
+`e2e/support/identities.ts` signs id tokens for whoever a spec names —
+signature, audience and verified email all checked as Auth0's are. A second
+person gets a context of their own through `prepareContext`
+(`support/test.ts`), held to the same network rules as the first.
+
+`e2e/playwright.film.config.ts` is the first user: the golden-path shoot
+(`npm run film`), which deploys the court booking board as one person, books on
+a phone as another and races them for the same hour. It is a filmed rehearsal
+rather than a suite — never part of `npm test` — and writes stills for the
+explainer video (`plans/TODO-GOLDEN-PATH-VIDEO.md`).
+
+### After a failure
+
+`trace: retain-on-failure` means the failing run was already recorded:
+`npx playwright show-trace <path>` replays it step by step with DOM snapshots,
+including for a run that failed elsewhere. There is no need to reproduce it
+first. `e2e/README.md` covers the ways of watching a run live.
+
+---
+
+## What CI runs
+
+`.github/workflows/run-all-tests.yml` checks out with `submodules: false` and
+runs **hkp-rt, hkp-frontend and readymade-mcp only** — the in-tree parts. The
+MCP suite's assertions about runtime source need the submodules it indexes and
+are skipped there. That is the repository
+split showing through: the submodules answer for themselves, and a superproject
+workflow that cloned them would be testing whatever commit they happened to be
+on. See [Repository](./repository.md).
+
+The end-to-end suite runs in the same workflow as two jobs:
+
+- **E2E Node cloud** — the cloud specs against the hkp-node the superproject
+  pins (its one submodule checkout), C++ left out;
+- **E2E browser** — the default suite on all three profiles, about nine
+  minutes.
+
+In CI a test that passes only on retry fails the run.
+
+The workflow runs when a change lands on main, and when someone starts it by
+hand (Actions → Run workflow, on any branch). Pushing to a working branch or a
+pull request runs nothing, so two things are worth knowing before merging:
+
+- **nothing in CI has checked a branch** unless someone started the workflow
+  on it — `run-all-tests.sh` locally is the check before a merge;
+- **hkp-node and hkp-python** are not covered by this workflow at all: their
+  suites run in their own repositories and in `run-all-tests.sh` locally.
+
+---
+
+## Where it lives
+
+| Concern | Where |
+|---|---|
+| Every suite in one run | `run-all-tests.sh` |
+| The C++ suites alone | `run-all-cpp-tests.sh` |
+| End-to-end suite, profiles, dev servers | `e2e/playwright.config.ts`, `e2e/README.md` |
+| Fake platform host | `e2e/support/fakeNativeHost.ts`, `e2e/support/test.ts` |
+| Board drift, without a browser | `hkp-frontend/src/runtime/browser/tests/demo-boards.regression.test.tsx` |
+| Board drift, in a browser | `e2e/tests/smoke/shipped-boards.spec.ts` |
+| Blocks on the running board: the lock, params, detach, editing, making one, wrapping picked services | `e2e/tests/blocks.spec.ts` |
+| Deploying to a real coordinator, in a browser | `e2e/playwright.cloud.config.ts`, `e2e/tests/cloud/deploy.spec.ts` |
+| Runtime sockets opened with a ticket, never the token, in a browser | `e2e/tests/cloud/ws-tickets.spec.ts` |
+| Signed-in people: test signing keys and id tokens | `e2e/support/jwks-server.mjs`, `e2e/support/identities.ts` |
+| Two people on one deployed board, filmed | `e2e/playwright.film.config.ts`, `e2e/film/` |
+| A board across hkp-node and hkp-python | `hkp-node/tests/coordinator-python.test.ts` |
+| A board across hkp-node and hkp-rt; endpoints mounted on hkp-rt | `hkp-node/tests/coordinator-rt.test.ts` |
+| What CI covers | `.github/workflows/run-all-tests.yml` |
+| Why CI covers only part of it | [Repository](./repository.md) |
+
+---
+
+See also: [Repository](./repository.md) for why the split between in-tree and
+submodule decides what CI covers.

package/bundle/docs/content/vocabulary.md

@@ -0,0 +1,171 @@
+# Vocabulary
+
+The words this project uses about itself, and what each one is in the code.
+
+---
+
+## What this is for
+
+Every project grows a private language. Somebody says "the board menu", "a
+mount", "the consent dialog" — and everyone in the room knows what is meant and
+nobody could point at the file. That gap costs an afternoon when a new person
+joins, and it costs an AI assistant far more: given a term it cannot resolve, it
+will search, guess, and edit something adjacent.
+
+So this is a lookup, not a tutorial. One line per term, saying what it is and
+where it lives. It is deliberately **finer-grained than the concepts**: a concept
+is an idea worth a page (`concepts/board.md`), while a term here can be a single
+dialog. Every concept appears below, so that entering by either door works.
+
+**It is written by people, not generated.** Which words matter, and which files
+are the ones worth naming, is a judgment no scan can make — a directory listing
+would be complete and useless. What is automated is the opposite half: checking,
+against a changeset, whether what an entry points at has moved. See *Keeping it
+true* at the end.
+
+A reference is a path, sometimes with the symbol that matters:
+`path/to/file.ts` or `path/to/file.ts#exportedName`. The first reference in a row
+is the one to open first.
+
+---
+
+## The interface
+
+Two bars are called a toolbar and two menus sit in one of them, so this section
+is the one worth being pedantic in.
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Toolbar** | The bar above an open board: board menu, board name, status, view controls, share, app menu. | `hkp-frontend/src/components/Toolbar/index.tsx` |
+| **TopBar** | The *start page's* bar — title, version badge, logo. A different bar in a different view; not the Toolbar. | `hkp-frontend/src/views/start/TopBar.tsx` |
+| **AppMenu** | The application-level dropdown in the toolbar: account, dashboard, settings, log out. About the app, not the board. | `hkp-frontend/src/ui-components/toolbar/AppMenu.tsx`, `hkp-frontend/src/ui-components/SettingsDialog.tsx` |
+| **BoardMenu** | The board-level dropdown beside it: save, load, and whatever else the host contributes through a `BoardMenuItemFactory`. About this board. | `hkp-frontend/src/ui-components/toolbar/BoardMenu.tsx`, `hkp-frontend/src/types.ts#BoardMenuItemFactory` |
+| **ShareMenu** | The third dropdown in the toolbar: the ways a board is handed to somebody else — a self-contained link, cloud access by email, a partner board QR. What distinguishes it from the BoardMenu beside it is direction: that one operates on the board you have open, this one gives it away. | `hkp-frontend/src/components/Toolbar/ShareMenu.tsx` |
+| **SaveBoardDialog** | Name and description on save, offering a suggested name. | `hkp-frontend/src/components/SaveBoardDialog.tsx` |
+| **Start page** | The Finder-style entry view: sources in columns, boards inside them, details on the right. | `hkp-frontend/src/views/start/StartPage.tsx`, `hkp-frontend/src/views/start/ColumnBrowser.tsx` |
+| **Source** | One column root on the start page — saved boards, demos, remotes, cloud boards. | `hkp-frontend/src/views/start/demosSource.ts`, `hkp-frontend/src/views/start/useCloudBoardsFolder.ts` |
+| **Service panel** | A service's own UI, or the generic panel when it has none. | `hkp-frontend/src/runtime/browser/UIRegistry.ts` |
+| **Board assistant** | Board Assist: a conversation beside the runtime canvas that reads the repository docs (or the `readymade-mcp` knowledge server), proposes changes to the whole board or one runtime, and applies a reviewed proposal — asking first when it would contact new addresses — with a revert to the previous configuration. → `concepts/board-assistant.md` | `hkp-frontend/src/assist/BoardAssistPanel.tsx`, `hkp-frontend/src/assist/scope.ts`, `hkp-frontend/src/assist/addresses.ts`, `hkp-frontend/src/assist/anthropic.ts`, `hkp-frontend/src/assist/mcpKnowledge.ts` |
+| **Nested navigation** | Drilling into a sub-pipeline as its own layered level, with breadcrumbs; levels stay mounted so panels keep running. | `hkp-frontend/src/runtime/ui/NestedNavigation.tsx` |
+| **Density** | The compact/comfortable axis, independent of the colour theme (`data-density`). | `hkp-frontend/src/ui-components/ThemeContext.tsx` |
+
+---
+
+## The board
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Board** | The top-level container: a named JSON document holding runtimes, their services and an optional facade. → `concepts/board.md` | `hkp-frontend/src/types.ts#BoardDescriptor`, `hkp-frontend/src/core/boardPersistence.ts` |
+| **Board context** | The live board while it is open — its runtimes, scopes, services, facade and linkage — and the actions that change them. Everything on screen reads from here. | `hkp-frontend/src/BoardContext.tsx` |
+| **Facade** | The app-like surface of widgets drawn over a board, so somebody can use it without seeing services. → `concepts/board.md` | `hkp-frontend/src/facade/types.ts`, `hkp-frontend/src/facade/FacadeRenderer.tsx` |
+| **Widget** | One control or display in a facade — a button, knob, level meter, data table — usually addressing a service by `serviceUuid`. | `hkp-frontend/src/facade/types.ts#LayoutItem`, `hkp-frontend/src/facade/panels/` |
+| **View mode** | Which half of a facade board is on screen: facade, split, or board. One three-state mode rather than two switches, so "at least one half is visible" is structural. | `hkp-frontend/src/facade/FacadeViewContext.tsx`, `hkp-frontend/src/facade/FacadeViewControls.tsx` |
+| **App mode** | The board being used rather than built: the facade has the whole window and the app's furniture steps back. Not a fourth view mode but a consequence of one — view mode `facade`, the facade editor closed, and a facade to show. The toolbar leaves the flow for a mark floating in the top right and returns *over* the facade rather than beside it, the copyright strip goes with it, and Escape works in both directions. Called app mode because the facade is all there is to see; the AppMenu's *app* is the application around the board, which is the part that retracts here. | `hkp-frontend/src/facade/FacadeChrome.tsx#useChromeRetracted`, `hkp-frontend/src/views/playground/PlaygroundInner.tsx` |
+| **Overview** | The full-window 3D-ish view of a whole board — every runtime, service and nesting level at once, with live activity. | `hkp-frontend/src/overview/OverviewView.tsx`, `hkp-frontend/src/overview/OverviewContext.tsx` |
+| **Board JSON** | The serialised form of a board. What is saved, shared by link, exported and deployed. | `hkp-frontend/src/core/boardPersistence.ts#serializeBoard` |
+| **Partner board** | The board for the other side of a peer connection, derived from the open one: the same board with its `peer-socket` roles swapped and its machine-local runtimes dropped, handed over as a link or a QR code. Derived one way only, so the share menu and a facade's `partner-board-qr` button hand out the same board. | `hkp-frontend/src/core/partnerBoard.ts#createPartnerBoard`, `hkp-frontend/src/components/Toolbar/ShareMenu.tsx` |
+| **Board action** | A facade widget action naming no service, because its subject is the board — what it does is the host's to decide, and a host that cannot do it leaves the button inert. | `hkp-frontend/src/facade/types.ts#BoardAction`, `hkp-frontend/src/facade/FacadeBoardActions.tsx` |
+
+---
+
+## Runtimes and services
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Runtime** | Where services run — a browser tab, a Node/Python/C++ process. Chained in board order. → `concepts/runtime.md` | `hkp-frontend/src/types.ts#RuntimeDescriptor`, `hkp-node/src/runtime.ts`, `hkp-python/src/hkp/runtime.py`, `hkp-rt/lib/src/runtime.cpp` |
+| **Service** | The unit of work: configure, process, optional panel, a place in an ordered list. → `concepts/service.md` | `hkp-frontend/src/types.ts#ServiceDescriptor`, `hkp-frontend/src/runtime/browser/services/` |
+| **Pipeline** | A runtime's ordered service list, which is the wiring — and the loop that walks it, one service at a time, stopping on `null`. Every runtime implements its own; these are the four. | `hkp-frontend/src/runtime/browser/BrowserRuntimeScope.ts#next`, `hkp-node/src/runtime.ts#processFromIndex`, `hkp-python/src/hkp/runtime.py#_process_from_index`, `hkp-rt/lib/src/runtime.cpp#processFrom` |
+| **Chain** | The step *between* runtimes: when one finishes, which one runs next and how its result gets there. Decided by whoever owns the board — the board view in the browser, the coordinator's session for a deployed board, which also has to reach a browser runtime over the bridge. | `hkp-frontend/src/views/playground/Board/index.tsx#onRuntimeResult`, `hkp-node/src/coordinator/session.ts#routeResult` |
+| **Sub-service / nested pipeline** | A service owning a pipeline of its own, run as one step of the outer one. | `hkp-node/src/services/sub-service.ts`, `hkp-rt/lib/src/sub_runtime.cpp` |
+| **Runtime API / scope / app** | The three seams: verbs per runtime *type*, one live runtime, and what a service may do. | `hkp-frontend/src/types.ts#RuntimeApi`, `#RuntimeScope`, `hkp-frontend/src/runtime/browser/BrowserRuntimeApp.ts` |
+| **Registry** | What services a runtime can create, sent back when it is provisioned. | `hkp-frontend/src/runtime/browser/BrowserRegistry.tsx`, `hkp-node/src/server.ts` |
+| **YAS** | The binary wire format for non-textual data over REST — 7-byte header, type-prefixed payload. | `hkp-frontend/src/runtime/rest/Message.ts`, `hkp-python/src/hkp/yas.py`, `hkp-node/src/yas.ts` |
+| **Remote** | A runtime server the host knows by name. A board may name one (`"remote": "Laptop"`) instead of giving a `url`; the client opening the board resolves it. `hkp://remotes/<name>` addresses the app's own embedded runtime. → `concepts/remotes.md` | `hkp-frontend/src/runtime/board/remote.ts#resolveRuntimeAddress`, `meander/backend/remoteRoute.h`, `meander/frontend/src/useBackendRemotes.ts` |
+| **Move (a runtime)** | Putting a runtime on another runtime server with its current state, as much of it as travels: each service's live state is carried, the runtime is built on the new server before it leaves the old one, and it keeps its id. What the old server keeps for the board — tables, records, files — stays there. "Move to …" in the runtime menu. → `concepts/remotes.md` | `hkp-frontend/src/core/runtimeOperations.ts#moveRuntime`, `hkp-frontend/src/ui-components/runtime-ui/MoveRuntimeDialog.tsx` |
+
+---
+
+## Composition
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Unit** | An ordinary board that also declares what it imports and exports, so another board can be made of it. → `concepts/units.md` | `hkp-frontend/src/runtime/board/units.ts#UnitDeclaration` |
+| **Composition** | An ordinary board that lists the units it is assembled from. | `hkp-frontend/src/runtime/board/units.ts#UnitEntry` |
+| **Projection** | Assembling composition and units into one board, qualifying exactly one thing: the runtime id. | `hkp-frontend/src/runtime/board/units.ts#projectUnits` |
+| **Linkage** | What linking produced, kept while the board is open: the units it was assembled from, the views they contribute, and where its blocks were expanded. | `hkp-frontend/src/runtime/board/units.ts#BoardLinkage` |
+| **Unit origin** | Where a `uri` is looked up — a sibling URL, a file beside the composition, the files opened together, saved boards. There is no registry. | `hkp-frontend/src/core/linkUnits.ts#UnitOrigin` |
+| **Unlink** | Splitting a running board back into the documents it came from, as a three-way merge rather than a copy. | `hkp-frontend/src/runtime/board/units.ts#unlinkProjection` |
+| **Topic** | The named channel units talk over, since they are never chained to each other. | `docs/content/services/queue.md`, `hkp-node/src/services/queue.ts` |
+| **Block** | A configured service — usually a sub-service and its pipeline — defined once in a board's `blocks` and used wherever a pipeline names it (`{ "block": "note", "params": {…} }`). Expanded on load, written back as the use on save; no runtime sees one. → `concepts/blocks.md` | `hkp-frontend/src/runtime/board/blocks.ts#BlockDefinition`, `hkp-frontend/src/core/linkBlocks.ts#linkBlocks` |
+
+---
+
+## Deployment and the cloud
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Coordinator** | The instance that owns a board and can see across all its runtimes. → `concepts/coordinator.md` | `hkp-frontend/src/core/coordinator.ts`, `hkp-node/src/coordinator/coordinator.ts` |
+| **Cloud board** | A board a coordinator owns and keeps running with nobody watching. → `concepts/cloud-boards.md` | `hkp-node/src/coordinator/session.ts`, `hkp-frontend/src/views/cloud/index.tsx` |
+| **Deploy** | Handing a board from the browser that built it to a coordinator. An introduction: the browser gets a ticket per remote runtime and tells each runtime server to connect with it; the board is registered only once they all have. | `hkp-frontend/src/core/deploy.ts#deployBoard` |
+| **Preflight** | What deploying a board would find, per runtime, asked before anything is deployed: where it resolves to and whether it can run there. | `hkp-frontend/src/core/deployPreflight.ts#preflightBoard`, `hkp-frontend/src/components/Toolbar/DeployDialog.tsx` |
+| **Ticket** | The credential a runtime server connects to a coordinator with — for one runtime of one board of one person. The server keeps it to reconnect; the coordinator keeps a hash. → `concepts/remotes.md` | `hkp-node/src/coordinator/participants.ts#ParticipantRegistry`, `hkp-node/src/coordinatorLinks.ts` |
+| **Participant** | Whatever runs one of a deployed board's runtimes and connected to its coordinator to do so. *Required* (a runtime server: its absence is an error that names it) or *transient* (a browser: its absence is normal). | `hkp-node/src/coordinator/participantProtocol.ts`, `hkp-node/src/coordinator/session.ts` |
+| **Bridge** | The WebSocket a browser attaches to a deployed board with — snapshots out, browser-runtime work in. | `hkp-node/src/coordinator/bridgeProtocol.ts`, `hkp-frontend/src/views/cloud/useCoordinatorBridge.ts` |
+| **Session token** | An opaque credential a runtime server mints for one of a user's runtimes, to outlive their session. The coordinator used to hold one per runtime; it now reaches runtimes over the connection a *ticket* opened. | `hkp-node/src/server.ts` |
+| **Fork** | Copying a deployed board back into something editable; the original keeps running. | `hkp-frontend/src/core/forkBoard.ts` |
+| **Mount** | An endpoint a runtime assigns to a service that must be reachable from outside. → `concepts/mounts.md` | `hkp-frontend/src/runtime/board/mount.ts`, `hkp-node/src/mounts.ts` |
+| **Mount reference** | `hkp-mount://<runtimeId>/<serviceUuid>` — what a person writes; `__hkpMount` is what machinery fills in. | `hkp-frontend/src/runtime/board/mount.ts#parseMountRef` |
+
+---
+
+## Logging
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Run** | One invocation of a board, followed across every service and runtime it reaches. → `concepts/logging.md` | `hkp-frontend/src/types.ts#ProcessContext`, `hkp-frontend/src/runtime/processContext.ts#startedRun` |
+| **Log entry** | One thing worth recording about a run, shaped the same on every runtime. | `hkp-frontend/src/types.ts#LogEntry`, `hkp-rt/lib/include/log_entry.h` |
+| **Log store** | Where a board's log lives: one JSONL file per board, kept by the coordinator because only it spans every runtime. | `hkp-node/src/coordinator/logStore.ts` |
+| **Log target** | Where a runtime hands its entries — the server registers one per runtime to carry them out. | `hkp-node/src/runtime.ts#registerLogTarget`, `hkp-python/src/hkp/server.py#_send_log` |
+
+---
+
+## Secrets
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Secret reference** | `{{secret.<alias>}}` — stays inline in service state and is resolved at the point of use, so a resolved value never comes back out of `getState`. | `hkp-frontend/src/core/secrets.ts` |
+| **Vault** | Where the values actually live, apart from every service's state and reachable only through `secrets()`. | `hkp-node/src/secrets.ts`, `meander/backend/vault.h` |
+| **Consent / audience** | Asking before a secret is sent, and to whom it may go; the answer is remembered as a grant. | `hkp-frontend/src/core/secretConsent.ts`, `meander/backend/grants.h` |
+| **SecretConsentDialog** | The dialog that does the asking in the desktop app. | `meander/frontend/src/SecretConsentDialog.tsx` |
+| **SecretsTab** | Managing secrets in Settings — add, rename, delete. Values are write-only. | `meander/frontend/src/SecretsTab.tsx` |
+| **SecretField** | The input a service panel uses for a credential, which shows a reference rather than a value. | `hkp-frontend/src/components/shared/SecretField.tsx` |
+
+---
+
+## The repository
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **Superproject** | The outer repository, holding what is built and released together — the frontend, the C++ runtime, the desktop app, these docs. → `repository.md` | `CMakeLists.txt`, `run-all-tests.sh` |
+| **Submodule** | One of the five directories with a history and a release of its own: hkp-node, hkp-python, hkp-website, meander-ios, meander-android. A change spanning one and the superproject is two commits. | `.gitmodules`, `scripts/vocabulary.mjs` |
+
+---
+
+## Keeping it true
+
+The risk is not that this is incomplete — it is meant to grow — but that an entry
+points somewhere that no longer exists. A wrong reference is worse than a missing
+one: it is confidently wrong, and whoever follows it edits the wrong file.
+
+The division of labour:
+
+- **A person decides what belongs here**, what each term means, and which files
+  are worth naming. Nothing adds entries automatically.
+- **The references are checked against a changeset.** `/vocabulary` (the command
+  in `.claude/commands/vocabulary.md`) takes the files a change touched, finds
+  every entry that names one of them, and reports which entries a reviewer
+  should look at — plus any reference that no longer resolves at all. It
+  proposes updated references; it does not invent terms.
+
+Run it on a change big enough to move things around, which is exactly when this
+document goes quietly stale.

package/bundle/hkp-frontend/src/runtime/browser/BrowserRegistry.tsx

@@ -0,0 +1,141 @@
+import { Bundles, ServiceClass, ServiceModule, User } from "../../types";
+import { loadBundle } from "../Bundles";
+import { defaultRegistry } from "./registry/Default";
+
+export const allowedServices = [
+  "hookup.to/service/timer",
+  "hookup.to/service/monitor",
+  "hookup.to/service/canvas",
+  "hookup.to/service/map",
+  "hookup.to/service/filter",
+  "hookup.to/shared/batcher",
+  "hookup.to/service/switch",
+  "hookup.to/service/camera",
+  "hookup.to/service/injector",
+  "hookup.to/service/trigger-pad",
+  "hookup.to/service/sound",
+  "hookup.to/service/audio-output",
+  "hookup.to/service/audio-input",
+  "hookup.to/service/audio-recorder",
+  "hookup.to/service/gif-encoder",
+  "hookup.to/service/input",
+  "hookup.to/service/output",
+  "hookup.to/service/thrower",
+  "hookup.to/service/receiver",
+  "hookup.to/service/downloader",
+  "hookup.to/service/mp3encoder",
+  "hookup.to/service/reduce",
+  "hookup.to/service/buffer",
+  "hookup.to/service/group-by",
+  "hookup.to/service/match-filter",
+  "hookup.to/service/chart",
+  "hookup.to/service/spotify",
+  "hookup.to/service/github-source",
+  "hookup.to/service/github-sink",
+  "hookup.to/service/cache",
+  "hookup.to/service/key-handler",
+  "hookup.to/service/reactor",
+  "hookup.to/service/html",
+  "hookup.to/service/array-transform",
+  "hookup.to/service/xy-pad",
+  "hookup.to/service/encrypt",
+  "hookup.to/service/decrypt",
+  "hookup.to/service/hash",
+  "hookup.to/service/sign",
+  "hookup.to/service/linear-regression",
+  "hookup.to/service/xlsl",
+  "hookup.to/service/select",
+  "hookup.to/service/hacker/considered",
+  "hookup.to/service/fetcher",
+  "hookup.to/service/cloud-source",
+  "hookup.to/service/cloud-sink",
+  "hookup.to/service/board-service",
+  "tracks",
+  "hookup.to/service/peer-socket",
+  "hookup.to/service/ollama-prompt",
+  "hookup.to/service/speech-synth",
+  "hookup.to/service/fft",
+  "sub-service",
+  "hookup.to/service/lz-compress",
+  "hookup.to/service/stopper",
+  "hookup.to/service/sort",
+  "hookup.to/service/limit",
+  "hookup.to/service/flat-map",
+  "hookup.to/service/smooth",
+  "hookup.to/service/set-runtime-variable",
+  "hookup.to/service/if",
+  "hookup.to/service/feedback",
+];
+
+export default class BrowserRegistry {
+  availableServices: Array<ServiceModule> = [...defaultRegistry];
+
+  static async create(
+    bundles?: Bundles,
+    user?: User,
+  ): Promise<BrowserRegistry> {
+    const registry = new BrowserRegistry();
+    registry.availableServices = [...defaultRegistry];
+    if (bundles && bundles.length) {
+      await registry.loadBundles(bundles);
+    }
+    if (user) {
+      await registry.loadUserBundles(user);
+    }
+    return registry;
+  }
+
+  getServiceClasses(): Array<ServiceClass> {
+    return this.availableServices.map(({ serviceId, serviceName }) => ({
+      serviceId,
+      serviceName,
+    }));
+  }
+
+  findServiceModule(serviceId: string): ServiceModule | undefined {
+    return this.availableServices.find((elem) => elem.serviceId === serviceId);
+  }
+
+  loadUserBundles = async (user: User) => {
+    if (user && user.features && user.features.registry) {
+      const userBundles: Array<string> = JSON.parse(user.features.registry);
+      await this.loadBundles(userBundles);
+    }
+  };
+
+  async loadBundles(bundles: Bundles): Promise<BrowserRegistry> {
+    if (bundles) {
+      for (const bundleId of bundles) {
+        const bdl = await loadBundle(bundleId);
+        this.__appendBundleServices(bdl);
+      }
+    }
+    return this;
+  }
+
+  allowedServices() {
+    const allowAllServices = true;
+    return this.availableServices.filter(
+      (s) => allowAllServices || allowedServices.indexOf(s.serviceId) !== -1,
+    );
+  }
+
+  allServices() {
+    return this.availableServices;
+  }
+
+  __appendBundleServices = (arr: Array<ServiceModule>) => {
+    arr.forEach((x) => {
+      const exists =
+        this.availableServices &&
+        this.availableServices.find((s) => x && x.serviceId === s.serviceId);
+      if (!exists) {
+        if (this.availableServices) {
+          this.availableServices.push(x);
+        } else {
+          this.availableServices = [x];
+        }
+      }
+    });
+  };
+}