@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/boards/rss-radio-board.md

@@ -0,0 +1,221 @@
+# Reading Radio
+
+A reading list, read aloud and served as audio. Five units — a reader, an
+editor, a voice, a radio and a library — each of which runs and can be tested on
+its own, held together by nothing thicker than two feed URLs and two
+[mount references](../concepts/mounts.md).
+
+## What it does
+
+It turns anything that publishes RSS or Atom into a podcast. Articles are
+collected into a reading list, the list is published as a feed of its own, an
+editor reads each article and writes a short brief of it, a voice reads the
+title and the brief of anything not yet spoken, and the resulting audio is
+served at an address you can point a player at.
+
+## The five units
+
+It is a [composition](../concepts/units.md) of five units, and declares one
+runtime of its own — the desk the lanes below read:
+
+| As | Unit | What it is |
+|---|---|---|
+| `reader` | `rss-demo-board.json` | Feeds in, a reading list out, published as a feed |
+| `editor` | [Radio Editor](./rss-radio-board.md#editor) | A feed in, the same feed out with a brief of each article |
+| `voice` | [Radio Voice](./rss-radio-board.md#voice) | A text-to-speech endpoint, and nothing else |
+| `radio` | [Radio](./rss-radio-board.md#radio) | Reads a feed, skips what it has spoken, calls the voice |
+| `library` | [Radio Library](./rss-radio-board.md#library) | Serves the audio, read-only |
+
+What holds them together is deliberately thin, and **it is not a wire**. The
+radio reads the editor's output *as a feed*, and the editor reads the reader's
+the same way, which is why neither knows the reading list is a SQL table — or
+that there is a reading list at all. Give either any feed and it does the same
+thing. That is also how the editor was added: placed between two units that
+already spoke feeds, with nothing in the radio changed but the address it
+reads. It reaches the voice and the library by
+mount reference: a board names a service, and the
+[coordinator](../concepts/coordinator.md) resolves the address when the board
+loads. It shares the library's bytes by **naming the same volume**, the way two
+boards share a database.
+
+Each unit's runtimes keep the unit's own board name, so a unit composed here is
+the same to a server as a unit opened alone — the same endpoints, the same
+tables. What the composition qualifies is the runtime id, which is why the voice
+is addressed as `voice.speech` here and as `speech` when it runs by itself.
+
+## The lanes
+
+The lanes are the board's only face: the units' own facades are for opening
+each unit alone, and a composition shows none of them (`"view": false`). The
+board's face follows one article from the feed it came from to the
+audio it became, in five [swimlanes](./swimlanes-demo-board.md):
+
+| Lane | A card here is | What you can do |
+|---|---|---|
+| **Sources** | a feed the reader subscribes to | add one, unsubscribe |
+| **Items** | an article in a feed, not yet kept | drag it onto the reading list |
+| **Reading list** | a kept article, waiting for the editor, being briefed, or failed | Retry or Use the feed's line on a failed one; drag it back to drop it |
+| **Briefed** | an article with its brief, waiting for the radio, being voiced, or whose audio failed | read the brief; Retry failed audio |
+| **On air** | an article the radio has read aloud | play it on the card; Forget it |
+
+Under the lanes are the two addresses the board publishes for use elsewhere:
+**the reading list as a feed**, for any RSS reader, and **On air as a
+playlist**, an M3U of everything voiced, newest first, for VLC, Music or any
+desktop player.
+
+The lane *is* the state: done is the next lane, and a card says only what is
+happening to it where it is — *waiting*, *briefing*, *failed* and why. Moving a
+card is the system's everywhere except onto the reading list and back off it.
+
+What makes that possible without merging the units is that **the reader, the
+editor and the radio share one database here** — `reading-radio`, set as each
+unit's `database` param. Each keeps its own table, `article`, `brief` and
+`episode`, and its own contract: opened alone, each unit uses a database of its
+own and works on any feed it is given. Composed, the three tables sit side by
+side, and one query in the board's `desk` runtime joins them on the article's
+link and says for every article which lane it is in. It is re-read every five
+seconds and after every action a card offers, so nothing needs refreshing.
+
+That query declares the three tables itself, copied from the units, so the lanes
+work before any unit has created its table. A unit changing its table changes
+the copy here too.
+
+## Radio
+
+*A feed, read aloud.* Every minute it reads the feed it was given; anything it
+has not spoken before is sent to a voice and the audio kept in the library.
+
+The feed is the only thing it knows about its source, and that is what makes it
+general. Two things in its pipeline are worth reading closely.
+
+**The claim** is one [SQL](../services/sql.md) statement doing the work of a
+lease. It takes the item and hands back *nothing at all* when the item is
+already spoken or is being spoken right now — and returning nothing
+[stops that pass](../concepts/runtime.md#control-flow), which is how work is
+skipped without a conditional. It also gives back the path the episode is to be
+kept at, built from the item's identity rather than from a counter that would
+drift. Nothing is taken again by itself.
+
+**A voice that fails is recorded, not retried.** The call to the voice is a
+[Join](../services/join.md) that reports a failure beside the article
+([`onFailure: "merge"`](../services/join.md#when-the-detour-fails)), and a
+[Tracks](../services/tracks.md) branches on what came back: one track keeps the
+audio — only a `200` carrying bytes — and the other writes down why there is
+none, in a `voicing` table beside the ledger: the voice's error, *the voice
+answered HTTP 503*, *the voice answered without audio*. Each track stops itself
+when it is not the one that applies. A failed article waits under **Being
+read**, and in the lanes, until somebody presses Retry; one that started and
+never finished counts as failed after `stuckAfter` (fifteen minutes).
+
+**The path comes back with the audio**, in a header the voice sets, because an
+answer arriving later than the pass that asked for it has to say what it is an
+answer to.
+
+**Forgetting an episode** is the claim run backwards, in a runtime of its own:
+*Remove* beside an episode in the Listen panel's player deletes its row from the ledger
+and its audio from the library, and what that leaves behind runs on into the
+playlist, so the list redraws without being asked. Because the claim is the
+only memory of what was spoken, an article still on the reading list is simply
+work again on the next round — removing a broken episode is how it gets read
+again. The runtime sits in the chain between the published feed and the
+playlist, so its first step lets through only a request naming an episode;
+the feed's answer, which arrives there every minute, stops at it.
+
+A round asks the feed for its ten newest and lets the claim decide which are
+work. Nothing limits the iteration itself, because an
+[Iterator](../services/iterator.md) would cut the list before the claim saw it,
+and an article below the cut would never get another turn.
+
+## Editor
+
+*A feed, briefed.* Every minute it reads the feed it was given; any article it
+has not read before is fetched, read by a language model, and given a brief of
+two to four sentences written to be heard rather than read. What it publishes is
+the same feed again, with the brief where the feed's own line was — which is the
+text the radio speaks after the title.
+
+**An article reaches the published feed only once its brief is written.** That
+is the whole of its contract with the radio: the radio never sees an article
+before the editor has read it, so it never speaks one without its brief.
+
+**The claim** is one SQL statement that takes an article the editor has not
+seen or hands back nothing, so an article already briefed, being briefed, or
+failed stops its own pass. Nothing is taken again by itself.
+
+**Two detours, one after the other.** The page is fetched and its text taken out
+of the HTML; then the title, the feed's line and that text go to the model. Each
+is a [Join](../services/join.md), so each comes back *beside* the article rather
+than instead of it — which is how the brief still knows which article it
+belongs to when it is filed. The fetch names its address in the request
+([`meta.url`](../services/http.md#a-request-that-says-where-it-is-going)),
+because every article lives somewhere else.
+
+**A page that cannot be read is not a failure.** A 404, a paywall, a PDF, a
+site that never answers: the model is told the article could not be read, and
+briefs from the title and the feed's line alone — saying less rather than
+guessing. The desk says so beside the brief, with what happened to the page.
+
+**A brief that fails is recorded, not retried.** The second detour reports a
+failure beside the article instead of stopping
+([`onFailure: "merge"`](../services/join.md#when-the-detour-fails)), and the
+last step files either the brief or the reason it is missing. A failed article
+stays on the desk with that reason — *Failed: API returned HTTP 401*, *Failed:
+the model used all 2000 tokens without answering* — and waits for a person:
+**Retry** runs that one article through the pipeline again, and **Use the feed's
+line** publishes it with the line its feed gave it, which the radio then reads
+like any brief. A brief that started and never finished — a runtime restarted
+mid-way — counts as failed after `stuckAfter` (ten minutes), so nothing says
+"briefing" forever.
+
+The model is Claude on hkp-node's `anthropic`
+[backend](../services/text-generation.md), with the key from the secret
+`anthropic.key` — hkp-node reads no key from its environment. Setting the unit's `backend` param to `server`, `serverUrl` to
+an OpenAI-compatible server and `apiKey` to empty briefs with a local model
+instead, and nothing else in the board changes.
+
+## Voice
+
+*A voice, as an endpoint.* POST `{"path": "episodes/x.mp3", "text": "…"}` and
+the answer is that text spoken, as an mp3.
+
+It keeps nothing and knows nothing about what it is reading: no feed, no
+library, no idea what an episode is. That is what makes it reusable — anything
+with text and somewhere to put audio can call it.
+
+The answer carries the path it was asked about in an `x-episode-path` header,
+because a caller holding many items needs to know which one came back. Inside, a
+[Join](../services/join.md) is what carries that path across the speaking:
+[text-to-speech](../services/text-to-speech.md) answers with audio rather than
+with the request *and* the audio, so the request is kept beside the detour
+rather than replaced by it.
+
+When it cannot speak — the model is missing, the encoder is not installed — it
+answers `502` with the reason as JSON, never `200` with something that is not
+audio, so a caller can tell a rendering from a failure without opening the
+bytes.
+
+## Library
+
+*A folder of audio, served.* Whatever is written into the volume it names is
+readable over one address: ask the address itself for a listing, or a path under
+it for the file, with the content type its extension means and range requests
+answered so a player can seek.
+
+It is the public half of the library and nothing else: its
+[Storage](../services/storage.md) services are **read-only**, which is what
+makes an unauthenticated endpoint safe to hand out. Writing happens through a
+different instance, inside the Radio unit.
+
+Storage names a place on the board rather than a place on a disk — what actually
+holds the bytes is its nested pipeline,
+[filesystem](../services/filesystem.md) here. Swapping that for something
+speaking S3 changes nothing outside the service.
+
+## Try it
+
+Needs an hkp-node and an hkp-python, kept under the names `node` and `python`
+in *Manage runtime servers* — both default to port 8080, so start one of them
+on another (`PORT=9000 hkp-python`). The editor needs an Anthropic API key,
+under **Settings → Secrets** as `anthropic.key`. hkp-python needs the
+speech and mp3 extras, which a plain `uv sync` in hkp-python installs. The first call
+downloads the Kokoro model (~310 MB) and takes a while; later ones do not.

package/bundle/docs/content/boards/send-ntfy-board.md

@@ -0,0 +1,33 @@
+# Send ntfy
+
+Takes a topic and a message, posts the message as a push notification, and
+answers with a confirmation somebody could read aloud. A skill target for the
+voice assistant boards.
+
+## What it does
+
+Given `{ topic, message }`, it POSTs to `https://ntfy.sh/<topic>` and returns
+`{ text: "Notification sent to topic …" }`.
+
+## How it works
+
+One [browser runtime](../concepts/runtime.md), four services.
+
+1. **Build Request**, a [Map](../services/map.md) in `replace` mode, turns the
+   incoming `{ topic, message }` into a URL and a body.
+2. **POST ntfy**, a [Fetcher](../services/fetcher.md), sends it.
+3. **Build Confirmation**, a [Map](../services/map.md), phrases the result as a
+   sentence.
+4. **Confirmation**, a [Monitor](../services/monitor.md), reports it.
+
+## Why it answers in words
+
+A skill that sent the notification and returned nothing would leave the calling
+assistant with nothing to say. Returning a sentence is the contract every skill
+target on these pages follows: the caller's
+[text-to-speech](../services/text-to-speech.md) reads whatever comes back, so
+the skill decides how its own success is announced.
+
+It is dispatched by name through [Skill Router](../services/skill-router.md) via
+a [Board Service](../services/board-service.md) in *board name from input* mode.
+Save it locally as `send ntfy`.

package/bundle/docs/content/boards/shared-costs-demo-board.md

@@ -0,0 +1,65 @@
+# Shared Costs
+
+Shared costs for a flat. Whoever paid adds what it was for and how much; it is
+split evenly between everyone in the flat at that moment, and each person sees
+what they owe or are owed. No board like it shipped with Readymade:
+[Board Assist](../concepts/board-assistant.md) composed this one from a single
+description.
+
+## What it does
+
+Open the board and you join the flat. On **Balances**, type what you paid for
+and how much, *Groceries 42.50*, and press **Add**. The total at the top says
+what you owe or are owed across everything, and the list below says it for
+everyone in the flat. **Expenses** lists what was paid for, newest
+first, with your share of each. Only whoever paid can remove an expense.
+
+## How it works
+
+One [REST runtime](../concepts/runtime.md#the-servers) on hkp-node, kept under
+the name `node`. Six [SQL](../services/sql.md) services share one database,
+`flat-costs`: three that change something and three that read it back.
+
+**Actions** — Join the flat · Add an expense · Remove an expense
+
+**Queries** — My balance · Everyone's balance · The expenses
+
+Every action enters the same pipeline at **Join the flat**, which runs when
+the board opens, and the queries at the end re-read what it just changed. What
+you see after adding an expense is what the database now says.
+
+## The rules live in the schema
+
+- **An expense needs a payer who is in the flat, says what it was for, and has
+  an amount above zero.** Four triggers, each refusing with a sentence that
+  tells you what to do instead.
+- **The even split is a trigger too.** When an expense is added, one share per
+  flatmate is written beside it. Money is kept in cents, and a leftover cent
+  or two goes to whoever joined first, so the shares always add up to what was
+  paid.
+- **A share goes with its expense.** Removing an expense removes its shares.
+
+Because the split is written when the expense is added, somebody who joins the
+flat later does not owe for what was bought before they came.
+
+## Who paid
+
+Every expense is recorded for the signed-in caller. The statements use
+`$caller_email` and `$caller_name`, which the server that verified the sign-in
+states, and the facade has no "paid by" field. Without a signed-in caller the
+board shows the balances but takes no expense. Others in the flat are shown a
+flatmate's name, never their address. See
+[callers and members](../concepts/cloud-boards.md).
+
+Deployed and shared, the flat is the board's members: each signs in to the
+board's app and nothing else, and they all use one database.
+
+## How it was made
+
+The board is the one Board Assist proposed in a recorded run (Claude
+Opus 5.5) from this description: whoever paid adds it, it is split evenly,
+everyone sees what they owe, each expense in the name of whoever is signed in,
+on the node server so the flat can share it. That conversation took five
+requests and 201,393 tokens, about $0.99. The proposal's review listed 138 new
+lines, all six statements. The form, the lists, the sign-in and the sharing
+are services other boards already use.

package/bundle/docs/content/boards/spectral-modifier-board.md

@@ -0,0 +1,55 @@
+# Spectral Modifier
+
+Audio captured on one machine, transformed in the browser, and reconstructed on
+another — a three-runtime chain where the middle link is a person moving a
+filter around a spectrum.
+
+## What it does
+
+It takes microphone audio on a native runtime, sends the FFT spectrum to the
+browser for display and filtering, and sends the filtered spectrum on to a
+second native runtime, which turns it back into sound.
+
+## How it works
+
+Three runtimes, and the order is the signal path.
+
+### Audio Input — a realtime runtime
+
+1. **Microphone** (`core-input`) captures audio natively. The browser could
+   record too, but this board is about a capture device that is not where the
+   interface is.
+2. [FFT](../services/fft.md) transforms it into a complex spectrum with a
+   512-sample window.
+
+### Spectrum — the browser
+
+1. [Analyzer](../services/analyzer.md) draws the spectrum so you can see it.
+2. **Spectral Filter**, a [Filter](../services/filter.md) with an `and`
+   aggregator, is where the editing happens — the conditions you set decide
+   which frequency bins survive.
+
+### Audio Output — a second realtime runtime
+
+1. [IFFT](../services/ifft.md) inverts the transform, with the same 512-sample
+   window.
+2. [Monitor](../services/monitor.md).
+3. **Speaker** (`core-output`) plays it, in `buffer-incoming` mode so arriving
+   frames queue rather than fight.
+
+## Why three runtimes
+
+Because the three jobs want three different places. Capture and playback want
+native audio hardware and low latency; the spectrum wants a screen and a mouse.
+Splitting them is not an optimisation — the board would not work as well in any
+one of the three.
+
+It is also the clearest illustration of what
+[crosses a runtime boundary](../concepts/runtime.md#what-crosses-a-runtime-boundary):
+what travels between these runtimes is a spectrum, serialised, not audio and not
+a function call.
+
+## Try it
+
+It needs two runtimes reachable as `hkp://remotes/realtime`, and the FFT and
+IFFT window lengths must match — 512 in both, or the reconstruction is wrong.

package/bundle/docs/content/boards/spotify-board.md

@@ -0,0 +1,46 @@
+# Spotify to GitHub
+
+Reads what you are listening to and commits it to a Git repository — then reads
+it back from a second runtime. Two chains that never talk to each other, joined
+only by the file one writes and the other reads.
+
+## What it does
+
+The first runtime polls Spotify for the current track and appends it to a file
+in a GitHub repo. The second runtime reads that file back. The result is a
+listening history you own, in a repository you control.
+
+## How it works
+
+Two [browser runtimes](../concepts/runtime.md), and this is the point of the
+board: they are **separate chains in one document**, not a pipeline split in
+two. The collector writes; the reader reads; neither knows the other exists.
+
+**Collector**
+
+1. [Spotify](../services/spotify.md) fetches the currently playing track.
+2. **Map Track**, a [Map](../services/map.md), reduces it to the fields worth
+   keeping.
+3. [Monitor](../services/monitor.md) shows what is about to be written.
+4. [GitHub Sink](../services/github.md) commits it to `owner/repo` on the
+   configured branch.
+
+**Reader**
+
+1. [GitHub Source](../services/github.md) fetches the file back.
+2. [Monitor](../services/monitor.md) shows it.
+
+## Why two runtimes
+
+They could have been one chain. Keeping them apart means each can be run on its
+own — collect without reading, read without collecting — and the storage between
+them is a Git repository rather than anything this board holds. GitHub is being
+used here as the database, with version history as a free side effect.
+
+## Try it
+
+Both halves need configuring before anything happens: a Spotify token on the
+Spotify service, and a GitHub token plus `owner`, `repo` and `branch` on both
+GitHub services. Nothing is stored in the board — see
+[secrets](../concepts/board.md) for why credentials are kept out of the
+document.

package/bundle/docs/content/boards/sql-explorer-board.md

@@ -0,0 +1,70 @@
+# SQL Explorer
+
+Every SQL database this browser keeps, and what is in it — to look at, to
+change, and to take somewhere else.
+
+## What it does
+
+The first column lists the databases the [SQL](../services/sql.md) service
+keeps in this browser, with their size. Pick one to see its tables and views;
+pick a table to see its rows. Click a value to change it in a small dialog;
+tick rows and **Delete picked rows** to remove them. **Export .sql** saves a
+database as an ordinary SQL dump.
+
+Changes go straight into the database, so the board that owns it sees them the
+next time it reads: renaming a member here renames them on the court booking
+too. Export first if you may want the old state back.
+
+The databases are the ones other boards made: book a court on
+[Court Booking (Browser)](./court-booking-browser-demo-board.md) and `tennis`
+appears here, with its `booking` table.
+
+## How it works
+
+One browser runtime holding four small pipelines, one for each thing the
+facade asks. Each is a sub-service that keeps its result to itself, so picking
+a table does not also re-list the databases:
+
+1. **Which databases** — `sql` in `databases` mode.
+2. **Which tables** — a query over `sqlite_schema`.
+3. **Which rows** — the table's rows, and the two statements that change them:
+   one setting a value, one deleting picked rows.
+4. **The dump** — `sql` in `export` mode, then [Download](../services/download.md).
+
+Picking a database configures the other three with its name. Picking a table
+configures the row statements for that table. A table or column name, unlike a
+value, cannot be a bound parameter, so the tables query writes those three
+statements for each table itself — every name quoted as an identifier, every
+value still a parameter:
+
+```sql
+UPDATE "booking" SET "member" = CASE WHEN $column = 'member' THEN $value ELSE "member" END, …
+ WHERE $action = 'update' AND rowid = $rowid
+```
+
+Rows are addressed by their `rowid`, the first column shown. A view, or a table
+declared `WITHOUT ROWID`, has none to address, so those are shown but not
+changed. Neither is a table with a column of its own called `rowid`: there the
+name means that column, whose values need not be unique, so a statement written
+for one row could reach several.
+
+Editing a cell is the data table's `cellActions`: a **prompt** step asks for the
+new value, starting from the current one, and hands the answer to the update.
+A value typed into a numeric column is stored as a number, as SQLite does
+with any text that looks like one; there is no way to set a value to `NULL`
+from the dialog.
+
+## Taking the tables to hkp-node
+
+The exported file is what hkp-node's SQL service imports — load it with
+[SQL Import](./sql-import-board.md), and a board on hkp-node that names the
+same database carries on with the same tables.
+
+To look into the databases a server keeps instead, use
+[SQL Explorer (hkp-node)](./sql-explorer-node-board.md): the same board with
+the runtime changed.
+
+## Try it
+
+Open it. Nothing to install; if the list is empty, a board using the browser's
+SQL has not stored anything yet.

package/bundle/docs/content/boards/sql-explorer-node-board.md

@@ -0,0 +1,76 @@
+# SQL Explorer (hkp-node)
+
+Every SQL database your hkp-node keeps for you, and what is in it — the
+[SQL Explorer](./sql-explorer-board.md) pointed at a server instead of at this
+browser.
+
+## What it does
+
+The first column lists the databases hkp-node's [SQL](../services/sql.md)
+service keeps under your sign-in, with their size. Pick one to see its tables
+and views; pick a table to see its rows. Click a value to change it; tick rows
+and **Delete picked rows** to remove them. **Export .sql** saves a database as
+an ordinary SQL dump.
+
+## Whose databases
+
+Yours, and that is exact rather than a manner of speaking. hkp-node is used by
+several people at once, and it files every database under the **owner of the
+runtime asking** — the person the server verified, never a name a board
+supplies. So this board has no setting for whose databases to show: opened by
+you it lists yours, and opened by somebody else on the same server it lists
+theirs. Naming a database that belongs to another person does not reach it —
+the name is looked up inside your own tenant, and finds your own database of
+that name or an empty one.
+
+Three things follow from that, and are worth knowing before you rely on it:
+
+- **A deployed board's data is here too.** A board you deployed to a
+  coordinator runs in your tenant, so the tables of your deployed
+  [Court Booking](./court-booking-demo-board.md) show up as `tennis` — the
+  bookings its members made included. That is what makes this the tool for
+  looking into a shared board.
+- **It is the live database.** A change made here is what the board reads
+  next. Export first if you may want the old state back.
+- **Only named databases are listed.** A board that leaves `database` empty
+  has its tables filed under a name derived from its title, which nobody can
+  write back as a name — so it cannot be opened from here. Give a board a
+  `database` if you want to look into it.
+
+On a server running without sign-in — a local one — everybody is the same
+anonymous owner, and the list is everything that server keeps.
+
+This is an owner's tool. It is not something to [share](../concepts/cloud-boards.md#sharing-a-board-members):
+it changes whatever statements its facade is pointed at, which is exactly what
+a member of a board is not allowed to do.
+
+## How it works
+
+The statements are the browser explorer's, unchanged — both runtimes are
+SQLite — so what differs is only where they run:
+
+1. **hkp-node** — three sub-services that each keep their result to
+   themselves: which databases (`sql` in `databases` mode), which tables (a
+   query over the schema that also writes the statements for each table), and
+   which rows, with the two statements that change them.
+2. **Browser** — an [Injector](../services/injector.md) the export button
+   starts.
+3. **hkp-node** again — `sql` in `export` mode.
+4. **Browser** — [Download](../services/download.md) saves what arrives.
+
+The export is four steps rather than one because of where a result goes. Asking
+a service on hkp-node to do its job answers whoever asked and travels no
+further, which is right for a list the facade draws — but a dump has to end up
+in the browser's Download. So the export is begun in a browser runtime: its
+output becomes the input of the runtime after it, hkp-node answers with the
+dump, and that becomes the input of the last runtime, which saves it.
+
+## Try it
+
+Needs an hkp-node kept under the name `node` in *Manage runtime servers*.
+If the list is empty, no board of yours has stored
+anything there under a name yet —
+[Court Booking](./court-booking-demo-board.md) does, as `tennis`.
+
+To carry a database the other way, from a browser to hkp-node, use
+[SQL Import](./sql-import-board.md).

package/bundle/docs/content/boards/sql-import-board.md

@@ -0,0 +1,37 @@
+# SQL Import
+
+Carries a database on to hkp-node: pick an SQL dump, name the database it goes
+into, and send it.
+
+## What it does
+
+The dump is typically one the [SQL Explorer](./sql-explorer-board.md) exported
+from a browser, but any SQLite dump will do. Once imported, the database is
+your hkp-node's, and any board there naming it carries on with its tables —
+import a browser's `tennis` and [Court Booking](./court-booking-demo-board.md)
+on hkp-node shows the bookings made in the browser.
+
+The list on the right is what hkp-node keeps under names a board can use.
+
+## How it works
+
+Two runtimes, chained:
+
+1. **Browser** — [File Source](../services/file-source.md) reads the file the
+   facade's file picker hands it, and passes the text on.
+2. **hkp-node** — [SQL](../services/sql.md) in `import` mode runs it against
+   the named database, then SQL in `databases` mode lists what is there.
+
+An import is all or nothing: a dump is one transaction, so a row that collides
+with one already in the database — importing the same dump twice, say — keeps
+none of it, and the notice names the row. The database is created when it does
+not exist; one that already has the dump's tables, empty or not, takes the rows
+too.
+
+An import runs text that came from outside, so it may not reach past its own
+database — no `ATTACH`, `VACUUM`, `load_extension`, or `PRAGMA` beyond
+`foreign_keys`. A dump never needs them.
+
+## Try it
+
+Needs an hkp-node kept under the name `node` in *Manage runtime servers*.