@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/concepts/board-assistant.md

@@ -0,0 +1,307 @@
+# Board assistant
+
+Build and change a board through a conversation beside the runtime canvas.
+Open it with the sparkle button beside zoom, at the top right of the playground
+toolbar:
+
+![The playground toolbar with the Board Assist sparkle button highlighted, left of the zoom button](/images/docs/board-assist-button@2x.png)
+
+Close it with the same button or the panel's close button. The conversation
+stays available while the panel is hidden; it is not saved in the board file.
+
+## Setup
+
+Open **Settings → Board Assist**, in either the website or the native Readymade
+app. Choose **Anthropic**, **OpenAI compatible**, **OpenCode server** or
+**OpenCode Go**; only the chosen provider's
+settings are shown. As in Appearance, changes take effect as you make them — a
+choice at once, a text field when you leave it — and an invalid value is
+explained under its field instead of being saved. Each saved token can be
+removed with the × beside its section. The assistant panel also has a **Provider** selector. Switching providers
+or API servers clears the conversation so a previous provider's history is not
+sent to a different server. The board is kept; the conversation's revert
+checkpoint goes with it.
+
+For Anthropic, enter an API token. For OpenAI-compatible servers, enter an **API
+base URL** including `/v1`, and an optional API token. An unauthenticated local
+llama.cpp server does not need a token. For example:
+
+- Provider: **OpenAI compatible**
+- API base URL: `http://127.0.0.1:8081/v1`
+- API token: empty unless the server was launched with authentication
+- Server context size: **8192** when using `llama-server -c 8192`
+
+Then select **OpenAI compatible** in the panel. It queries `/v1/models`
+and lists the returned model IDs, such as `Bonsai-27B-Q1_0.gguf`. **Refresh models**
+repeats that query. Requests use `/v1/chat/completions` with JSON output mode;
+the model and its chat template must support following instructions and producing
+JSON. Responses are streamed so slow generation can show progress without
+waiting for the entire response. A server that ignores streaming is accepted
+with a normal JSON response. Hosted endpoints work with the same fields. Browser clients need the server
+to allow their origin through CORS. An address using plain `http://` to anything
+but this machine is accepted with a warning, in Settings and in the panel: the
+token, prompts and board cross the network unencrypted. The MCP server URL is
+warned about the same way.
+
+For llama.cpp, **Thinking mode** can be **Server default**, **Off**, or **On**.
+The assistant panel's **Effort** selector offers **Server default**, **Thinking off**,
+and **Thinking on** for OpenAI-compatible servers. It shares the saved thinking
+setting with Settings, so it can be changed directly before the next request.
+Off sends `chat_template_kwargs: { enable_thinking: false }`; On sends true.
+Leave Server default for endpoints without llama.cpp's template options. This
+controls thinking in the template and is separate from the context-size setting.
+Thinking can use the output budget before the final board appears.
+
+**OpenCode Go** uses the models of an OpenCode Go subscription through the same
+OpenAI-compatible API, with Board Assist itself as the client — no OpenCode
+server is involved. Enter the subscription's **API key** (from
+`opencode.ai/auth`); the **API base URL** starts as Go's own,
+`https://opencode.ai/zen/go/v1`. The model list shows only the models Go serves
+through chat completions, and each turn is sized by the selected model's
+context window, so there is no context setting. Each conversation is named to Go
+by a session id in the `X-Opencode-Session` header, which Go asks of every
+client; a new conversation gets a new one.
+
+Go lists its models to any page, but does not yet answer the browser's CORS
+check for generating, so a page reaches it through a relay: a small server that
+adds CORS headers for the pages using it, forwards `models` and
+`chat/completions` to `https://opencode.ai/zen/go/v1`, and passes on the
+`Authorization` and `X-Opencode-Session` headers. Its address goes in the API
+base URL, with the gateway's path, such as
+`https://example.com/opencode.php/go/v1`. The key travels through the relay to
+Go. A relay meant for only some people can ask for a key of its own: the
+**Relay key**, sent as `X-Relay-Key` when it is set, and never to Go directly.
+
+A connection failure during generation can mean a timeout or disconnect, even
+when the server is still working. It does not establish a CORS problem. The
+panel distinguishes initial connection errors from interrupted response streams;
+**Stop** cancels the request and an incomplete stream is never offered as a board.
+
+The compatible provider retrieves relevant repository pages before generating,
+using a conservative budget for the configured context size. It preserves the
+full current board and rejects a request that cannot fit rather than truncating
+its configuration. Older conversation may be omitted to fit the latest board.
+Larger boards may require increasing both the server's context size and this
+setting. This does not change the server's context limit itself.
+
+Anthropic uses its official browser-capable TypeScript SDK and Models API,
+following all model-list pages. Effort offers the levels the selected Anthropic
+model reports it supports; **Model default** omits effort. Compatible servers use
+their model default, since the standard model-list API does not report supported
+effort levels. The provider, model, effort and server settings are saved on this
+device. **API settings** replaces **Send** if the active provider lacks its required
+settings; local servers can send with no API token.
+
+Where tokens are kept depends on the host. The desktop and phone apps keep them
+with their other secrets (`targets.md`, "Where secrets live"), as
+`readymade.assist.anthropic`, `readymade.assist.openai-compatible`,
+`readymade.assist.opencode`, `readymade.assist.opencode-go` and
+`readymade.assist.opencode-go-relay`, so they
+are listed, and can be removed, in **Settings → Secrets** like any other
+credential. Each is allowed only to its provider's host — `api.anthropic.com`,
+or the host of the API base URL, which it follows when the URL changes — so a
+board that names one as `{{secret.readymade.assist.anthropic}}` can use it for
+its own calls to that provider and nowhere else. A token an older build kept in
+local storage moves there on the first launch. The website has no secret store
+and keeps tokens in the browser's local storage. Either way they stay outside
+board files and share links. The other settings stay in local storage on every
+host. Requests go directly to the selected provider or API server; hosted API
+usage is billed to that account.
+
+## On a phone
+
+On iOS and Android, Board Assist is a page of its own, opened with the sparkle
+button in a board's top bar. Leaving it with Back keeps the conversation, as
+hiding the desktop panel does. The provider's settings are a section of
+**Settings**, after Appearance, and the page leads there when no provider is set
+up; the model, effort and **Include asset contents** are in a sheet opened from
+the model line at the top.
+
+A phone has no selection. What it has instead is what the person opened last:
+tapping a service, inspecting its flow, adding a service to a runtime, running a
+runtime with parameters or making a block of services makes that runtime, and
+those services, what **Context** narrows to. The choice above the conversation
+names it ("Browser · Timer"), beside **Whole board**. The open nested pipeline
+is likewise the one last drilled into in a service's sheet: the sub-services
+passed through on the way, and the one shown if it holds a pipeline of its own,
+sent as the levels the desktop's breadcrumb would show.
+
+**Review changes** opens the proposal as a page: what it does in a sentence per
+change — runtimes and services added, removed, changed or reordered, the facade,
+blocks or assets changed — and then the board document's lines that differ,
+with the unchanged ones folded. It is read-only; ask for another proposal to
+change it. **Apply changes** applies it exactly as **Apply board** does, with
+the same checks, connection confirmation and revert
+(`hkp-frontend/src/views/assist/`, `hkp-frontend/src/assist/proposalDiff.ts`).
+Both layouts share one model of the conversation
+(`hkp-frontend/src/assist/useBoardAssist.ts`).
+
+## Building and editing
+
+Describe what the board should do. For example:
+
+> Create a board that runs every minute, captures an image using the browser
+> Camera service, detects faces, and sends a notification to ntfy topic xxx
+> when there are faces.
+
+The assistant can search and read the documentation in `docs/content/` and the
+JSON examples in `boards/`. Both are packaged into builds, so the documentation
+matches that build and requires no documentation server. It reads the relevant
+service contracts, configuration and data shapes before proposing a board.
+
+The repository also contains an optional read-only MCP knowledge server in
+`readymade-mcp/`. It indexes the same documentation plus example boards and
+allowlisted runtime source from a pinned checkout. Its tools can search, read
+contracts, find compatible services and examples, inspect bounded source
+excerpts, and statically validate a board. Each result carries build and commit
+provenance.
+
+To use it with Board Assist, run the server and set **Settings → Board Assist →
+Knowledge server → MCP server URL**, for example
+`http://127.0.0.1:8787/mcp`. The URL is device-local configuration and is not
+written into boards. A hosted playground needs the server behind a TLS reverse
+proxy; `readymade-mcp/README.md` walks through deploying it. Both providers can consume the server's search and
+document-reading tools. Anthropic also receives the allowlisted contract,
+compatibility, example, source-inspection and board-validation operations as
+model-controlled tools. OpenAI-compatible providers retain bounded
+pre-retrieval until their tool-calling support can be detected reliably.
+
+The MCP connection has bounded connect and tool-call timeouts. What happens when
+a call fails depends on what the failure says about the server:
+
+- **The server refused this call** — a tool result marked as an error, or a
+  JSON-RPC error: invalid arguments, an unknown path or service. The server is
+  reachable, so only that call is answered from the bundled documentation (or
+  its error goes back to the model), and the rest of the turn keeps using MCP.
+- **The server cannot serve the turn** — a network or CORS failure, an HTTP
+  error, a timeout, a closed connection, missing required tools, or replies in
+  a shape Board Assist does not understand. The rest of the turn uses the
+  bundled documentation and the panel shows a fallback notice. It is not retried
+  within the turn: seconds later it is unlikely to have recovered.
+
+The next turn tries the server again, which costs nothing when it refuses
+connections. A server that failed **slowly** — a timeout, or any failure that
+took two seconds or more — is skipped by later turns for a minute instead, so a
+hanging server does not delay every request before the offline path is used.
+Cancellation still stops the request. Leaving the MCP URL empty keeps the fully
+offline path and does not load the MCP client.
+
+The MCP server receives knowledge search terms, requested document paths and
+arguments to richer operations. Those arguments can include the current or
+proposed board when the model calls `validate_board`. Provider API tokens are
+not sent to MCP. Treat a configured MCP endpoint as a trusted recipient of this
+context even though retrieved content is still treated as untrusted model data.
+
+The local server accepts browser origins on loopback by default. When Board
+Assist is served from a named host, explicitly allow that hostname when starting
+the server, for example `--allowed-origin readymadeit.com`. A non-loopback MCP
+deployment additionally needs strict Host and Origin allowlists and
+authentication before it should be exposed publicly.
+
+Every request is built from the board as it is at that moment, with the
+available runtime engines and service catalog, the selected services and the
+open nested pipeline. **Context** decides how much of the board goes with it and
+what the assistant may change:
+
+- **Only runtime …** — when a runtime is selected. The assistant receives that
+  runtime and its services in full, and the rest of the board only as an
+  outline: runtimes in order with their services' ids and names, no state, and
+  which services the facade uses. It proposes that runtime alone, which is
+  merged into the current board; nothing outside it can change, whatever the
+  model writes. A request that needs other runtimes, the facade, assets or
+  blocks is answered by asking to switch to the whole board. Blocks, assets and
+  imported units the runtime refers to are included as context. A runtime
+  contributed by an imported unit cannot be edited through the board, so
+  selecting one uses the whole board.
+- **Whole board** — the complete board and imported unit documents; the
+  proposal is a complete board.
+
+Select a service before asking to change "this service". Ambiguous requests can
+receive a clarification instead of a change. Imported unit documents cannot be
+edited through their containing board here.
+
+**Include asset contents** is off by default: assets are sent as their id and
+media type only, and a proposal that keeps an asset gets its contents back from
+the current board. Turn it on to let the assistant read or rewrite an asset's
+text — a page, a script. The choice is saved on this device.
+
+Your prompts, the board context above, conversation history and the
+documentation retrieved by the assistant are sent to the selected provider or
+API server; the line under the prompt says what the next request carries and
+where it goes. Service state can include credentials entered directly; use
+secret references where possible — a `{{secret.…}}` reference is sent, never
+its value. Credentials from **Board Assist** settings are used for
+authentication and are not added to the model's conversation.
+
+## Review, apply and revert
+
+The assistant explains its proposal and offers **Show changes** beside
+**Apply board**. Preview opens a Monaco JSON diff: the current board
+on the left and the proposal on the right, with removed lines in red and added
+lines in green. Narrow windows use an inline diff. The current board is read
+afresh when opening the preview; viewing it does not apply the proposal. The current side is read-only; the
+proposed side can be edited. **Apply edited board** validates and applies your
+JSON, including manual changes, and supports the same revert action. Invalid
+JSON or a board-load error keeps the editor open with your draft intact.
+**Cancel** discards the draft. Applying from the diff checks for configuration
+changes since the diff was opened, so the current side you reviewed is the
+configuration being replaced. A proposal does not change the running board. It first passes
+structural validation and the normal board linker checks its blocks and
+references without loading runtimes. A failed preflight leaves the proposal and
+diff available, but disables direct application; edit it in the diff to repair
+and revalidate it. Service-specific behavior still needs testing with the actual
+devices and runtime servers.
+
+**Apply board** loads the proposed configuration through BoardContext. This
+rebuilds the runtimes and can start services, connect to remote servers, or request
+camera and microphone permissions. Timer ticks and JSON object key ordering do not count as edits for this check.
+If the board configuration changed after the request,
+applying is refused: ask for a new proposal using the current board.
+
+A proposal that would make the board contact an address it does not use yet is
+not applied until you say so — from the message or from the diff. The
+assistant read board content, documentation and knowledge-server results
+nobody on your side wrote, so an address in its output is not trusted just
+because you asked for a change. Board Assist lists the new origins: runtime
+servers, which run part of the board and receive your Readymade sign-in, and
+any other address in service state, assets or the facade, which services may
+connect and send board data to. An origin counts as known when it appears
+anywhere in the current board or its imported units. Vault secrets are asked
+about separately, per server, when a runtime first needs them.
+
+Runtimes that **name** their server never need this confirmation, because a
+name resolves only to a server you keep (`"remote": "node"`, `"remote":
+"embedded"`; see [Remotes](./remotes.md)). Board Assist leans on that:
+
+- The assistant is shown your runtime servers by name only — their addresses
+  are not sent to the provider — and is told to use `remote`, never `url`.
+- When a proposal still gives a runtime the address of a server you keep, that
+  address is replaced by the server's name, the same name the runtime picker
+  would write, and the message says so. A runtime keeping the `url` it already
+  has is left alone; ask for the change if you want it named.
+- A name you keep nothing under is asked about when the board loads: you say
+  which server it means. The address comes from you, not from the model.
+
+Addresses in service state are not covered by names and are still confirmed.
+
+Service panels and facade panels have independent render boundaries, so one
+broken panel reports its error in place instead of taking down the playground.
+Board Assist watches those boundaries while applying. A load or render failure
+automatically reloads the checkpoint from before the attempt and keeps the
+proposal available for inspection or editing. This is transactional failure
+containment, not a security sandbox: services may begin initialization during
+the attempted load, so external effects that already occurred cannot be undone.
+
+**Revert** replaces **Apply board** in the proposal after a successful
+application. It restores the complete configuration from immediately
+before the last assistant application, including its assets, blocks and facade.
+If automatic restoration itself fails, the manual revert remains available.
+Revert replaces the current configuration. When the board has changed since the
+proposal was applied, it asks first, because those later edits would be
+discarded. It does not undo notifications, HTTP requests or other effects
+services have already produced. There is one previous configuration, kept for
+the conversation.
+
+**Stop** cancels the current API request. **New conversation** clears the chat
+and its revert checkpoint without changing the board. Conversation and revert history are not persisted
+across leaving the playground or reloading the app.

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

@@ -0,0 +1,265 @@
+# Board
+
+The top-level unit: a named, self-contained description of an app — its runtimes, the services inside them, and optionally the facade that presents it.
+
+---
+
+## What a board is
+
+Everything lives on a board. It is the unit a person thinks in ("my doorbell
+board", "the booking board"), the unit that gets saved, shared, forked and
+deployed, and the unit a coordinator owns.
+
+Structurally it is one JSON document, `BoardDescriptor` in
+`hkp-frontend/src/types.ts`:
+
+```ts
+type BoardDescriptor = {
+  runtimes: Array<RuntimeDescriptor>;
+  services: { [runtimeId: string]: Array<ServiceDescriptor> };
+  registry?: ServiceRegistryMap;
+  boardName?: string;
+  description?: string;
+  facade?: FacadeDescriptor;
+};
+```
+
+That is the whole model. There is no wire list, no graph, no separate flow
+definition: **order is the wiring**. Runtimes run in array order, and the
+services inside each runtime run in the order they are listed.
+
+```json
+{
+  "boardName": "My Board",
+  "runtimes": [
+    { "id": "ui",   "name": "Browser", "type": "browser", "state": {} },
+    { "id": "node", "name": "Node", "type": "rest", "remote": "node", "state": {} }
+  ],
+  "services": {
+    "ui":   [ { "uuid": "tick", "serviceId": "hookup.to/service/timer", "serviceName": "Timer", "state": {} } ],
+    "node": [ { "uuid": "log",  "serviceId": "monitor", "serviceName": "Monitor" } ]
+  }
+}
+```
+
+---
+
+## Ids, and why they matter
+
+`runtimes[].id` and each service's `uuid` are not decoration. They are how
+everything in and around a board refers to a part of it: which runtime a
+service list belongs to, which service a facade widget drives, which service a
+mount reference names.
+
+- **A board loaded from JSON keeps the ids the file carries.** That is what
+  makes them stable across reloads — a runtime server can recognise the runtime
+  it already has and attach rather than rebuild.
+- **Ids are unique per user, not globally.** hkp-node namespaces runtimes by the
+  authenticated `sub`, so boards can ship readable ids like `node` or
+  `chat-node` without two people colliding on one server. A deployed board's
+  runtimes are further kept per board, so two of one person's boards may share
+  an id too (`concepts/cloud-boards.md`).
+- **Copying a board must rename all of them.** Otherwise the copy provisions
+  over the original's runtimes — an editor whose changes land somewhere else.
+  `hkp-frontend/src/core/forkBoard.ts` does the renaming, driven by *field name*
+  rather than by value, because an id like `node` is an ordinary string that can
+  appear anywhere in a document. `KNOWN_REFERENCE_FIELDS` is where a new
+  id-carrying field gets registered.
+
+---
+
+## Order is the default, not the only shape
+
+Everything above describes a line: runtimes in array order, services in list
+order, each result becoming the next input. That is the shape a board should
+have, and almost every board can have it.
+
+It is not a cage, though. A board can also **jump**: a service can name another
+service by id and reconfigure it, or hand it data to process; a service can call
+a whole runtime by name. Those are real capabilities with real uses — a feedback
+loop, a state machine, a control panel that reconfigures something elsewhere —
+and `concepts/runtime.md` lists the mechanisms.
+
+**Treat them the way you treat `goto`.** They are not forbidden, they are
+expensive:
+
+- A jump makes two parts of the board know about each other. Neither can be
+  moved, renamed or reused without the other, and reading either one no longer
+  tells you what happens.
+- A named id is a reference generic machinery has to know about. Every one of
+  them is a field in `KNOWN_REFERENCE_FIELDS` (`core/forkBoard.ts`) —
+  `targetServiceUuid`, `targetRuntime`, `serviceUuid` — because a fork has to
+  rewrite them or the copy reaches into the original. A service that invents its
+  own way to name another one is simply not carried across.
+- The flow stops being visible. The list no longer says what runs, and nothing
+  else does either.
+
+**The alternative is nesting, and it is almost always available.** A pipeline
+inside a service is a step of the outer pipeline: the host knows its nested
+pipeline, and the nested pipeline knows nothing about its host. That ignorance is
+the point — it is what makes the group movable, reusable and readable on its own.
+
+The clearest example is the `join` service (hkp-node): it runs a nested pipeline
+as a **detour** and merges the result *beside* the input rather than replacing it.
+Two services that would otherwise have to know each other's ids — one producing
+a value, one filing it against the record it belongs to — become one grouped step
+that takes a value in and hands a bigger value out. Same for `sub-service` (a
+pipeline as a step), `switch` (pipelines as branches), `looper` (a pipeline
+repeated) and `board-service` (a whole saved board as a step).
+
+The question to ask when reaching for a jump is: *what value am I actually trying
+to get from over there?* Usually there is a grouping that produces that value
+where it is needed, and then nothing has to reach anywhere.
+
+---
+
+## What a board deliberately does not contain
+
+| Not in the board | Where it lives instead | Why |
+|---|---|---|
+| Secret values | the host's secret store, referenced as `{{secret.alias}}` | a board is meant to be shared, downloaded, handed to a model — there is nothing to redact because it never held the value (`core/secrets.ts`) |
+| Mount addresses | published by the owning service at load, referenced as `hkp-mount://…` | the address is assigned when the board loads, so no file can know it (see `concepts/mounts.md`) |
+| Where a runtime server listens | the remotes each client keeps, referenced by name as `"remote": "node"` | an address is only true from where it is dialled; the name opens on each person's own server (see `concepts/remotes.md`) |
+| Host-specific URLs | substituted from `HKP_RUNTIME_HOST`, `HKP_RUNTIME_URL`, `HKP_WEBAPP_URL` at load | the same board opens on a laptop and a phone (`hkp-frontend/src/templateVars.ts`) |
+| Live service output | nowhere — it is a notification, not state | a Monitor's messages are its output; `getState()` reports configuration |
+
+The rule behind all five: **a board records intent, not the circumstances of one
+run.** Anything only true of one machine on one day is resolved on load, not
+written down.
+
+---
+
+## Loading a board
+
+A board is **linked** first: if it lists `units`, those documents are resolved
+and projected into it, and what runs is the projection. A board that lists none
+is its own projection, so nothing else here has a special case for it. See
+**Units and compositions** (`concepts/units.md`).
+
+Then `restoreBoard()` in `hkp-frontend/src/core/boardPersistence.ts`:
+
+1. If any runtime needs authentication, wait for the user session to settle —
+   remote runtimes authenticate every call with the user's id token, and
+   provisioning without one gets a 401.
+2. Restore **every runtime concurrently** (`Promise.all`), each through the
+   `RuntimeApi` for its type.
+3. Services are restored with their secret references intact. Nothing is
+   substituted into service state: a resolved value in state is a value that
+   comes back out of `getState()` and into the next saved board.
+
+That concurrency is worth remembering, because it is the reason so much in HKP
+is *lazy*: when one runtime comes up, the runtimes it points at may not exist
+yet. "Not resolved yet" is a normal state, not an error.
+
+## Saving a board
+
+`serializeBoard()` in the same file asks **each service for its live state**
+(`getServiceConfig`) rather than writing down what the board was loaded with.
+A service reports what it was configured with, so a board round-trips — and this
+is also why anything the machinery pushes into a service's state ends up in the
+saved file.
+
+A board assembled from units is written back as the documents it was assembled
+from, never as the one board it is running as; `serializeBoard` is the flat
+output that deploying, sharing and exporting want.
+
+---
+
+## What you can do with a board
+
+| Action | What happens | Where |
+|---|---|---|
+| **Save / load** | one JSON document per board, kept by the host — files on desktop, `localStorage` on the web | `backend.saveBoard` / `loadBoard` (`meander/frontend/src/backend/types.ts`) |
+| **Import / edit source** | paste a board JSON in *Edit Board Source*; hosts that support it keep the unparsed text too | `loadBoardSource` / `saveBoardSource` |
+| **Share as a link** | the board is compressed into a URL that opens it in the playground | `views/playground/BoardLink.tsx` |
+| **Share as a QR / partner board** | a *subset* of the board travels — the runtimes the receiver can reach — with mount references and template variables baked into concrete values first | `ui-components/runtime-ui/RuntimeHeader.tsx`, `facade/FacadeRenderer.tsx` |
+| **Fork** | a copy with every id regenerated, so it is a board of its own | `core/forkBoard.ts` |
+| **Deploy** | hand it to a coordinator that provisions its runtimes and keeps them running | `core/deploy.ts`, see `concepts/cloud-boards.md` |
+| **History** | hosts may snapshot the board on every structural change | `onBoardInfrastructureChange` → `pushBoardSnapshot` |
+
+Note what the export cases have in common: **references are resolved on the way
+out.** A reference is meaningful only inside the board that also holds the thing
+it names, so a board leaving for another device gets concrete values instead.
+
+---
+
+## The facade
+
+A board can carry a `facade`: a JSON description of a polished, app-like surface
+of controls and displays laid over the services. Developers build the internals;
+the facade makes the result usable by someone who neither knows nor cares what a
+service is.
+
+Widgets reference services by `serviceUuid` — another id-carrying field, which
+is why forking rewrites it. Types live in `hkp-frontend/src/facade/types.ts`;
+the full widget catalogue is in `CLAUDE.md` and the `/new-board` skill.
+
+Beside its panels a facade declares two things about what is on screen and when.
+**Tabs** group the panels into faces shown one at a time, because a board's
+controls rarely all belong to the same person or the same moment — a feed is
+subscribed to once and read every day. They are a view over the panels the
+facade already has: a tab names panel ids, a panel no tab names stays on screen
+above the bar, and `defaultTab` — which is not remembered between visits — is
+what everybody gets. A panel can also be another's **detail** (`detailOf`) — a
+story's discussion beside the list of stories. Where they fit side by side they
+are; on a phone the detail opens in place of its master, from a `show-panel`
+action, with a way back to the list as it was left. **Notices** are what a board says without being looked at: a
+toast raised from what a service reports, instead of a row kept free for a
+problem that is usually not there.
+
+A facade can say **who it is being shown to**: `{ "$user": "name" }` or
+`{ "$user": "email" }`, usable wherever a `{ "$state": … }` reference is — in a
+payload, or as a `text` widget's `value`. On a deployed board `name` is what
+that board's member list calls the person; elsewhere it is the account's own.
+It is for *showing* somebody who they are acting as. A service that has to
+know who is calling asks the run, which the server states — see
+[SQL: who is calling](../services/sql.md#who-is-calling). Nothing a facade puts
+in a payload proves it.
+
+And it can keep a part of itself **for the board's owner**: a widget, a
+container, a panel, a tab or a notice carrying `"visibleTo": "owner"`. On a
+deployed, shared board the coordinator leaves it out of the facade a member is
+sent, so a member is not shown it, cannot act through it, and is not sent what
+it reads; anywhere else whoever has the board open is its owner and sees it
+all ([Cloud boards](./cloud-boards.md#sharing-a-board-members)).
+
+---
+
+## Who owns a board
+
+Exactly one instance, always — and which one changes what the browser may do:
+
+| Board runs as | Owner | Browser's role |
+|---|---|---|
+| Playground / Readymade | this browser | owns it: provisions runtimes, holds engine state |
+| Deployed | a coordinator | viewer: reads, configures, cannot edit structure |
+| Deployed, shared with you | a coordinator, for its owner | member: sees the facade and what it reads, does what the facade does, and is shown nothing else of the board |
+
+The role that owns the board is the **coordinator**
+(`concepts/coordinator.md`), and moving between the two rows is
+**deploying** (`concepts/cloud-boards.md`).
+
+---
+
+## Rough index into the source
+
+| Concern | Where |
+|---|---|
+| The type | `hkp-frontend/src/types.ts` (`BoardDescriptor`, `isBoardDescriptor`) |
+| The live board (engine state, actions) | `hkp-frontend/src/BoardContext.tsx` |
+| Load / save | `hkp-frontend/src/core/boardPersistence.ts` (`restoreBoard`, `serializeBoard`) |
+| Copying a board | `hkp-frontend/src/core/forkBoard.ts` |
+| Deploying | `hkp-frontend/src/core/deploy.ts` |
+| Secret references | `hkp-frontend/src/core/secrets.ts` |
+| Host template variables | `hkp-frontend/src/templateVars.ts` |
+| Facade | `hkp-frontend/src/facade/` |
+| Host storage | `meander/frontend/src/backend/types.ts` (`BackendAdapter`) |
+| Example boards | `boards/*.json` |
+
+---
+
+See also: **Runtime** (`concepts/runtime.md`), **Service**
+(`concepts/service.md`), **Mounts** (`concepts/mounts.md`), **Coordinator**
+(`concepts/coordinator.md`), **Cloud boards** (`concepts/cloud-boards.md`),
+**Units and compositions** (`concepts/units.md`), **Logging**
+(`concepts/logging.md`).