moontide-mcp 2.2.0 → 2.4.0

package/README.md

@@ -2,6 +2,9 @@
 
 > The moon guides the tide.
 
+**Early:** Moontide is young and has known bugs, and its Scratchpad is early experimental (see the
+[known limits](https://konni-arcadia.github.io/moontide/troubleshooting.html#known-limits)).
+
 **A hobby project: Claude plays live music for you. Describe a mood, a theme or an idea, and
 Claude writes [Strudel](https://strudel.cc) code that plays in your browser and changes without
 ever stopping.**
@@ -20,389 +23,74 @@ written by an AI coding assistant working under my direction. I set the goals, l
 every change, tried it on my own instruments, judged the results by ear, and made the
 decisions. I am responsible for what is here, errors included.
 
-## Why
-
-Curiosity. I wanted to see how far an AI assistant can go at making real music, not a
-technical demo, when it is given a good instrument. Strudel is that instrument: a live-coding
-language where a change lands on the next cycle, with no cut, and where the music is plain text
-that both of us can read.
-
-So Claude writes the code, and the code stays on screen while it plays. You can watch it, edit
-it by hand, go back to any earlier version, or point at something in the page and ask for a
-change.
-
 ## What it does
 
 - You talk ("start something dreamy in D minor", "darker", "add a bass"). Claude writes
-  Strudel code, and a browser page plays it at once. Each change takes over within a fraction
-  of a second, without stopping the music.
+  Strudel code, and a browser page plays it at once, without stopping the music.
 - The code is always visible and editable. Every version that played is kept, and Claude can
   bring any of them back.
-- Around the code, the page shows the music in several views: the named tracks on a timeline
-  where you can edit notes, the Song grid with the sections of a piece, the history as a list
-  or a tree, a mixer with groups and lights whose moves rewrite the code, and a jam view with
-  the scale on a piano or a guitar. When the notes fit several scales, the jam view proposes
-  one and says why.
+- The page shows the music in several views: a timeline of named tracks where you can edit
+  notes, a Song grid, the history, a mixer and a jam view with the scale on a piano or a guitar.
+- A right-click on anything in the page sends Claude a request with that context.
 - Claude can move the tempo up or down over a number of bars, instead of jumping.
-- A right-click on anything in the page sends Claude a request with that context. The Requests
-  list in the top bar shows what became of each request.
-- The same code can play real MIDI instruments from the page, through Web MIDI.
+- The same code can play real MIDI instruments from the page, and a
+  [Scratchpad](https://konni-arcadia.github.io/moontide/scratchpad.html) (early experimental) lets you draw or play in a motif and send
+  it to Claude.
+- On an instrument whose model describes them, Claude can set tone, part and scene
+  [settings](https://konni-arcadia.github.io/moontide/synth-settings.html) that no program change carries, written in the code like a sound
+  or a control. Moontide stores none of them. The models that describe settings are files of your own;
+  none ships with Moontide.
 
 Moontide does not start from scratch. The music engine is
 **[Strudel](https://strudel.cc)**, the JavaScript port of TidalCycles by Felix Roos, Alex McLean and the
 Strudel contributors. Moontide is the bridge between Claude and a Strudel page.
 
-## How it works
-
-```
- you ──talk──► Claude ──MCP (stdio)──► Moontide ──WebSocket (localhost)──► browser page
-                                          │                                 Strudel plays
-                                          └─ history file on your disk      the code, sound
-                                                                            and Web MIDI out
-```
-
-1. Moontide runs as an MCP server that Claude connects to. It starts nothing until you ask
-   for music or say "start Moontide".
-2. It then opens a page in your browser with a Strudel editor.
-3. Claude writes the code, the page plays it, and you watch the code come alive.
-4. Claude can stop the music at any point. The page has its own Play and Stop button too.
-5. Right-click anything in the page to ask Claude about it. A right-click on the Timeline also
-   sends the moment under the pointer: the cycle and the beat, the version that was playing, and
-   the notes sounding there or starting in the same sixteenth, with their velocities and, for a
-   MIDI track, its instrument and channel. The Session drawer (the Session button in the top
-   bar) says whether page requests are live (they reach Claude right away) or wait for Claude
-   (they reach it with its next action). Its (i) explains how to switch.
-
-   The **Requests** button in the top bar counts the requests still in flight and opens a list:
-   one row per request, with what happened to it and how long ago. A request reads Sent, then
-   Waiting for Claude's next action or Received, then Claude has started on it, which means
-   Claude made a call after the request arrived. A change made for it reads Waiting for its
-   line while it waits for the next bar or phrase, then Applied as v12 (the version in the
-   History view); a change that failed reads Failed with the error, and one that a newer change
-   replaced or Stop canceled says so. A request Claude answers in words reads Answered or
-   Declined, with Claude's sentence. A request shows as applied only when Claude names it with
-   its change, never from timing alone. After 30 seconds without news a row reads No change yet
-   and keeps counting: that is not a failure. If the page loses its connection, open rows read
-   Connection lost. Click a row to see the whole request and what its
-   state means. Finished rows move to a short Recent list after 30 seconds. Nothing is kept
-   after the Moontide server stops.
-
 ## Install
 
-The short version, for someone who already has Node 22 or later and Claude Code:
-
-```bash
-claude mcp add --scope user moontide -- npx -y moontide-mcp
-```
-
-Then start a new Claude session and ask for music. The steps below explain each part.
-
-### 1. What you need
-
-- **Node 22 or later**, with npm and npx (they come with Node).
-- **Claude Code or Claude Desktop.** Moontide is an MCP server: Claude talks to it.
-- **Chrome**, the browser Moontide was tried with. For MIDI (Web MIDI), use Chrome or Edge.
-- **Internet access**: Strudel and its sounds load from the web.
-- **Speakers or headphones.**
-
-### 2. Check Node
-
-In a terminal, run:
-
-```bash
-node --version
-```
-
-It must print `v22` or higher. If Node is missing or older, install the LTS version from
-[nodejs.org](https://nodejs.org). On macOS with Homebrew, `brew install node` works too. Open a
-new terminal afterwards and check again.
-
-### 3. Get Claude
-
-Install Claude Code or Claude Desktop from [claude.com](https://claude.com/claude-code) and sign
-in once. Moontide works with either; Claude Code is the one tried most.
-
-### 4. Add Moontide to Claude
-
-<details open>
-<summary>Claude Code (tested on macOS; Linux untested)</summary>
-
-In a terminal, run:
+What you need: **Node 22 or later**, **Claude Code or Claude Desktop**, **Chrome** (Chrome or Edge
+for MIDI), internet access (Strudel and its sounds load from the web), and speakers or headphones.
 
 ```bash
 claude mcp add --scope user moontide -- npx -y moontide-mcp
 ```
 
-With `--scope user`, Moontide is available in every folder. The default scope (local) works
-only in the folder where you ran the command, and the scope `project` shares it through a
-`.mcp.json` file.
-
-Keep the name `moontide`. The page-request commands below use it.
-
-Check the install with:
-
-```bash
-claude mcp get moontide
-```
-
-The same line is meant for Linux. It is untested there.
-
-</details>
-
-<details>
-<summary>Claude Desktop (tested on macOS; Windows untested)</summary>
-
-Open Settings, then Developer, then Edit Config. The file is:
-
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-Add Moontide to it:
-
-```json
-{
-  "mcpServers": {
-    "moontide": {
-      "command": "npx",
-      "args": ["-y", "moontide-mcp"]
-    }
-  }
-}
-```
-
-If the file already has an `mcpServers` block, add the `moontide` entry inside it. Quit Claude
-Desktop fully and start it again. Claude Desktop has no Linux version.
-
-</details>
-
-<details>
-<summary>Windows with Claude Code (untested)</summary>
-
-From PowerShell or Command Prompt (not Git Bash), run:
-
-```bash
-claude mcp add --scope user moontide -- cmd /c npx -y moontide-mcp
-```
-
-Check it with `claude mcp get moontide`. The command must read `cmd` with `/c npx -y moontide-mcp`. If it shows `C:/` instead of `/c`, edit the `moontide` entry in the `.claude.json` file of your user folder so it reads `"command": "cmd", "args": ["/c", "npx", "-y", "moontide-mcp"]`.
-
-This form comes from community reports. It has not been tried here.
-
-</details>
+Then start a new Claude session and ask for music. Claude Desktop, Windows, running from the
+source code, updating and uninstalling are on the manual's
+[Install page](https://konni-arcadia.github.io/moontide/install.html).
 
-<details>
-<summary>From the source code</summary>
-
-To run Moontide from a copy of this repository instead of npm:
-
-```bash
-git clone https://github.com/konni-arcadia/moontide.git
-cd moontide
-npm ci
-npm run build
-```
-
-Then add it with the full path of `dist/index.js`, written here as `<folder>`:
-
-```bash
-claude mcp add --scope user moontide -- node <folder>/dist/index.js
-```
-
-`npm test` runs the test suite. The real-browser checks (`npm run probe:page`) need Chrome.
-
-</details>
-
-### 5. First music
+## First music
 
 1. Start a new Claude session. Nothing opens yet: Moontide waits until you want it.
-2. Ask for music, for example "Play something calm to start the day" or "Give me a slow, warm
-   groove". Or say "start Moontide". In Claude Code, `/mcp__moontide__start` does the same.
+2. Ask for music, for example "Play something calm to start the day". Or say "start Moontide".
 3. The page opens in a new tab at http://localhost:5757, or on another port when 5757 is busy.
-   Claude's replies name the address. The tab title names the folder Claude runs in and the
-   port, for example "Moontide · my-project · 5757".
 4. Click once anywhere in the page. Browsers start sound only after a click.
 5. Ask for changes: "darker", "add a bass", "slower".
 
-Set `MOONTIDE_NO_BROWSER=1` in the environment and starting Moontide opens no tab. Open the
-address from Claude's reply yourself.
-
-### Update
-
-To see the version that runs, run `npx -y moontide-mcp --version`. Releases are listed in
-[CHANGELOG.md](https://github.com/konni-arcadia/moontide/blob/main/CHANGELOG.md). npx can keep
-using a copy it already downloaded; to move to the newest release, add Moontide again with
-`@latest`:
-
-```bash
-claude mcp remove moontide --scope user
-claude mcp add --scope user moontide -- npx -y moontide-mcp@latest
-```
-
-### Uninstall
-
-```bash
-claude mcp remove moontide --scope user
-```
-
-In Claude Desktop, remove the `moontide` entry from the config file and restart it. Moontide
-keeps its history and settings in your data folder (see History); delete that folder if you
-want them gone too.
-
-### MIDI instruments (optional)
-
-Moontide can play MIDI instruments from the code through Web MIDI. It ships ready models for the
-Roland MT-32 and SC-55. You can describe your own instruments and models, add sound catalogs and
-send MIDI clock. The setup is in
-[docs/midi.md](https://github.com/konni-arcadia/moontide/blob/main/docs/midi.md).
-
-## Page requests without a permission prompt
-
-In the Code tab of the Claude app, ask Claude to turn page requests on or off. Claude calls
-Moontide's `set_page_requests` tool. In Claude Code in a terminal, type
-`/mcp__moontide__page-requests-on` to make them live or `/mcp__moontide__page-requests-off` to
-make them wait. Live, Claude starts a monitor, which lasts at most 30 minutes and is started
-again when a tool reply asks. Waiting, tool replies stop offering to start it until page
-requests are turned on again. Page requests need an open page, so start Moontide first. These
-names assume the server was added as `moontide`.
-
-Claude Code asks permission before it starts the monitor for page requests, because it runs a
-command. You can approve it each time. If you want a narrower permission rule instead, see the
-permissions section of the Claude Code documentation. Do not allow broad `node` commands.
-
-## Musical reference
-
-Claude gets a factual reference of the exact Strudel version the page runs, through the
-`get_strudel_reference` tool (also offered as MCP resources), covering nine topics: Strudel
-vs TidalCycles, mini-notation, pattern functions, effects and sound controls, the sound
-palette, music theory in Strudel, transitions, song structure, and MIDI output. It holds facts only: what
-exists and how to write it. Moontide ships no mood vocabulary, no style material and no model
-pieces; Claude translates your words with its own knowledge of music theory, then tells you in
-one line what it chose. Ask for a surprise in your own words: there is no menu command for it.
-Set a frame for the session, for example gradual changes, and Claude follows it for every
-change until you lift it. Say what matters to you (a melody, a rhythm) and Claude keeps it,
-and asks before a full rewrite.
-
-## Small edits and harmony
-
-Claude can change a few lines of a long piece without sending it again, through the
-`edit_code` tool; a change that waits for its bar is edited, and your hand edits are kept.
-
-The code can say which harmony it means with one top-level line, for example
-`const harmony = 'C:minor'`, placed above the patterns. It plays nothing and is never a
-track. The Jam view then shows two lines, "Declared:" and "Heard:", side by side.
-
-When the notes fit several scales, the Jam view proposes one and says why in a sentence, for
-example "Proposed: C major, C is the note heard most." It takes the declared scale of the playing
-section when that scale is among the ones that fit, and otherwise the scale the notes support
-most. Warnings stay on. "Scales that fit, click to switch:" lists them, and one click or Enter
-switches the whole view. Your pick holds while the same scales fit, and is forgotten on reload.
-When the scales differ in their notes and the code declares none of them, warnings are off: the
-view says why and lists the scales without a switch. The piano is coloured like the guitar, with
-the same legend, and every role also has a shape or text cue, so it reads without colour.
-
-## Song structure
-
-Every new piece Claude writes starts with one `const song` at the top. It names the sections
-with their lengths in cycles, says which version (variation) of each track plays in each section
-or that the track rests, and may put tracks into groups. It is still ordinary Strudel, and the
-same code plays in plain Strudel. A small request on an older piece is made in place and does not
-restructure it. A piece without a song plays and looks as before.
-
-For a piece with a song, the Parts view is called **Song**. The Song grid shows the tracks under
-foldable groups, with one column per section and the playing section marked.
-
-- Click a section header to launch that section on the next line the toolbar names: the end of
-  the playing section, the next phrase or the next bar. Click again to cancel.
-- Click a cell to pick another variation for that track and section, or a rest. It takes over
-  with your usual hand-edit timing.
-- A fixed variation says whether its notes fit the section's harmony: fits, does not fit, or
-  cannot check. It only says; it never blocks.
-- Play after Stop starts from the first section. The Jam view's Declared line follows the
-  playing section.
+More in [First music](https://konni-arcadia.github.io/moontide/first-music.html).
 
-The **Mixer** draws the groups as frames that fold together with the grid. One click on a
-group's M or S mutes or solos every track below it, as one change. There is no group fader,
-because plain Strudel has no gain for a group. A small light on each strip and each group blinks
-when its note is heard. With motion off in the Session drawer, a light stays lit while notes come.
+## The manual
 
-On the **Timeline**, click a note to select it. Drag it up or down, or press the Up and Down
-keys, to change its pitch by semitones. Delete, Backspace or "Make a rest" turns it into a rest.
-Two buttons change its velocity by a tenth. The page checks an edit before it writes it, says
-first when one edit changes the note in several places, and uses your hand-edit timing. A note
-the page cannot edit says why. Your gesture then opens the Ask box with a ready-made request,
-and it goes to Claude only when you press Enter. Drag across one lane, or hold Shift and press
-Left or Right, to select a range of whole cycles, and use "Ask Claude" to send it.
+The manual is at [https://konni-arcadia.github.io/moontide/](https://konni-arcadia.github.io/moontide/). It is written in plain words,
+and every page ends with a box that says what was checked and what was not.
 
-A right-click on a section, a track, a cell or a group asks Claude about that thing.
+- Getting started: [Install](https://konni-arcadia.github.io/moontide/install.html),
+  [First music](https://konni-arcadia.github.io/moontide/first-music.html) and
+  [the page and its views](https://konni-arcadia.github.io/moontide/the-page.html).
+- Working with Claude: [asking Claude](https://konni-arcadia.github.io/moontide/asking-claude.html),
+  requests from the page, small edits, song structure, tempo ramps and history.
+- MIDI gear: [instruments and the setup file](https://konni-arcadia.github.io/moontide/midi-instruments.html),
+  [sounds and catalogs](https://konni-arcadia.github.io/moontide/midi-sounds.html),
+  [tone, part and scene settings](https://konni-arcadia.github.io/moontide/synth-settings.html),
+  [the Scratchpad](https://konni-arcadia.github.io/moontide/scratchpad.html),
+  [keyboard input](https://konni-arcadia.github.io/moontide/keyboard-input.html) and
+  [sending a motif](https://konni-arcadia.github.io/moontide/sending-a-motif.html).
+- Troubleshooting: [problems and known limits](https://konni-arcadia.github.io/moontide/troubleshooting.html).
+- How it works: [the pieces and the tools](https://konni-arcadia.github.io/moontide/how-it-works.html),
+  what was measured, and
+  [network, privacy, credits and license](https://konni-arcadia.github.io/moontide/privacy-and-credits.html).
 
-## Tempo ramp
-
-Ask Claude to speed up or slow down over a number of bars, for example "bring it up to 140 over
-eight bars". Claude sends the new code with the tempo to reach and `glideBars`, a whole number
-of bars from 1 to 64, on `set_code` or `edit_code`. The tempo then moves from the tempo that
-plays to the one in the code in equal small steps, and ends exactly on it. It starts at once, or
-at the line when the change waits for the next bar or phrase.
-
-While it runs, the tempo in the top bar shows the live tempo, an arrow and the tempo to reach.
-Hover it to see how many bars are left.
-
-Your Mixer moves, Song grid cells, Timeline edits and hand edits keep the ramp going. Code with
-another tempo cancels it, and that tempo plays at once. Code with no tempo cancels it, and the
-tempo stays where it was. A new `glideBars` replaces it. Stop cancels it too, and the next Play
-starts at the code's tempo. A reload, or another tab taking over, ends it. There is no cancel
-button of its own.
-
-A ramp is refused, and nothing changes, when nothing plays, when the code sets no tempo, or when
-it sets the tempo that already plays. A ramp is never a version: it writes nothing into the code
-or the history.
-
-The MIDI clock follows every step of a ramp. How hardware that follows the clock, such as an
-arpeggiator or a step sequencer, reacts to a ramp has not been verified.
-
-## History
-
-Every version that plays is kept: Claude's own changes and your Ctrl+Enter edits, each with
-its time, who made it and a short label. Failed code and stops are not versions.
-
-Ask Claude things like "go back to the previous version", "the one from 3 changes ago", "the
-one with the bass", or "keep this one, call it Take two", and "list my favorites". The
-Session drawer shows the number of the version that is playing, in its Last change card, for
-example `v42`.
-
-The history file lives in your OS's per-user data folder:
-
-- macOS: `~/Library/Application Support/moontide/history.jsonl`
-- Linux: `$XDG_DATA_HOME/moontide/history.jsonl`, or `~/.local/share/moontide/history.jsonl`
-- Windows: `%APPDATA%\moontide\history.jsonl`
-
-Set `MOONTIDE_DATA_DIR` to use another folder. The history is one text file with one entry
-per line, and survives the end of the Claude session.
-
-The history keeps the last 1000 versions; older ones are dropped in batches and Claude is
-told. Favorites are never dropped.
-
-If a line of the file cannot be read, Claude is told which lines; they stay in the file
-untouched. If the file cannot be read or written at all, the music keeps working and Claude
-is told.
-
-Run one Moontide at a time with the same history file. Two at once can give two versions the
-same number.
-
-## Troubleshooting
-
-**"Failed to connect" right after installing.** The first start downloads the package, and Claude Code gives up after 30 seconds. Wait a little and check again with `claude mcp list`. If it keeps failing, start Claude Code with a longer limit: `MCP_TIMEOUT=60000 claude`. In PowerShell, use `$env:MCP_TIMEOUT = "60000"; claude`.
-
-**Moontide is missing in another folder.** It was added without `--scope user`. Add it again with the Install line.
-
-**The page did not open.** Claude's replies name its address. Open it yourself, or ask Claude to start Moontide again: it gives the address and opens a new tab when no page is connected.
-
-**Several Moontide tabs.** Each Claude session that started Moontide has its own page and port. The tab title says "Moontide · <folder> · <port>", with the folder that session runs in, and the Session drawer shows the same. Ask Claude which tab is its own: it answers with the address, the port and the tab title.
-
-**No sound.** Click once in the page. Check that the browser tab is not muted, and keep the page open.
-
-**Claude Desktop does not find `npx`.** Put the full path in `"command"`: the path printed by `which npx` on macOS or `where npx` on Windows, written here as `<full path printed by which npx>`. This is common advice and has not been tried here. The Claude Desktop logs are in `~/Library/Logs/Claude` on macOS and `%APPDATA%\Claude\logs` on Windows.
-
-**MIDI says to use Chrome or Edge.** Web MIDI is missing in that browser.
+The same pages can be read on GitHub, as Markdown, in the
+[site folder](https://github.com/konni-arcadia/moontide/tree/main/site).
 
 ## Status
 
@@ -410,27 +98,15 @@ Early and personal. It runs on one setup: a Mac, Chrome, Claude Code and Claude
 for MIDI, a Roland SC-55, the Munt MT-32 emulator and a Roland JUPITER-Xm. It has not been tried
 anywhere else. The test suite runs on Windows, Linux and macOS in CI, but nobody has played
 music on Windows or Linux yet. There are known bugs. Feedback is welcome, but support is not
-something I can promise.
-
-Known limits:
-
-- Tried by hand only on macOS, with Chrome, Claude Code and Claude Desktop.
-- Windows and Linux are untested by hand. Edge, Safari and Firefox are untested.
-- Internet access is needed.
-- MIDI needs Chrome or Edge.
-- How hardware that follows Moontide's MIDI clock, such as an arpeggiator or a step sequencer,
-  reacts to a tempo ramp has not been verified.
-- Run one Moontide at a time with the same history file.
-- The first start through npx downloads the package and can be slow.
+something I can promise. The list is in
+[Known limits](https://konni-arcadia.github.io/moontide/troubleshooting.html#known-limits).
+What is not yet checked by hand is listed at the end of each manual page and in the
+[changelog](https://github.com/konni-arcadia/moontide/blob/main/CHANGELOG.md).
 
 ## Network and privacy
 
-- The server listens on 127.0.0.1 only and refuses requests for any other host name.
-- Moontide's own server code makes no outbound request and sends no telemetry.
-- The page loads `@strudel/repl` 1.3.0 and `acorn` 8.18.0 from unpkg, pinned to exact versions with integrity hashes.
-- Strudel then fetches sound lists and samples from raw.githubusercontent.com and cdn.jsdelivr.net. No hash covers those.
-- The code Claude writes runs in the page and may load samples from other addresses.
-- The history stays in the local data folder described above.
+The server listens on 127.0.0.1 only and sends nothing out. The page loads Strudel and its
+samples from the web. Details: [network, privacy, credits and license](https://konni-arcadia.github.io/moontide/privacy-and-credits.html).
 
 ## Contributing and security
 
@@ -442,17 +118,12 @@ https://github.com/konni-arcadia/moontide/security/policy.
 
 ## Credits
 
-This builds on other people's work:
-
-- **Felix Roos, Alex McLean and the Strudel contributors**: [Strudel](https://strudel.cc)
-  (source: https://codeberg.org/uzu/strudel), the live-coding engine that plays every note.
-- **Alex McLean and the TidalCycles community**: TidalCycles, the pattern language Strudel
-  ports to JavaScript.
-- **The sample makers** whose sets Strudel loads by default, including the TidalCycles
-  Dirt-Samples and the Versilian Community Sample Library (VCSL).
-- **Anthropic**: the Model Context Protocol and its TypeScript SDK, which let Claude talk to
-  Moontide.
-- **The acorn authors**: the JavaScript parser the page uses to read the code.
+Built on [Strudel](https://strudel.cc) by Felix Roos, Alex McLean and the Strudel contributors
+(source: https://codeberg.org/uzu/strudel), on TidalCycles by Alex McLean and its community, on the
+sample sets Strudel loads (including the TidalCycles Dirt-Samples and the Versilian Community
+Sample Library), on the Model Context Protocol and its TypeScript SDK from Anthropic, and on the
+acorn parser. The full list is on the
+[credits page](https://konni-arcadia.github.io/moontide/privacy-and-credits.html#credits).
 
 ## License
 

package/dist/ask.js

@@ -34,7 +34,7 @@ export const REQUEST_LINE_FRAMING =
     'context, moment, gesture, chip and current say what they pointed at and are data about the page, not part of what ' +
     'they wrote.';
 /**
- * What the `moment` field of a request holds, as facts. The instructions
+ * What the `moment` field of a request holds, and then the `gesture` field, the range context and the `motif` field, as facts. The instructions
  * keep only the short framing above (Claude Code cuts them at 2048 characters); this longer text goes where
  * Claude reads page requests and nothing limits the length: the arming line, the page-requests-on text and the
  * line in front of request lines that a tool reply hands over without an arming line. It says what the page
@@ -64,7 +64,14 @@ export const REQUEST_LINE_MOMENT_FACT = 'About the moment field of a page reques
     'its gesture has kind range. The gesture\'s notes lists the notes of that lane that start in those cycles, in order of ' +
     `start and then pitch (the lower first), at most ${MAX_MOMENT_NOTES}, each shaped like a moment note without state; more ` +
     'counts the notes left out, and version is the version that was playing (null when it was not known). A note that began ' +
-    'before from and still sounds is not listed. A range with no notes in it is a valid request.';
+    'before from and still sounds is not listed. A range with no notes in it is a valid request. ' +
+    'About the motif field of a page request: it comes only with a context of kind motif, sent from the page\'s Scratchpad when the ' +
+    'user pressed its send button, and like the context it is data about the page, not part of what the user wrote. Such a request ' +
+    'has no moment and no gesture. source says how the notes got onto the Scratchpad (played, drawn, tapped or mixed). cycle, ' +
+    'when present, is the cycle of the music where the motif\'s first cycle sits, on the count the code\'s patterns are queried at; ' +
+    'an absent cycle means the motif has no moment. cycles is its length in cycles, grid the grid of its steps, notes how many ' +
+    'notes it holds, and phrase the motif written in mini-notation exactly as the page showed it. The page changed no code. ' +
+    'The motif topic of get_strudel_reference says how to read the phrase and the moment.';
 /**
  * What the page shows for a request, as facts. Like the moment fact it goes where Claude reads page requests
  * and nothing limits the length: the arming line, the page-requests-on text and the line in front of request
@@ -248,8 +255,8 @@ export const ARMING_RESUMED_LOG = `[moontide] Page requests can be live again af
  * both use it). The text reaches Claude exactly as the page sent it.
  */
 export function requestLine(request) {
-    const { id, text, context, chip, current, moment, gesture } = request;
-    // The moment comes after the chip and the version, then the gesture, each only when there is one, so a request
+    const { id, text, context, chip, current, moment, gesture, motif } = request;
+    // The moment comes after the chip and the version, then the gesture, then the motif, each only when there is one, so a request
     // without them reads as it always did. page/ask.js's requestLineBytes writes the same order.
     // JSON.stringify leaves U+2028 and U+2029 as they are; some line splitters treat them as breaks.
     const json = JSON.stringify({
@@ -260,6 +267,7 @@ export function requestLine(request) {
         current,
         ...(moment === undefined ? {} : { moment }),
         ...(gesture === undefined ? {} : { gesture }),
+        ...(motif === undefined ? {} : { motif }),
     })
         .replaceAll('\u2028', '\\u2028')
         .replaceAll('\u2029', '\\u2029');