@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/boards/swimlanes-demo-board.md

@@ -0,0 +1,148 @@
+# Swimlanes
+
+Five ordered card lanes backed by SQLite and composed from five independent
+`swimlane` facade widgets. It is a small Trello-shaped board rather than a
+workflow engine: people open it, arrange work and change the cards in real
+time.
+
+## What it does
+
+- **Backlog** and **Ready** allow cards to be created.
+- **In progress**, **Review** and **Done** only accept cards moved into them.
+- Every card can be edited or deleted in every lane.
+- Cards can be moved between any two lanes and reordered within a lane.
+
+Each lane is a widget in an ordinary facade row. Adding a sixth lane means
+adding another widget with another `laneId`; there is no enclosing kanban
+widget to change.
+
+## One query, several views
+
+Every lane reads `read-board.rows`, the result of one [SQL](../services/sql.md)
+query. A lane selects the rows carrying its own `laneId` and orders them by the
+query's `position` field. Empty lanes still exist because the lane itself is
+facade composition, not a group inferred from whichever cards happen to exist.
+
+The widgets share only a `dragGroup`. While a card is being dragged, the facade
+uses that group to let the destination lane recognise it. Cards and rules never
+move into frontend state: the drop sends an operation to SQL, and the query at
+the end of the pipeline redraws every lane from the database's answer.
+
+Dragging is one way to move a card, not the only one. A card that can be
+dragged also carries a **Move** menu naming the lanes of its group that would
+take it, and — in a lane that takes cards itself — one place up or down. It
+sends the same operation a drop does, so a keyboard, or a host that delivers no
+drag from a touch, reaches everything a pointer does.
+
+## The services
+
+One REST runtime on hkp-node holds six top-level services:
+
+1. **Move or reorder a card** ranks the destination lane and changes its order
+   and the moved card's lane in the same SQL statement.
+2. **After a card moves** is a [SubService](../services/sub-service.md) holding
+   a **Move event** Monitor.
+3. **Create a card** appends a card to a lane.
+4. **Edit a card** changes its title and description.
+5. **Delete a card** removes it.
+6. **Read the board** returns the ordered rows all lanes display.
+
+The changing statements use `emit: "input"`, so the operation survives until
+the final query. Each operation enters at the service that owns it: creating a
+card starts at **Create a card**, for example, and therefore does not pass
+through the move hook that sits earlier in the runtime.
+
+## Following a move with another board
+
+`After a card moves` currently passes the event through a Monitor, so opening
+**Move event** inside the SubService shows exactly what a downstream board could
+receive. The Monitor is observational: its output is the same value as its
+input, so the board still reaches the refresh query afterward.
+
+To add custom behaviour later, follow or replace the Monitor with services in
+that SubService. An HTTP Client can call an endpoint on another composed board
+by using its `hkp-mount://<runtime>/<service>` reference.
+
+The event already carries:
+
+```json
+{
+  "operation": "move",
+  "cardId": 4,
+  "fromLaneId": "doing",
+  "toLaneId": "review",
+  "fromPosition": 0,
+  "toPosition": 1,
+  "card": { "cardId": 4, "title": "Build swimlane widget" }
+}
+```
+
+That keeps the swimlane widget ignorant of the board that reacts to a move.
+The extension remains an ordinary nested pipeline; the Monitor makes its
+contract visible while the real integration is still absent.
+
+## The swimlane widget
+
+The conventional source fields are `cardId`, `laneId`, `title`, `description`
+and `position`. A board can point each field at a different, dotted name using
+`cardIdField`, `laneIdField`, `titleField`, `descriptionField` and
+`positionField`.
+
+`allowCreate` only controls whether the lane offers the create button. The
+actual effects stay explicit as `createActions`, `editActions`,
+`deleteActions` and `moveActions`. Their templates are filled from the
+operation object before the normal facade action runner processes them.
+
+For an unrestricted board, `moveActions` continues to make a lane both
+draggable and a drop target. A workflow can separate those capabilities with
+`allowDrag` and `acceptDrops`: a review lane can supply the card being dragged,
+while a drop-only destination owns the approval action. This makes the drop a
+domain command rather than pretending the facade has already moved persisted
+state. The **Move** menu follows the same two permissions: it appears on cards
+that may be dragged and lists only lanes that accept drops.
+
+`selectable` lets a card be selected, by a click or with Enter on a focused
+card; selecting it again lets go. The selection is not kept by the lane: the
+card's id is written to facade state under `selectionState`, so the five lanes
+of this board, which all name `selectedCard`, hold one selection between them,
+and a button can act on it with `{ "$state": "selectedCard" }`. A selected card
+stays selected when it is moved and is let go when it is deleted.
+
+A lane can also be a **stage of work** rather than a pile of cards — the card's
+lane says how far it has got, and the card says what is happening to it there.
+`statusField` names the row's state (`working`, `failed`) and shows it as a chip
+in the colour `statusColors` gives it; `detailField` adds a line saying more,
+such as the reason a step failed or since when it has been running.
+`cardActions` puts buttons on the card for what a person does to that one card
+where it is, each with `{{item.*}}` templates like the lane's other actions and
+an optional `visibleWhen: { field, equals? }`, so a **Retry** appears on the
+failed cards and nowhere else:
+
+```json
+"cardActions": [{
+  "label": "Retry",
+  "visibleWhen": { "field": "status", "equals": "failed" },
+  "actions": [{ "type": "process", "serviceUuid": "each.name",
+                "payload": { "id": "{{item.cardId}}", "retry": 1 } }]
+}]
+```
+
+A lane need not share its source with the others. `allRows` makes every row
+of its source the lane's, for a source whose rows know nothing of lanes — a
+list of subscribed feeds. `except: { source, idField? }` leaves out the cards
+another source already holds, compared by card id: a feed's articles, less the
+ones already on the reading list, so a card is in one lane and not two.
+
+`audioField` names an address to play, and gives each card that has one a
+player; starting one card stops whichever card on the page was playing.
+
+The generic editor wording can also be adapted without introducing a new
+widget. `editorTitle`, `titleLabel`, `descriptionLabel` and `saveLabel` let a
+mail board call a card's fields **Subject** and **Body**, for example.
+
+## Try it
+
+Run hkp-node, keep it under the name `node` in *Manage runtime servers*, and
+open **Swimlanes** from the demo list. The schema
+and starter cards are created on first run in the board's `swimlanes-demo`
+database.

package/bundle/docs/content/boards/syn-mail-desk-board.md

@@ -0,0 +1,52 @@
+# SYN Mail Desk
+
+`syn-mail-desk-board.json` is the existing SYN composition with a human review
+facade in front of it. The booking and hotels units are included unchanged;
+their original facades are hidden in this composition, and remain available in
+the original `syn-board.json`.
+
+This is the first stage: the desk drafts follow-ups and the human in the loop
+reviews them. Handing enquiries that are ready for an offer on to the next
+board comes next.
+
+## The three lanes
+
+- **Incoming mail** shows active enquiries received and filed by the booking
+  unit.
+- **Needs human review** shows the latest pending follow-up draft. Its card
+  editor calls the generic fields **Subject** and **Body** and writes only to a
+  still-pending draft.
+- **Waiting for user response** shows conversations whose approved email was
+  sent successfully.
+
+Only review cards can be moved, and only the waiting lane accepts them — by
+dragging the card there, or from the card's **Move** menu. Either way the
+move asks for confirmation and marks the draft approved through the
+Conversations service. It does not move facade state. The unchanged booking
+dispatcher observes the approval, sends through SMTP, files the outbound mail,
+marks the artifact sent and transitions the conversation. The database query
+then places the card in the waiting lane. If sending fails, the conversation
+does not transition and the card remains in review.
+
+## Composition
+
+The small `syn-mail-desk-unit-board.json` unit is an adapter, not a second mail
+engine. It uses the explicitly named `syn-booking` database owned by the
+booking workflow and projects conversations, inbound messages and follow-up
+artifacts into the five fields a swimlane consumes. Its **Approved draft
+event** Monitor exposes the approval artifact after every approved drop; more
+services, including a call to another board, can be composed after that
+Monitor later.
+
+Run hkp-node, keep it under the name `node` in *Manage runtime servers*, and
+load these four sibling board documents
+together when opening the composition:
+
+- `syn-mail-desk-board.json`
+- `syn-booking-unit-board.json`
+- `syn-hotels-unit-board.json`
+- `syn-mail-desk-unit-board.json`
+
+The same mail and model secrets required by the original SYN board are still
+required. SMTP recipient restrictions also remain exactly as configured in the
+booking unit.

package/bundle/docs/content/boards/timeline-demo-board.md

@@ -0,0 +1,115 @@
+# Timeline Demo
+
+A night sky in which stars pop up, a planet appears and a rocket and a comet
+fly across, eight seconds long and looping. It has no animation code: every
+image is animated by keyframes on a [timeline](../services/timeline.md) of its
+own, and one outer timeline arranges them all.
+
+## What it does
+
+The show starts when the board loads. **Pause** holds it, **Play** carries on,
+and **Stop** takes it back to the start. Each star appears with an overshoot,
+turns a full circle and fades; the planet does the same, large in the middle
+of the sky; the rocket climbs from the bottom left to the top right and the comet
+crosses the other way, a small star moving fast. The sky behind them shifts from night to dusk and back
+over the eight seconds.
+
+## How it works
+
+One [browser runtime](../concepts/runtime.md) with three services:
+
+```
+Show                       (Timeline, own clock: 8 s, looping, 30 fps)
+Scene                      (Tracks, one track per image, run in order)
+├─ sky                     Timeline, reads the Show's time
+├─ planet                  Pop  · name "planet"
+├─ star-1                  Pop  · name "star-1"
+├─ star-2                  Pop  · name "star-2"
+├─ star-3                  Pop  · name "star-3"
+├─ star-4                  Pop  · name "star-4"
+├─ rocket                  Fly  · name "rocket"
+└─ comet                   Fly  · name "comet"
+Canvas                     (draws the Scene's answer)
+```
+
+The **Show** keeps the clock. Thirty times a second it emits a frame: the time,
+and which of the names it places are playing and how far into their placement
+they are. The frame carries no picture; it only says when.
+
+The **Scene** is a [Tracks](../services/tracks.md) service, so every track is
+given the same frame. Each track answers with the drawing instruction for its
+image as it is at that moment, or with null while its image is not playing.
+Tracks collects the answers into a list in declaration order, which makes the
+first track the one at the back: the sky is drawn first, the comet last.
+
+The [Canvas](../services/canvas.md) clears on every frame and draws the list,
+skipping the holes. An image that is not playing is not drawn.
+
+## Two blocks
+
+The motions are written once, as [blocks](../concepts/blocks.md). Each block is
+one timeline holding one image and the keyframes that move it:
+
+| Block | Its own length | What it does |
+|---|---|---|
+| **Pop** | 3 s | Grows from nothing to 125 % in half a second and settles at full size; turns a full circle over the three seconds; stays opaque until 2.2 s, then fades out |
+| **Fly** | 4 s | Travels from one point to another, easing in and out; starts tilted 40° and levels off; grows on the way up and shrinks a little as it arrives |
+
+Every use says only what differs:
+
+| Parameter | Pop | Fly |
+|---|---|---|
+| `image` | a star by default; the planet's use gives a ringed planet | a rocket by default; the comet's use gives a small star |
+| where | `x`, `y` (the centre) | `fromX`, `fromY`, `toX`, `toY` |
+| `size` | height, as a share of the canvas | height, as a share of the canvas |
+| `name` | the name it plays under | the name it plays under |
+
+A use does not say *when* it plays. That is the Show's business.
+
+## Placements
+
+The Show's [placements](../services/timeline.md#placements) put a name at a
+moment for a while. The timeline inside each use takes the name its `name`
+parameter gives it, and plays while that name is placed:
+
+| Name | At | For | Its own length | So it plays |
+|---|---|---|---|---|
+| `star-1` | 0 s | 3 s | 3 s | as written |
+| `star-2` | 0.7 s | 3 s | 3 s | as written |
+| `star-3` | 1.4 s | 3 s | 3 s | as written |
+| `star-4` | 2.1 s | 3 s | 3 s | as written |
+| `rocket` | 2.5 s | 4 s | 4 s | as written |
+| `planet` | 4.5 s | 3 s | 3 s | as written |
+| `star-1` | 5 s | 2 s | 3 s | 1.5 times as fast |
+| `comet` | 5.5 s | 2.5 s | 4 s | squeezed into 2.5 s |
+
+A timeline that does not loop is **stretched** to fit its placement, so the
+same motion can be placed at any length. The second `star-1` is the first one
+played again, faster; the comet is the rocket's flight, done in less time.
+
+Neither side knows where the other sits. The Show names `rocket` without
+knowing it is inside a track, inside a block; the rocket's timeline takes
+`rocket` without knowing what places it. That is what lets a use be moved to
+another track, or the whole Scene be rearranged, without touching the Show.
+
+Every track is still given every frame. A timeline whose name is not playing
+answers null at once, so the rest of its track does not run. In the overview,
+the timelines that are playing glow; the ones that are waiting show only a
+faint tint.
+
+## The sky
+
+The sky is a timeline too, but placed nowhere: it has no `name` to take, so it
+reads the Show's time directly. Its object is a rectangle the size of the
+canvas, and one keyframed property, its colour: `#0b1026` at 0 s, `#312e81`
+at 4.5 s, back to `#0b1026` at 8 s. Because the Show loops at 8 s, so does the
+sky.
+
+## Try it
+
+Pause the show and drag the Show's playhead: the whole board follows, and the
+canvas shows every image as it is at that moment. Open the Show's timeline,
+drag the comet's placement to start earlier, or stretch its bar to slow it
+down. Set `star-3`'s `name` parameter to `star-1` and it pops with the first
+star, twice a loop. Give it a name the Show does not place and it never
+appears, and its panel warns that its name is never placed.

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

@@ -0,0 +1,32 @@
+# Trigger Pad
+
+Three services: record audio, chop it into pads, play them back. The shortest
+board here that is a usable instrument.
+
+## What it does
+
+It captures microphone audio in two-second slices and lays them out as
+triggerable pads. Hit a pad and that slice plays.
+
+## How it works
+
+One [browser runtime](../concepts/runtime.md).
+
+1. **Audio Input**, from [Audio IO](../services/audio-io.md), records with a
+   `timeslice` of 2000 ms — so the stream arrives as two-second chunks rather
+   than one continuous buffer. That chunk size *is* the pad length.
+2. [Trigger Pad](../services/trigger-pad.md) holds the slices and emits one when
+   a pad is hit.
+3. **Audio Output**, also from [Audio IO](../services/audio-io.md), plays it.
+
+## Why it is this short
+
+Almost all of the behaviour is a single configuration value. `timeslice`
+decides what a pad contains, and the rest is two services that already know how
+to record and play. Nothing here slices anything — the recorder was asked to
+produce chunks, so chunks are what travel down the chain.
+
+## Try it
+
+It needs microphone permission. Let it record for a few seconds, then hit the
+pads.

package/bundle/docs/content/boards/triggerpad-recorder-board.md

@@ -0,0 +1,52 @@
+# Trigger Pad Recorder
+
+The [Trigger Pad](./triggerpad-board.md) board with a recorder in it: play the
+pads, record what you play, and play the take back.
+
+## What it does
+
+Hits go straight to the speaker, as on the Trigger Pad. Press record and play
+on the Recorder, and every hit is also kept at the moment it was played. Stop,
+play again, and the take plays back as it was played, faster or slower if you
+change the Recorder's speed. Record a second time over it to add to the take
+(`overdub`), or to play it again from scratch (`replace`).
+
+## How it works
+
+One [browser runtime](../concepts/runtime.md).
+
+1. **Audio Input** and [Trigger Pad](../services/trigger-pad.md) work as on the
+   Trigger Pad board: two-second slices of the microphone, laid out as pads.
+2. **Recorder** is a [Timeline](../services/timeline.md) keeping its own clock.
+   It does not know it is fed by pads. Whatever arrives at its input is an
+   action happening now: it leaves in the frame for that moment, and while
+   recording it stays on the timeline at that moment. The Recorder is
+   unbounded and emits 60 frames a second, so a hit plays back at most a
+   sixtieth of a second late.
+3. **On a hit**, a [Filter](../services/filter.md), lets through only the
+   frames with an action in them. The Recorder emits a frame 60 times a
+   second whether anything is due or not.
+4. **The hit**, a [Map](../services/map.md), takes the action out of the frame,
+   so the speaker is given the audio itself.
+5. **Audio Output** plays it.
+
+## Looping a part of a take
+
+Drag across the strip above the Recorder's ruler to mark a loop range. The
+Recorder then repeats that stretch. Record in `overdub` to layer more hits
+onto it pass after pass, or in `replace` to play each pass anew. Press the
+range to switch looping off, and the whole take plays again.
+
+## Things to know
+
+- Anything that reaches the Recorder while it records is recorded, including
+  the microphone's slices if Audio Input is still recording. Stop the
+  microphone once the pads are filled.
+- The Map takes the first action of a frame. Two hits within a sixtieth of a
+  second of each other land in one frame, and only the first sounds.
+- A take lasts only while the board is open: audio is not saved with the board.
+
+## Try it
+
+It needs microphone permission. Fill the pads, stop the microphone, then press
+record and play on the Recorder and play a pattern. Press stop, then play.

package/bundle/docs/content/boards/voice-assistant-demo-board.md

@@ -0,0 +1,51 @@
+# Voice Assistant
+
+Push Record, speak, push Stop, and hear an answer — with nothing leaving your
+machine. Speech in, speech out, across three runtimes that each do the part they
+are suited to.
+
+## What it does
+
+The browser captures your voice, a Python runtime transcribes it, answers it and
+speaks the answer, and the browser plays the result back.
+
+## How it works
+
+Three runtimes in chain order, and the split is the design.
+
+**1 · recorder — the browser.** [Audio IO](../services/audio-io.md) captures
+16 kHz PCM. Capture belongs here because the microphone is here; nothing else in
+the board could reach it.
+
+**2 · python — a [REST runtime](../concepts/runtime.md#the-servers), the remote `python`.**
+
+- [Speech To Text](../services/speech-to-text.md) transcribes with
+  faster-whisper.
+- **Transcript**, a [Monitor](../services/monitor.md), shows what it heard —
+  worth having, because most surprising answers turn out to be surprising
+  transcriptions.
+- [Text Generation](../services/text-generation.md) answers via an
+  OpenAI-compatible llama-server on port 8081. Its system prompt asks for one or
+  two short spoken sentences, no markdown and no lists, because the reply is
+  going to be read aloud rather than displayed.
+- **Answer**, another [Monitor](../services/monitor.md).
+- [Text To Speech](../services/text-to-speech.md) synthesises with Kokoro-82M.
+
+**3 · playback — the browser.** [Audio IO](../services/audio-io.md) plays it.
+
+## Why three runtimes rather than one
+
+The microphone and the speaker are in the page; the models are not, and could
+not be. What crosses each boundary is audio as a
+[FloatRingBuffer](../concepts/runtime.md#what-crosses-a-runtime-boundary) —
+serialised, not handed over. The board is the same shape it would be if the
+Python runtime were on another machine, which is the point: moving it there is a
+`url` change.
+
+## Try it
+
+Needs an hkp-python kept under the name `python` in *Manage runtime servers*,
+with both extras —
+`uv sync --extra asr --extra tts` in hkp-python — and an OpenAI-compatible LLM server on
+port 8081. First use downloads the Whisper and Kokoro models, so give it a
+moment.