tutticode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,56 @@
+MIT License
+
+Copyright (c) 2026 TuttiDAW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Notices
+
+- This package is a local client. Sound is rendered by the TuttiCode engine on
+  https://tuttidaw.com, loaded in your own browser; its use is governed by the
+  TuttiDAW terms of use (https://tuttidaw.com/page/terms-of-use). You own the audio you render.
+- The skills and references in dist/skills are TuttiDAW documentation,
+  included for use with your AI agents.
+- TuttiCode is a superset of the Strudel pattern language; this package
+  contains no Strudel code.
+
+Third-party software bundled in dist/tutticode.cjs:
+
+ws (https://github.com/websockets/ws), MIT License
+Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
+Copyright (c) 2013 Arnout Kazemier and contributors
+Copyright (c) 2016 Luigi Pinca and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# tutticode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文说明](README.zh-CN.md)
+
+Turn **TuttiCode** - the [tuttidaw.com/code](https://tuttidaw.com/code)
+pattern language, a superset of Strudel - into audio files from any agent or
+script. A CLI and an MCP server for Claude Code, Copilot CLI, Codex, Cursor,
+Claude Desktop and friends.
+
+Rendering happens **in your own browser**, on the same engine as
+tuttidaw.com/code, so a file sounds exactly like the editor. Nothing is
+rendered on a server, there is no account, and it costs nothing. Every result
+carries an `editUrl` that opens the program in TuttiDAW to keep editing.
+
+## Install
+
+```sh
+npm i -g tutticode          # or: npx tutticode ...
+tutticode skills install    # skills for Claude Code / Copilot / Codex
+claude mcp add tutticode -- tutticode mcp   # MCP clients
+tutticode doctor            # check that everything is in place
+```
+
+Needs Node 20+ and Google Chrome or Microsoft Edge (Chromium works too).
+
+Guide: [TuttiCode for agents](https://tuttidaw.com/code/learn/for-agents)
+(install, the two backends, privacy, the browser permission,
+troubleshooting).
+
+## Skills
+
+`tutticode skills install` installs two skills (also readable online):
+
+- [`tutticode`](https://tuttidaw.com/skills/tutticode/SKILL.md) - the
+  language: syntax, top mistakes, the `code_check` / `code_render` /
+  `code_compare` loop on both backends (this package, or TuttiDAW's web
+  MCP), and references for every function, sound and device.
+- [`tutticode-sound-for-media`](https://tuttidaw.com/skills/tutticode-sound-for-media/SKILL.md)
+  - music beds, loops, stems and sound effects for videos, apps and games:
+  brief -> recipe -> check -> render at an exact length and a platform
+  loudness (-14 LUFS web/social, -16 podcasts, -23 broadcast) -> read the
+  stats -> revise, with tested recipes (riser, impact, whoosh, UI click /
+  confirm / error, notification, transition, ambience bed, music beds).
+
+Claude Code, Copilot CLI and Codex read them from `~/.claude/skills`,
+`~/.copilot/skills` and `~/.codex/skills`; `--dir <path>` installs them
+anywhere else (for example a project's `.claude/skills`).
+
+## Use
+
+```sh
+tutticode check song.tc                     # diagnostics, no audio
+tutticode render song.tc -o bed.wav --seconds 12 --fade-out 1.5 --lufs -16 --json
+tutticode render song.tc -o loop.flac --loops 4 --stems stems/
+tutticode open song.tc                      # open it in TuttiCode for a human
+cat song.tc | tutticode check -             # read the program from stdin
+```
+
+`render` flags: `--seconds|--bars|--loops N`, `--bpm N`,
+`--format wav|flac|mp3` (default from the `-o` extension),
+`--sample-rate 44100|48000`, `--bit-depth 16|24`, `--stems <dir>`,
+`--fade-in s`, `--fade-out s`, `--tail s`, `--lufs N`, `--true-peak N`,
+`--json`, `--timeout s`. `--lufs` applies one static gain; when the true-peak
+ceiling cannot be met the render fails with `clip` instead of being limited.
+
+`--json` prints the render report: length, bars, tempo, loudness and true
+peak, the gain applied, per-voice levels, the bar and beat grid (seconds, for
+syncing cuts), the check report, the analysis, the `editUrl` and the written
+files. Audio is never printed.
+
+Exit codes: `0` ok, `1` errors in the code (or a loudness target that would
+clip), `2` bridge or browser problem, `3` usage.
+
+### MCP tools
+
+`tutticode mcp` serves the same tools as TuttiDAW's web agent loop, so one
+skill teaches both:
+
+| tool | what it does |
+| --- | --- |
+| `code_check` | compile and plan, no audio: diagnostics, voices, mix warnings |
+| `code_render` | render to a file (`out`), returns paths + statistics + `editUrl` |
+| `code_compare` | compare a render with goals (or a Muse style), or two renders |
+| `code_open` | open a program in a visible TuttiCode tab (`tutticode mcp --headless`: no window, returns the link) |
+| `code_reference` | search the TuttiCode reference shipped in the package |
+
+The reference documents are also MCP resources (`tutticode://skills/...`).
+
+## How it works
+
+```
+agent --CLI/MCP--> tutticode (Node) --WebSocket 127.0.0.1--> tuttidaw.com/code/bridge (your browser)
+```
+
+1. The first call starts a local server on `127.0.0.1` with a random port
+   and a fresh 128-bit token, and opens
+   `https://tuttidaw.com/<locale>/code/bridge#p=<port>&t=<token>`. The port and
+   token sit in the URL fragment, which browsers never send to the server.
+2. The page connects back, renders with the TuttiCode engine and streams the
+   audio to tutticode, which writes your files.
+3. The bridge stays warm for 10 minutes, so later calls skip the startup.
+
+By default (MCP and non-interactive calls) tutticode starts a **headless**
+Chrome or Edge from your install with its own profile in
+`~/.tutticode/browser-profile` and grants that profile the Local Network
+Access permission for tuttidaw.com. That profile is yours (you installed
+tutticode), so tutticode also gives the bridge page's one-time consent
+("Allow this agent to render sound with TuttiCode") in it, for tuttidaw.com
+only. `--show` uses a visible tab in your default browser instead (the
+default when you type a command in a terminal); there tutticode grants
+nothing: the first time, the page asks for your consent and the browser asks
+whether tuttidaw.com may access devices on your local network - allow both,
+or run `tutticode setup` for the second.
+
+Security: the server listens on 127.0.0.1 only, accepts one page at a time,
+only from `https://tuttidaw.com` (or an origin you pass with `--origin` /
+`--dev-origin`), only with the session token, and checks the Host header.
+The CLI talks to its background bridge over a second token in
+`~/.tutticode`, which web pages cannot reach. The headless browser is driven
+over a private pipe (`--remote-debugging-pipe`), never a DevTools TCP port
+other programs could connect to. Everything the page sends back is checked
+before it touches your disk: the format, the numbers and the stem names are
+validated, stem files are named from a safe character set and only ever
+written inside the stems folder, and never through a symbolic link.
+
+## Commands
+
+- `tutticode doctor` - Node, the browser, the page, the connection and the
+  engine version.
+- `tutticode setup` - explains, asks, and then sets the browser policy
+  `LocalNetworkAccessAllowedForUrls = ["https://tuttidaw.com"]` for your
+  user (Windows: HKCU registry; macOS: `defaults`; Linux: a managed policy
+  file, needs sudo) so `--show` needs no click. `tutticode setup --undo`
+  removes exactly that entry. Also installs the skills (`--no-skills` to
+  skip).
+- `tutticode skills install [--claude] [--copilot] [--codex] [--dir <path>]`
+  - copies both skills (`tutticode`, `tutticode-sound-for-media`) into `~/.claude/skills`, `~/.copilot/skills`,
+  `~/.codex/skills` (default: every agent folder that exists).
+
+Bridge flags for every command: `--show` / `--headless`,
+`--browser chrome|edge|<path>`, `--origin <url>` (staging / local dev),
+`--dev-origin <url>`, `--locale <locale>`, `--no-daemon`, `--verbose`.
+Environment: `TUTTICODE_BROWSER` (browser path), `TUTTICODE_HOME` (state
+folder), `TUTTICODE_BROWSER_ARGS` (extra browser flags).
+
+## Privacy
+
+tutticode sends no telemetry. Your program goes only to the TuttiCode page
+in your own browser. Logs stay in `~/.tutticode/logs` and never contain your
+program or audio.
+
+## Browsers
+
+Chrome and Edge (desktop) are supported. Firefox and Safari may work with
+`--show` but are not tested.
+
+## License
+
+MIT for this package; see [LICENSE](LICENSE). Rendering uses the TuttiCode
+engine on tuttidaw.com under the TuttiDAW terms of use.

package/README.zh-CN.md

@@ -0,0 +1,138 @@
+# tutticode
+
+[English](README.md)
+
+把 **TuttiCode**([tuttidaw.com/code](https://tuttidaw.com/code) 的 pattern 语言,
+Strudel 的超集)变成音频文件,任何 agent 或脚本都能用。它是一个 CLI,也是一个
+MCP server,适用于 Claude Code、Copilot CLI、Codex、Cursor、Claude Desktop 等。
+
+渲染**在你自己的浏览器里**进行,用的就是 tuttidaw.com/code 的同一个引擎,所以
+文件和编辑器里听到的一模一样。不经过服务器渲染,不需要账号,也不收费。每个结果
+都带一个 `editUrl`,可以在 TuttiDAW 里打开这段程序继续编辑。
+
+## 安装
+
+```sh
+npm i -g tutticode          # 或者: npx tutticode ...
+tutticode skills install    # 给 Claude Code / Copilot / Codex 装 skill
+claude mcp add tutticode -- tutticode mcp   # MCP 客户端
+tutticode doctor            # 检查环境是否就绪
+```
+
+需要 Node 20+,以及 Google Chrome 或 Microsoft Edge(Chromium 也可以)。
+
+使用指南:[给 agent 用的 TuttiCode](https://tuttidaw.com/zh-CN/code/learn/for-agents)
+(安装、两个后端、隐私、浏览器权限、常见问题)。
+
+## Skill
+
+`tutticode skills install` 会安装两个 skill(也可以在线阅读):
+
+- [`tutticode`](https://tuttidaw.com/skills/tutticode/SKILL.md) —— 语言本身:
+  语法、常见错误、在两个后端(本包,或 TuttiDAW 网页版 MCP)上的
+  `code_check` / `code_render` / `code_compare` 循环,以及每个函数、音色和设备的参考。
+- [`tutticode-sound-for-media`](https://tuttidaw.com/skills/tutticode-sound-for-media/SKILL.md)
+  —— 为视频、应用和游戏做配乐、循环、分轨和音效:需求 -> 配方 -> 检查 -> 按精确时长和
+  平台响度渲染(网页/社交 -14 LUFS、播客 -16、广播 -23)-> 读数据 -> 修改;配方都经过测试
+  (riser、impact、whoosh、UI 点击/确认/错误、通知、转场、环境音床、配乐)。
+
+Claude Code、Copilot CLI 和 Codex 分别从 `~/.claude/skills`、`~/.copilot/skills`、
+`~/.codex/skills` 读取;`--dir <路径>` 可以装到其他任何地方(比如项目里的 `.claude/skills`)。
+
+## 用法
+
+```sh
+tutticode check song.tc                     # 只检查,不出声音
+tutticode render song.tc -o bed.wav --seconds 12 --fade-out 1.5 --lufs -16 --json
+tutticode render song.tc -o loop.flac --loops 4 --stems stems/
+tutticode open song.tc                      # 在 TuttiCode 里打开给人看
+cat song.tc | tutticode check -             # 从 stdin 读程序
+```
+
+`render` 参数: `--seconds|--bars|--loops N`、`--bpm N`、
+`--format wav|flac|mp3`(默认按 `-o` 的扩展名)、`--sample-rate 44100|48000`、
+`--bit-depth 16|24`、`--stems <目录>`、`--fade-in 秒`、`--fade-out 秒`、
+`--tail 秒`、`--lufs N`、`--true-peak N`、`--json`、`--timeout 秒`。
+`--lufs` 只做一次静态增益;如果达不到 true peak 上限,会以 `clip` 失败,而不是
+偷偷加限制器。
+
+`--json` 输出渲染报告:时长、小节数、速度、响度和 true peak、施加的增益、每个
+声部的电平、小节和拍的时间点(秒,用来对齐剪辑点)、检查报告、分析结果、
+`editUrl` 和写出的文件路径。永远不会把音频打印到终端。
+
+退出码: `0` 成功, `1` 代码有错(或响度目标会削波), `2` bridge / 浏览器问题,
+`3` 用法错误。
+
+### MCP 工具
+
+`tutticode mcp` 提供和 TuttiDAW 网页版 agent loop 相同的工具,一份 skill 两边通用:
+
+| 工具 | 作用 |
+| --- | --- |
+| `code_check` | 编译并规划,不出声音:诊断、声部、混音提醒 |
+| `code_render` | 渲染到文件(`out`),返回路径 + 统计 + `editUrl` |
+| `code_compare` | 把一次渲染和目标(或 Muse 风格)比较,或比较两次渲染 |
+| `code_open` | 在可见的 TuttiCode 标签页里打开程序（`tutticode mcp --headless` 时不开窗口，只返回链接） |
+| `code_reference` | 搜索包里自带的 TuttiCode 参考文档 |
+
+参考文档同时作为 MCP resources 提供(`tutticode://skills/...`)。
+
+## 工作原理
+
+```
+agent --CLI/MCP--> tutticode (Node) --WebSocket 127.0.0.1--> tuttidaw.com/code/bridge (你的浏览器)
+```
+
+1. 第一次调用时,在 `127.0.0.1` 的随机端口上启动本地服务,生成新的 128 位
+   token,然后打开 `https://tuttidaw.com/<locale>/code/bridge#p=<端口>&t=<token>`。
+   端口和 token 放在 URL 的 fragment(`#` 后面),浏览器不会把它发给服务器。
+2. 页面连回本地服务,用 TuttiCode 引擎渲染,把音频传回 tutticode,由它写文件。
+3. bridge 会保持 10 分钟,后续调用不用重新启动。
+
+默认情况下(MCP 和非交互调用),tutticode 会用你已安装的 Chrome 或 Edge 启动一个
+**无头(headless)**浏览器,使用独立的配置目录 `~/.tutticode/browser-profile`,并
+给这个配置授予 tuttidaw.com 的"本地网络访问"权限。这个配置是你自己的(tutticode 是
+你装的),所以 tutticode 也会在其中代你给出 bridge 页面的一次性同意("允许这个 agent
+用 TuttiCode 渲染声音"),只对 tuttidaw.com 生效。`--show` 改为在默认浏览器里打开
+可见标签页(在终端里手动敲命令时默认如此),这时 tutticode 不代授任何东西:第一次
+页面会请你同意,浏览器也会询问是否允许 tuttidaw.com 访问本地网络上的设备 —— 两者都
+选允许,后者也可以运行 `tutticode setup` 免去。
+
+安全:服务只监听 127.0.0.1,同一时间只接受一个页面,只接受来自
+`https://tuttidaw.com`(或你用 `--origin` / `--dev-origin` 指定的来源)且带有本次
+token 的连接,并检查 Host 头。CLI 和后台 bridge 之间用 `~/.tutticode` 里的另一个
+token 通信,网页无法访问。无头浏览器通过私有管道(`--remote-debugging-pipe`)控制,
+从不开放其他程序能连上的 DevTools TCP 端口。页面传回的一切在写盘前都要校验:格式、
+数值和分轨名都会检查,分轨文件名只用安全字符,只写进分轨文件夹,也绝不经由符号链接写入。
+
+## 命令
+
+- `tutticode doctor` —— 检查 Node、浏览器、页面、连接和引擎版本。
+- `tutticode setup` —— 先说明、再询问,同意后为当前用户设置浏览器策略
+  `LocalNetworkAccessAllowedForUrls = ["https://tuttidaw.com"]`
+  (Windows:HKCU 注册表;macOS:`defaults`;Linux:托管策略文件,需要 sudo),
+  这样 `--show` 不再需要点击确认。`tutticode setup --undo` 只删除这一条。
+  同时安装 skill(`--no-skills` 跳过)。
+- `tutticode skills install [--claude] [--copilot] [--codex] [--dir <路径>]`
+  —— 把两个 skill(`tutticode`、`tutticode-sound-for-media`)复制到 `~/.claude/skills`、`~/.copilot/skills`、
+  `~/.codex/skills`(默认:所有已存在的 agent 目录)。
+
+所有命令通用的 bridge 参数:`--show` / `--headless`、
+`--browser chrome|edge|<路径>`、`--origin <url>`(预发 / 本地开发)、
+`--dev-origin <url>`、`--locale <语言>`、`--no-daemon`、`--verbose`。
+环境变量:`TUTTICODE_BROWSER`(浏览器路径)、`TUTTICODE_HOME`(状态目录)、
+`TUTTICODE_BROWSER_ARGS`(额外的浏览器参数)。
+
+## 隐私
+
+tutticode 不发送任何遥测数据。你的程序只会交给你自己浏览器里的 TuttiCode 页面。
+日志保存在 `~/.tutticode/logs`,不包含程序内容和音频。
+
+## 浏览器
+
+支持桌面版 Chrome 和 Edge。Firefox 和 Safari 用 `--show` 可能可以用,但未测试。
+
+## 许可
+
+本包采用 MIT 许可,见 [LICENSE](LICENSE)。渲染使用 tuttidaw.com 上的 TuttiCode
+引擎,遵循 TuttiDAW 使用条款。

package/dist/skills/tutticode/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: tutticode
+description: Write, fix, check and render TuttiCode (TuttiDAW Code): Strudel-compatible live-coding pattern programs (mini-notation, note/s/n, scales, chords, effects, samples) that play on TuttiDAW instruments and effects, plus TuttiCode-only .inst/.fx/.midifx devices. Covers the code_check / code_render / code_compare tools of the local tutticode CLI/MCP and the TuttiDAW web MCP. Use when asked for Strudel, TuttiCode or TuttiDAW code, a beat/melody/loop as code, a tuttidaw.com/code link, a Pattern Clip, rendering code to audio, or when a pattern program errors.
+---
+
+# TuttiCode
+
+TuttiCode (TuttiDAW Code) is a pattern language for music: a superset of
+Strudel (strudel.cc) that plays on TuttiDAW's instruments and effects. A
+program is JavaScript built from pattern functions; double-quoted strings are
+mini-notation. It loops: one cycle = one bar.
+
+## Core syntax
+
+```js
+setcpm(30)                                   // cycles (bars) per minute: 30 = 120 BPM in 4/4
+drums: s("bd [~ bd] sd ~, hh*8").bank("tr909") // a labelled voice = one track
+bass: note("c2 [~ c2] eb2 g1").s("sawtooth").lpf(800)
+chords: chord("<Cm7 Ab^7 Fm7 G7>").voicing().inst("Electric").fx("Reverb:Large Hall")
+_lead: n("0 2 4 7").scale("C:minor")         // a leading _ mutes a voice
+```
+
+- Mini-notation: `a b c` steps share a cycle; `~` rest; `[a b]` one step;
+  `<a b>` one per cycle; `a,b` together; `*n` `/n` faster/slower; `@n`
+  longer; `!n` repeat; `x(3,8)` Euclidean; `?` maybe; `a|b` random choice;
+  `{a b c, d e}` polymeter; `bd:3` variant.
+- Pitches: `note("c4")` = MIDI 60; no octave = octave 3. `n("0 2 4").scale("C:minor")`
+  plays scale degrees (root in octave 3). `chord("Am7").voicing()` voices
+  chord symbols.
+- Time: `.fast` `.slow` `.early` `.late` `.rev` `.ply` `.iter` `.every(n, f)`
+  `.lastOf(n, f)` `.off(t, f)` `.superimpose(f)` `.struct("x ~ x")`
+  `.mask("1 0")` `.swingBy(1/3, 4)`; combine with `stack` `cat` `seq`
+  `arrange([4, a], [2, b])`. `f` is an arrow function: `x => x.fast(2)`.
+- Sound: `s("bd sd hh cp oh")` drums (`.bank("tr808")`), waveforms
+  `sine triangle square sawtooth supersaw`, `piano`, `gm_*` names.
+- Controls: `.gain` `.velocity` `.pan` `.lpf` `.hpf` `.lpq` `.room` `.size`
+  `.delay` `.delaytime` `.delayfeedback` `.shape` `.crush` `.attack`
+  `.decay` `.sustain` `.release`; signals `sine saw tri perlin rand` with
+  `.range(a, b)` `.slow(n)` `.segment(n)`.
+- TuttiDAW only: `.inst("Device:Preset", {key: value})` instrument,
+  `.midifx(...)` before it, `.fx(...)` after it, in call order. Params use the
+  device's keys and units (`"4s"`, `"-6dB"`, `"1/16"`); constants only for now.
+  `toggle(1)` is an inline switch. These disable the strudel.cc link.
+
+## Top mistakes
+
+1. **Octaves**: code `c4` is MIDI 60, but TuttiDAW's piano roll (like
+   Ableton Live) labels MIDI 60 as C3. Write code names; a request for "C3"
+   from a Live user may mean MIDI 60.
+2. **Arithmetic on controls**: `note("c e").add(12)` does nothing (warning);
+   write `note("c e").add(note(12))` or `n("0 2".add(7))`.
+3. **Multi-word scales** need colons inside quotes: `"C:harmonic:minor"`,
+   `"A:minor:pentatonic"`. `"C:harmonic minor"` is two steps.
+4. **Device calls inside callbacks** fail: `every(2, x => x.fx(...))` is an
+   error; a voice has one chain. Put `.inst/.fx/.midifx` on the voice.
+5. **Patterned device params** (`{cutoff: "<300 900>"}`) are not applied
+   yet; use Strudel controls (`.lpf("<300 900>")`) for movement.
+6. **One `.inst` per voice**; a second is an error. Use another voice.
+7. **Single vs double quotes**: double quotes are mini-notation; single
+   quotes are plain strings (`register('name', ...)`, `.scale('C minor')`).
+8. **No browser APIs**: no `fetch`, `import`, timers or DOM; code runs in a
+   deterministic sandbox (seeded `Math.random`, fixed `Date`).
+9. **Unknown sound names** fall back with a warning; check
+   `references/sounds.md` and `references/devices.md`. Noise is
+   `s("white")`, `s("pink")` or `s("brown")` (hard to soft).
+10. **Voice labels** become track names: label every voice
+    (`kick:`, `bass:`) instead of `$:` when the program goes to the studio.
+
+## Tools: two backends, one API
+
+The same tools, with the same names and report shapes, run on two backends.
+Use whichever this agent has; prefer the local one.
+
+- **Local `tutticode`** (default; free, no account): the `tutticode` CLI
+  and MCP server (`npm i -g tutticode`, `tutticode mcp`) render in the
+  user's own browser with the tuttidaw.com/code engine and write files to
+  disk, up to 300 s. Its tool descriptions say "Runs locally". Without MCP,
+  call the CLI: `tutticode check prog.tc`, `tutticode render prog.tc -o
+  out.wav --seconds 12 --lufs -16 --json`, `tutticode open prog.tc`.
+  Program code goes only to the user's browser, never to TuttiDAW's servers.
+- **Web**: TuttiDAW's MCP server (`https://tuttidaw.com/api/mcp`, OAuth) or
+  HTTP (`POST https://tuttidaw.com/api/code/check|render|compare`). Renders
+  on TuttiDAW's servers (signed in, costs Muse points, 16 bars / 60 s) and
+  returns a `listenUrl` instead of files. Only this backend compares with a
+  reference recording.
+
+| tool | what it does |
+| --- | --- |
+| `code_check` | compile and plan, no audio: diagnostics, voices, mix warnings. Free, deterministic |
+| `code_render` | render and measure: loudness, true peak, bands, groove, per-voice levels |
+| `code_compare` | a render against goals (or a Muse `style`), or two renders (A/B) |
+| `code_open` | (local) open the program in a visible TuttiCode tab for the user |
+| `code_reference` | (local) search these references |
+
+## Workflow: write -> check -> render -> revise
+
+1. **Write** the smallest program that does the job; label each voice.
+2. **`code_check`** after every edit; fix every `error` diagnostic (line,
+   column and a `fix` hint), then the mix `warnings`. Never render to find
+   syntax errors. Without tools, compare every name with
+   `references/functions.md` and `references/devices.md`.
+3. **`code_render`** once the check is clean, then read the numbers
+   (`references/agent-loop.md`): loudness, clipping, silent bars, which
+   voice dominates. Change one thing at a time; `code_compare` tells you
+   whether it moved what you meant.
+4. **Hand over** the `editUrl` (local) or `listenUrl` (web) with the
+   files: it opens the program in TuttiCode, where **Open in TuttiDAW**
+   saves it as a project with one track per voice. Without tools, link
+   `https://tuttidaw.com/code#<payload>`, the payload being the UTF-8 code
+   in base64, URI-encoded (`encodeURIComponent(btoa(utf8))`, as strudel.cc's
+   long links).
+
+Pattern Clips in an open TuttiDAW project are edited with the web MCP's
+`read_pattern` / `write_pattern` (notes only; devices apply on /code and in
+group programs). Sound for videos, apps and games: the
+`tutticode-sound-for-media` skill.
+
+## References
+
+Read only what the task needs:
+
+- `references/agent-loop.md`: reading the code_check / code_render / code_compare reports, loudness targets, lengths and the `clip` error, on both backends.
+- `references/getting-started.md`: Getting started. What TuttiCode is, how a program loops, and how to play your first line.
+- `references/first-sounds.md`: First sounds. Drums with s(), pitches with note(), and the difference between them.
+- `references/mini-notation.md`: Mini-notation. The rhythm language inside the quotes - sequences, rests, groups, alternation, polymeter, Euclidean rhythms and chance.
+- `references/time-and-structure.md`: Time and structure. Functions that speed up, shift, reverse, repeat and combine patterns, and arrange them into sections.
+- `references/harmony-and-scales.md`: Harmony and scales. Note names and octaves, scale degrees, transposition, chord symbols, voicings and arpeggios.
+- `references/sounds.md`: Sounds. Drum kits and banks, synth waveforms, General MIDI instrument names, Ensemble sounds and your own samples.
+- `references/effect-controls.md`: Effect controls. Filters, reverb, delay, distortion, panning, envelopes and synth controls - and moving them with signals.
+- `references/sample-operations.md`: Sample operations. Play part of a sample, change its speed, cut it into slices, fit it to the tempo and choke it.
+- `references/tuttidaw-extensions.md`: TuttiDAW extensions. Load any TuttiDAW instrument, MIDI effect or audio effect with presets and parameters; voices, groups and Open in TuttiDAW.
+- `references/mixing.md`: Mixing: buses and master. Shared reverbs and delays on buses, sends from the voices, each voice's fader and pan, and the program's master chain - the same tracks Open in TuttiDAW makes.
+- `references/javascript.md`: JavaScript in code. Variables, functions, loops and register - and the sandbox, determinism and limits that keep shared code safe.
+- `references/muse.md`: Muse on /TuttiCode. Ask TuttiDAW's AI assistant to write, explain, fix or restyle your program, from text, a Strudel tune, a screenshot or a reference track.
+- `references/for-agents.md`: TuttiCode for agents. Let Claude Code, Copilot, Codex or any MCP client write TuttiCode and render it to audio files in your own browser, with the tutticode CLI, MCP server and skills.
+- `references/functions.md`: every function, method and signal, with signature, description and example (generated from the engine).
+- `references/devices.md`: every instrument and effect for `.inst/.fx/.midifx`, with `references/devices/<id>.md` per device: param keys, ranges, units, presets (generated from the device catalogue).
+
+Language: PATTERN LANGUAGE 1.2.0, engine 15.
+Human guide: https://tuttidaw.com/code/learn; agents: https://tuttidaw.com/code/learn/for-agents

package/dist/skills/tutticode/references/agent-loop.md

@@ -0,0 +1,103 @@
+# The agent loop: check, render, compare, revise
+
+You cannot hear. `code_check`, `code_render` and `code_compare` give you
+what a producer hears, as numbers. Both backends (local `tutticode`, web
+MCP / `/api/code`) take the same requests and return the same fields;
+differences are marked *local* or *web*.
+
+## When to call which
+
+| Situation | Call |
+| --- | --- |
+| After every edit | `code_check`. Fix every `error` before anything else |
+| The check is clean and you need to know how it sounds | `code_render` (one loop is enough while sketching) |
+| You have a target ("streaming loudness", "like house") | `code_compare` with `goals` or `goals.style` |
+| You changed one thing: did it help? | `code_compare` with `renderId` (new) and `againstRenderId` (old) |
+| *web*: `status: "queued"` / `"rendering"` | `code_render { renderId }` to wait |
+
+## Reading `code_check`
+
+- `diagnostics[]`: `severity`, `code`, `line`/`col` (1-based), `snippet`, a
+  `fix` hint. `error` blocks rendering; `warning` means something was
+  ignored or approximated; `info` is context.
+- `tempo.bpm` (`setcpm(n)` = n x 4 BPM in 4/4); `loop.bars` / `loop.seconds`:
+  the program loop, what one loop of a render plays.
+- `voices[]`: per labelled voice: notes per bar, polyphony, pitch range
+  (MIDI, `c4` = 60), instrument and effects, gain, pan.
+- `warnings[]`, read off the notes:
+
+| Code | Means | Usual fix |
+| --- | --- | --- |
+| `mix/pitch-clash` | Two voices a semitone apart | Put both on the same chord or scale there |
+| `mix/register-overlap` | Two pitched voices share a range | Move one an octave, or thin one |
+| `mix/low-end-crowded` | Two voices below `c3` together | Keep one bass part |
+| `density/very-dense` | Over 32 notes per bar in a voice | Fewer steps or `.slow()` |
+| `density/silent-voice` | An unmuted voice plays nothing | Check the mini-notation and masks |
+| `level/hot-voice` | A voice's gain above 1.2 | Turn it to 1 or less; lower the others |
+| `level/clip-risk` | Voices hitting together sum above 3 | Lower the busiest voices to 0.5-0.8 |
+
+## Reading `code_render`
+
+*local* returns `files` (`audio`, `stems`: paths written on disk),
+`editUrl`, `window` (`bars`, `seconds`, `bpm`), `loudness` (`lufs`,
+`truePeak` of the delivered file, `gainDb` applied for a `lufs` target),
+`voices[]` (each voice's solo `lufs` and `truePeak`), `barTimes` /
+`beatTimes` (seconds of each bar and beat: sync video cuts to them),
+`check` and `analysis`. *web* returns `analysis`, a `listenUrl` (24 h) and
+signed audio links.
+*web* renders at most 16 bars and 60 s, and at most 320 track-seconds
+(the tracks it plays x seconds; `check` reports them as
+`stats.renderTracks`: one per audible voice, one per waveform of a
+multi-waveform voice, four per Ensemble Set): a larger render is refused with
+`CODE_RENDER_TOO_LARGE`, which says how many bars fit. Render fewer bars,
+or mute (`_`) the voices you are not listening to.
+
+`analysis` (both):
+
+| Field | How to read it |
+| --- | --- |
+| `loudness.integratedLufs` | Overall loudness; halving every gain is about -6 LU |
+| `loudness.truePeakDbtp`, `clipping` | Keep the peak at -1 dBTP or below; `clipping` must be false |
+| `loudness.crestDb` | Peak minus RMS: under ~8 dB sounds squashed, over ~18 dB is peaky (a loudness target may not fit) |
+| `bands.low/mid/high` | Energy below 250 Hz / 250 Hz-4 kHz / above 4 kHz; high under 0.03 sounds dull |
+| `stereo.width`, `correlation` | Width 0.2-0.6 is typical; correlation below 0 is phase trouble |
+| `groove.swing`, `timingErrorMs` | 0.5 straight, 0.67 triplet swing; code is sample-accurate |
+| `silence`, `barLufs` | Leading/trailing silence, silent bars: a silent bar you did not plan is a bug |
+| `voices[]` | Each voice's `lufs` (null = silent: a dead voice) and `share` of the mix |
+
+## Loudness and length (*local* `code_render` / `tutticode render`)
+
+- Length: `seconds` (exact, cut with a 10 ms fade), `bars`, or `loops`
+  (whole loops ring out past their end). `tail` adds seconds after the
+  length for reverbs and delays and makes the file exactly length + tail;
+  `fadeIn` / `fadeOut` are linear, in seconds.
+- `lufs` applies one static gain to that integrated loudness, the same on
+  the stems. When the true peak would pass `truePeak` (default -1 dBTP)
+  the render fails with code `clip` instead of limiting: ask for a lower
+  `lufs`, or make the program less peaky (lower its loudest voice). Under
+  0.4 s there is no integrated loudness and `lufs` is ignored.
+- Exit codes (CLI): 0 ok, 1 errors in the code or `clip`, 2 bridge or
+  browser problem (run `tutticode doctor`), 3 usage.
+
+## Targets
+
+| Goal | lufs |
+| --- | --- |
+| Sketch for the user | -16..-12, true peak -1 dBTP or below |
+| Web, social, streaming | -14 |
+| Podcasts, video beds under speech | -16 (beds under a voice -20..-24) |
+| Broadcast (EBU R128) | -23 |
+| A style's finished master | `goals.style` (house -9..-7, lofi-hip-hop -14..-11, ambient -20..-14) |
+
+`goals.style` takes a Muse style id (`house`, `techno`, `trap`,
+`modern-pop`, `lofi-hip-hop`, `ambient`, `cinematic`, `synthwave`,
+`jazz-swing` and others); a render without a master chain sits a few LU
+under a style's mastered loudness, so match its spectrum first.
+
+## Comparing
+
+`code_compare` returns `deltas[]` (`metric`, `current`, `target`,
+`verdict`: `ok` / `low` / `high`) and `suggestions[]`, most important
+first, written as edits to the code. *local* compares renders of the same
+session and goals; reference recordings (`referenceUrl`,
+`referenceAudio`) need the *web* backend.

package/dist/skills/tutticode/references/devices/aligndelay.md

@@ -0,0 +1,28 @@
+# Align Delay
+
+An audio effect (`.fx`), available.
+
+```js
+note("c3 e3 g3 b3").fx("Align Delay:A/V Sync 40ms")
+```
+
+Accepted names: `aligndelay`.
+
+## Parameters
+
+| Key | Live label | Values |
+|---|---|---|
+| `delayMsL` | Left ms | 0 .. 100 ms |
+| `delayMsR` | Right ms | 0 .. 100 ms |
+| `samplesL` | Left samples | 0 .. 200 smp |
+| `samplesR` | Right samples | 0 .. 200 smp |
+| `metersL` | Left meter | 0 .. 100 m |
+| `metersR` | Right meter | 0 .. 100 m |
+| `feetL` | Left Feet | 0 .. 328.08 ft |
+| `feetR` | Right Feet | 0 .. 328.08 ft |
+| `celsius` | Celsius | -20 .. 60 °C |
+| `fahrenheit` | Fahrenheit | -4 .. 140 °F |
+
+## Factory presets
+
+A/V Sync 40ms · Distance Trim · Haas Widener · Sample Compensate

package/dist/skills/tutticode/references/devices/amp.md

@@ -0,0 +1,25 @@
+# Amp
+
+An audio effect (`.fx`), available.
+
+```js
+note("c3 e3 g3 b3").fx("Amp:Bass Roundup")
+```
+
+Accepted names: `amp`.
+
+## Parameters
+
+| Key | Live label | Values |
+|---|---|---|
+| `drive` | Gain | 0 .. 10 |
+| `bass` | Bass | 0 .. 10 |
+| `middle` | Middle | 0 .. 10 |
+| `treble` | Treble | 0 .. 10 |
+| `presence` | Presence | 0 .. 10 |
+| `volume` | Volume | 0 .. 10 |
+| `dryWetBalance` | Dry/Wet | 0 .. 1 % |
+
+## Factory presets
+
+Bass Roundup · Blues Drive · Boost and Crunch · Clean · Discrete · Heavy · Key Crunch · Marsh Mellows · Metalic · Rhythm Funk · Rock all 10 · Screamer