@hraness/dawg 0.2.0 → 0.3.0

package/README.md

@@ -15,20 +15,28 @@ curl -fsSL https://dawg.sh/install | sh
 or install the release tarball from GitHub directly:
 
 ```sh
-bun add -g https://github.com/hraness/dawg/releases/download/v0.2.0/hraness-dawg-0.2.0.tgz
+bun add -g https://github.com/hraness/dawg/releases/download/v0.3.0/hraness-dawg-0.3.0.tgz
 dawg --help
 ```
 
 Each [release](https://github.com/hraness/dawg/releases) is immutable and ships the tarball, a `SHA256SUMS` file and a build provenance attestation. To check a download before installing it:
 
 ```sh
-gh release download v0.2.0 --repo hraness/dawg
+gh release download v0.3.0 --repo hraness/dawg
 shasum -a 256 -c SHA256SUMS
-gh attestation verify hraness-dawg-0.2.0.tgz --repo hraness/dawg
-bun add -g "$PWD/hraness-dawg-0.2.0.tgz"
+gh attestation verify hraness-dawg-0.3.0.tgz --repo hraness/dawg
+bun add -g "$PWD/hraness-dawg-0.3.0.tgz"
 ```
 
-dawg is not published to npm yet. To run from source instead:
+dawg is also on npm as [`@hraness/dawg`](https://www.npmjs.com/package/@hraness/dawg):
+
+```sh
+npm i -g @hraness/dawg
+# or
+bun add -g @hraness/dawg
+```
+
+To run from source instead:
 
 ```sh
 git clone https://github.com/hraness/dawg.git
@@ -37,13 +45,13 @@ bun install --frozen-lockfile
 bun run dawg
 ```
 
-Running `dawg` creates `.dawg/session` when needed and attaches to that session on later launches. Use `dawg --new` for a new composition, `dawg --session <name|id>` to attach explicitly, or `dawg --track bass` to focus a named track.
+Running `dawg` creates `.dawg/session` when needed (the first launch says `created .dawg/ · add it to .gitignore`) and attaches to that session on later launches. Use `dawg --new` for a new composition, `dawg --session <name|id>` to attach explicitly (an unknown name or id is an error, `no session named "…" · dawg sessions`, never a new session), or `dawg --track bass` to focus a named track. `dawg --version` prints the version; an unknown subcommand or option is rejected with usage before anything is written, and `dawg sessions --help`, `dawg render --help` and `dawg auth --help` print their own usage.
 
 ### Sessions
 
 Every window you open on a session takes the first track no other window has focused, in score order. Open three terminals on a three-track session and each one restores a different instrument. A fourth window gets a draft track (`track-4`, "all tracks open · new track") that is added to the score on its first edit, so idle windows never clutter the song. `--track` always wins over auto-claim.
 
-Sessions have names. A new session starts as `untitled` and is named automatically from what you play (`a minor bass groove`, `dusty basement funk`). `/rename <name>` sets your own name and stops auto-naming for good; `/rename --auto` hands it back. A user rename always beats an auto-name that was still in flight, and every window updates. `/fork [name]` snapshots the current song into a new session (`night drive` → `night drive 2` → `night drive 3`; a fork of `night drive 2` is `night drive 3`) and switches this window to it. `/sessions` lists recent sessions, `/resume` opens a picker (↑/↓, Enter, Esc) and `/resume <n|name|id>` switches directly. Undo in a fork steps back past the fork point into the parent's history. `dawg sessions` prints the same list from the shell.
+Sessions have names. A new session starts as `untitled` and is named automatically from what you play (`a minor bass groove`, `dusty basement funk`). `/rename <name>` sets your own name and stops auto-naming for good; `/rename --auto` hands it back. A user rename always beats an auto-name that was still in flight, and every window updates. `/fork [name]` snapshots the current song into a new session (`night drive` → `night drive 2` → `night drive 3`; a fork of `night drive 2` is `night drive 3`) and switches this window to it. `/sessions` lists sessions in an overlay (one summary card stays in the strip), `/resume` opens a picker (↑/↓, Enter or a digit, Esc) and `/resume <n|name|id>` switches directly by any list index, name or id prefix. Undo in a fork steps back past the fork point into the parent's history. `dawg sessions` prints the same list from the shell.
 
 Auto-naming is cheap. dawg keeps a local musical fingerprint (tempo, key estimate, instruments, register, density and effects) and only asks a model when the music actually changed, at most once every few turns, after three quiet seconds. The request is about 120 tokens in and 12 out through the configured provider (gateway `anthropic/claude-haiku-4.5`, or xcb), runs in the background so it never blocks the prompt, and falls back to a local name such as `96 bpm drums` when offline or with `DAWG_AI=0`. In tests a typical 10-prompt session makes 2–3 naming calls.
 
@@ -63,7 +71,7 @@ automate volume at 0 0.2
 automate volume at 4 1
 automate pan at 0 -1
 automate pan at 4 1
-track drums
+/track drums
 instrument kit
 hit kick at 0
 hit snare at 1 vel 0.7
@@ -98,50 +106,91 @@ move note <id> to 2.5
 duration note <id> 0.25
 /export loop.track.json
 /import loop.track.json
-/model opus-5.5
+/model             pick a model (cost per prompt shown)
 ```
 
+`/help` (or `?`) opens the command reference in an overlay, grouped as music, session, window and keys, with every command listed once in its canonical form: music words are bare (`tempo 96`, `pattern kick every 1`), app commands take a slash (`/tracks`, `/export`); bare `tracks`, `export`, `import` and `track` keep working as aliases. An unknown `/word` is rejected locally (`unknown command /foo · /help`), and a known verb with bad arguments gets usage (`pan 3 · pan takes -1…1 · pan -0.5`) instead of a model call. `/track <name>` focuses a track in this window, creating it when it is new; a track another live window has open stays theirs (`drums is open in another window`).
+
 A track named `drums` (or `kit`) starts with the `kit` instrument; `instrument kit` turns any track into a drum track. Drum voices are `kick` (`bd`), `snare` (`sd`), `clap` (`cp`), `rim` (`perc`), `tom`, `hat` (`hh`), and `openhat` (`oh`); the highway shows one lane per voice. `pattern <voice> <beats...>` takes up to 64 beats, `pattern <voice> every <step>` (step ≥ 0.125) fills the loop, `vel <0..1>` sets velocity, and `clear <voice>` removes only that voice. `filter <hz> [resonance]` is a per-track low-pass (20–20000 Hz, resonance 0–1), `delay <beats> [feedback] [mix]` is a tempo-synced stereo ping-pong echo send (0.0625–4 beats, feedback ≤ 0.9, mix 0–1), `reverb <mix> [size]` is an algorithmic stereo reverb send (mix 0–1, size 0–1, default 0.5; `reverb off` removes it), and `automate filter|resonance|delay-feedback|delay-mix at <beat> <value>` writes the cutoff (Hz), resonance (0–1), delay feedback (0–0.9) and delay mix (0–1) lanes. `solo` isolates the focused track in playback across every window; `redo` re-applies the last undone edit.
 
-The screen has four parts. A one-line header shows track · session · ▶/⏸ BPM · key · model · revision · sync state. The highway overlays every unmuted track, each in its own stable accent, with the focused track bright and the others dimmed; `/view focus` shows only the focused track and `/view all` (the default) brings the rest back. Below it, an activity strip shows operation cards (`✓ +8 bass notes · rev 41→42 · ^z undo`), queue depth, a braille spinner while the agent works, and errors in red with an `✗` prefix. The prompt panel is filled with a background color. It wraps by grapheme, grows from 1 to 8 rows (capped at 30% of the screen, then scrolls internally) and keeps the draft when the terminal is resized. Narrow terminals collapse the header and hints, and below 24×8 the screen shows a resize hint.
-
-| Key                  | Action                                                                       |
-| -------------------- | ---------------------------------------------------------------------------- |
-| Space (empty prompt) | play / pause                                                                 |
-| Enter                | submit (STEER) or queue (QUEUE mode)                                         |
-| Shift+Enter, Ctrl+J  | newline                                                                      |
-| Alt+Enter            | queue this prompt                                                            |
-| Ctrl+Q               | toggle the STEER / QUEUE mode pill                                           |
-| Ctrl+Z / Ctrl+Y      | undo / redo                                                                  |
-| Ctrl+O or `/log`     | transcript overlay: ↑/↓, PgUp/PgDn scroll, `/` filters requests, ops, errors |
-| Esc                  | cancel the agent turn, close the overlay, or clear the draft                 |
-| Ctrl+L               | full redraw                                                                  |
-| Ctrl+C               | exit                                                                         |
+The screen has four parts. A one-line header shows `dawg` · track · ▶/⏸ BPM · key · session · window count (when more than one) on the left and model · rev · sync state on the right; narrower terminals drop the least important segments first. The highway overlays every unmuted track, each in its own stable accent, with the focused track bright and the others dimmed; `/view focus` shows only the focused track and `/view all` (the default) brings the rest back. A track with no hits shows `main · empty · add C4 at 0 to start` in place of lane labels. Below it, an activity strip shows operation cards (`✓ +8 bass notes · rev 41→42 · ^z undo`; the undo hint accompanies the first three score edits), queue depth, a braille spinner while the agent works, and errors in red with an `✗` prefix in one shape, `<what> · <why> · <next step>` (`no such file · nope.json`). The prompt panel is filled with a background color. It wraps by grapheme, grows from 1 to 8 rows (capped at 30% of the screen, then scrolls internally) and keeps the draft when the terminal is resized. Narrow terminals collapse the header and hints, and below 24×8 the screen shows a resize hint.
+
+| Key                   | Action                                                                       |
+| --------------------- | ---------------------------------------------------------------------------- |
+| Space (empty prompt)  | play / pause                                                                 |
+| Enter                 | submit (STEER) or queue (QUEUE mode)                                         |
+| Shift+Enter, Ctrl+J   | newline                                                                      |
+| Alt+Enter             | queue this prompt                                                            |
+| Ctrl+Q                | toggle the STEER / QUEUE mode pill                                           |
+| Ctrl+Z / Ctrl+Y       | undo / redo                                                                  |
+| Ctrl+O, `/transcript` | transcript overlay: ↑/↓, PgUp/PgDn scroll, `/` filters requests, ops, errors |
+| Esc                   | cancel the agent turn, close the overlay, or clear the draft                 |
+| Ctrl+L                | full redraw                                                                  |
+| Ctrl+C                | exit                                                                         |
 
 A STEER submit runs ahead of queued work. Bracketed paste preserves multiline input.
 
 `/theme default|high-contrast|mono` and `--theme <name>` (or `DAWG_THEME`) pick a theme. Semantic color tokens map to truecolor, 256, 16 or no color. `NO_COLOR` and `TERM=dumb` force monochrome. `/motion off`, `--reduce-motion` or `DAWG_REDUCE_MOTION=1` replace animations with static states in the same positions. Every color has a non-color cue as well: glyph density, `✓`/`✗`/`!` prefixes, the mode pill text and `▶`/`⏸`.
 
+### Project files
+
+`dawg init` turns the current directory into a project: `song.ts` and one `tracks/<slug>/track.ts` per track, written with a small typed SDK (`import { track, note, hit } from "dawg"`). Edit them in any editor (or let the agent edit them) and every open window applies the change as one revision; edit in the TUI and the affected file is reprinted. `dawg check` typechecks and evaluates the files and exits 1 with `file:line:col` diagnostics. See **Project files and SDK** in [DAWG.md](./DAWG.md).
+
 ## Auth
 
-Run `dawg login` once to give the agent a model. With the Vercel CLI it signs you in (if needed) and creates an AI Gateway key named `dawg-<hostname>`; `--budget <dollars>` sets its spend limit. Without the CLI it prints `bun add -g vercel` and lets you paste a key instead (`dawg login --key`, hidden input, Enter opens the key page).
+Run `dawg login` (or just `dawg` the first time) to give the agent a model. dawg looks for what is already on the machine, in parallel and with a 4 s cap, then shows one picker: ↑/↓ or a number, Enter to choose, Esc to cancel. The first detected option is the default, and when exactly one is ready it just asks `Use <it>? [Y/n]`.
+
+| Option                     | Detected from                                                        | Sign-in                                                                                                                                                                                                                        |
+| -------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Vercel AI Gateway          | `AI_GATEWAY_API_KEY`, a stored dawg key, `vercel whoami`             | With the Vercel CLI: `vercel login` in the browser if needed, then a key named `dawg-<hostname>` is created (`--budget <dollars>` sets its limit). Without it: opens the keys page and takes a pasted key (hidden input).      |
+| OpenRouter                 | `OPENROUTER_API_KEY`, a stored dawg key                              | OpenRouter's OAuth PKCE flow: dawg opens the browser on a one-time `127.0.0.1` callback, checks the state, exchanges the code for a key and verifies it (5 min timeout; the URL is printed too). `--key` pastes a key instead. |
+| ChatGPT/Codex subscription | [xcb](https://github.com/hraness/xcb) accounts with provider `codex` | Lists ready accounts and their models; runs `xcb setup codex` (browser sign-in) when none is ready.                                                                                                                            |
+| Claude subscription        | xcb accounts with provider `claude`                                  | Same, with `xcb setup claude`.                                                                                                                                                                                                 |
 
-- `dawg login --xcb` uses a Claude, Codex or Devin subscription through [xcb](https://github.com/hraness/xcb) (`curl -fsSL https://xcb.sh/install.sh | sh`). It lists the accounts that `xcb --json generate --capabilities` reports as available and saves your pick; inside the TUI, `/login --xcb` opens the same choice as a picker of accounts and models. An account whose admission xcb reports as `pending` counts as available, and its first turn shows `admitting account…` while xcb admits it. The provider is re-resolved when `~/.config/dawg` credentials or config change, so a login in another terminal applies on the next turn. An account only appears after xcb's [application qualification](https://github.com/hraness/xcb/blob/main/docs/application-api.md); if none qualify, the command prints the read-only `xcb --json qualify-application --inspect` line for each connected account.
-- `dawg auth status` (or `/auth` in the TUI; `--check` verifies the key online) shows the provider, a masked key such as `vck_…abcd` and its source, plus the audio backend. `dawg logout` removes the stored key and the provider choice. `/login` works in the TUI too; flows that need hidden input or a browser tell you to use a shell.
-- Keys go to the macOS Keychain (service `dawg`, account `ai-gateway`, passed to `security -i` on stdin so the key never appears in a process list) or to `~/.config/dawg/credentials.json` (0600, directory 0700). They are never written to `.dawg/`. `AI_GATEWAY_API_KEY` in the environment always wins. `DAWG_CREDENTIAL_STORE=file` skips the Keychain and `DAWG_CONFIG_DIR` moves the config directory.
-- `DAWG_PROVIDER=gateway|xcb|auto` overrides the saved choice. `auto` (the default) uses the gateway when a key exists, then an available xcb account, otherwise direct commands only with a hint to run `dawg login`. `DAWG_AI=0` turns the agent off. The header shows the active provider, for example `opus-5.5 · gateway` or `devin/swe-2-high · xcb`.
+- Shortcuts: `dawg login gateway|openrouter|codex|claude` (`--account <id> --model <id>` for subscriptions), `dawg login --xcb` for any xcb account (Devin too), `dawg login --key` to paste a gateway key.
+- The choice sticks. dawg saves the provider, model and account in `~/.config/dawg/config.json` (0600, written atomically, never a key) and reuses it on every start and `dawg login` without asking. `dawg login <provider>`, `/model` and `dawg logout [provider]` change or clear it. If the saved provider stops working (revoked key, account gone), dawg says so once and opens the picker; it never switches providers on its own.
+- `/login` in the TUI suspends the screen, runs the same flow (browser and `vercel login` included) and redraws when done.
+- `dawg model` (or `/model` in the TUI) picks a model for the active provider, grouped as frontier, fast and open weights, with type-to-filter and an estimated cost per prompt (`~$0.004/prompt`) from [models.dev](https://models.dev) pricing (OpenRouter's own `/models` prices on OpenRouter); subscriptions show `included`. On the gateway and OpenRouter only tool-calling models are listed; for subscriptions the list is what xcb reports for the account. `/model opus-5.5` sets one directly, and any `vendor/model` ID the provider serves works too.
+- Under the prompt, `$0.12 session · $0.48 today · opus-5.5 · gateway` shows spend from the usage each response reports (the provider's own cost when given, else tokens × price). The daily total is shared across windows through `~/.config/dawg/usage.json`. Subscriptions show `subscription`.
+- `dawg auth status` (also `/auth`; `--check` verifies keys online) lists all four options with detected, active and validated state, plus the installed xcb version and the audio backend. Keys appear only masked (`vck_…abcd`).
+- Keys go to the macOS Keychain (service `dawg`, passed to `security -i` on stdin so a key never appears in a process list) or `~/.config/dawg/credentials.json` (0600, directory 0700). They are never written to `.dawg/`. Environment keys always win.
+- Provider order: `DAWG_PROVIDER`, then the saved choice, then auto (AI Gateway, then OpenRouter, then a ready subscription). `DAWG_AI=0` turns the agent off. The header shows `<model> · <provider>`.
+- Subscriptions need xcb 0.20.0 or newer. An account is usable when xcb reports it `available`; one still in automatic admission (`admission: pending`) works, but its first turn can take up to a minute longer. Accounts whose catalog is missing are refreshed once (`xcb accounts refresh`) during discovery.
 
-On the gateway, unrecognized requests go to a streaming, tool-calling agent. Choose `DAWG_MODEL=opus-5.5` or `DAWG_MODEL=sol-6.1`, or switch with `/model`. By default these labels map to `anthropic/claude-opus-5.5` and `openai/gpt-6.1-sol` from the gateway catalog. Override them with `DAWG_OPUS_MODEL` and `DAWG_SOL_MODEL`. Other labels are rejected. xcb has no tool calling, so dawg asks for one JSON object of ops per call and runs each op through the same checks; it retries with diagnostics up to 3 calls per turn.
+On the gateway and OpenRouter, unrecognized requests go to a streaming, tool-calling agent through the OpenAI-compatible chat API. The default is `opus-5.5` (`anthropic/claude-opus-5.5`); `DAWG_MODEL=<alias|vendor/model>` overrides it, and an unknown value is an error at startup that lists the choices. xcb has no tool calling, so dawg asks for one JSON object of ops per call and runs each op through the same checks; it retries with diagnostics up to 3 calls per turn.
 
 The agent edits the score only through typed tools: `add_notes`, `add_drums`, `remove_notes`, `update_notes`, `set_instrument`, `set_mix` (with solo), `set_effects` (filter, delay and reverb), `set_automation` (volume, pan, filter cutoff and resonance, delay feedback and mix), `extend_loop`, `set_tempo`, `create_track`, `transport` and `explain`. Each call is validated, then committed as its own revision, and the status line shows its result (for example `✓ +8 bass notes`). While the agent is working, Esc cancels and keeps every change accepted so far. Enter sends a steering message that the agent reads at its next step. A queued submit (Ctrl+Q queue mode) waits until the turn ends.
 
-Playback renders deterministic stereo PCM with sine, piano, pluck, bass, saw, square, and triangle voices plus a synthesized drum kit (pitch-swept sine kick, seeded-noise snare and hats), applies per-track volume, equal-power pan (-1 left to 1 right), low-pass filter, ping-pong delay, and a Freeverb-style reverb, and honors mute and solo. Renders are byte-identical across runs. Playback is gapless: one long-lived player (`ffplay`, else SoX `play`) reads a seamless loop as raw PCM on stdin, and edits, tempo changes and seeks swap the buffer in place at the current position without restarting it, so the transport stays aligned with what you hear. On macOS without either, `afplay` replays a re-rendered loop on each edit. `dawg auth status` shows the backend; `DAWG_AUDIO_BACKEND=ffplay|sox|afplay|none` forces one, `DAWG_AUDIO_PLAYER="cmd {rate} {channels}"` streams to any stdin player, and `DAWG_AUDIO=0` runs headless. `dawg --export file.track.json` and `dawg --import file.track.json` exchange the bounded `track.loop/v1` document. `dawg render out.wav` writes the current session (or `--session <name|id>`, or `--import file.track.json`) to a WAV through the same renderer, without starting dawgd or playing audio; the same score always produces the same bytes, and the command prints the file's sha256. `/status` prints the session name, revision, composition digest and connection mode. `DAWG_DEMO=1 bun run src/main.ts` prints a deterministic renderer frame for development.
+Playback renders deterministic stereo PCM with sine, piano, pluck, bass, saw, square, and triangle voices plus a synthesized drum kit (pitch-swept sine kick, seeded-noise snare and hats), applies per-track volume, equal-power pan (-1 left to 1 right), low-pass filter, ping-pong delay, and a Freeverb-style reverb, and honors mute and solo. Renders are byte-identical across runs. Playback is gapless: one long-lived player (`ffplay`, else SoX `play`) reads a seamless loop as raw PCM on stdin, and edits, tempo changes and seeks swap the buffer in place at the current position without restarting it, so the transport stays aligned with what you hear. On macOS without either, `afplay` replays a re-rendered loop on each edit. `dawg auth status` shows the backend; `DAWG_AUDIO=0` runs headless (see Environment for the other switches). `dawg --export file.track.json` and `dawg --import file.track.json` exchange the bounded `track.loop/v1` document. `dawg render out.wav` writes the current session (or `--session <name|id>`, or `--import file.track.json`) to a WAV through the same renderer, without starting dawgd or playing audio; the same score always produces the same bytes, and the command prints the file's sha256. `/status` prints the session name, revision, composition digest and storage (`shared via dawgd` or `saved locally · no daemon`).
+
+The agent can download a YouTube reference, split stems, analyze tempo and key, transcribe notes and lyrics, and import samples into `tracks/<slug>/`; `dawg media doctor` shows which local binaries or StemDeck it will use (see [DAWG.md](./DAWG.md#media-tools)).
+
+## Environment
+
+| Variable                                                      | Effect                                                                                                                                  |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `DAWG_AUDIO=0`                                                | no sound; the transport still runs (the one audio kill switch)                                                                          |
+| `DAWG_AUDIO_BACKEND=ffplay\|sox\|afplay`                      | force a player (`none` is still accepted and means the same as `DAWG_AUDIO=0`)                                                          |
+| `DAWG_AUDIO_PLAYER="cmd {rate} {channels}"`                   | stream raw PCM to any stdin player                                                                                                      |
+| `DAWG_AI=0`                                                   | agent off; unrecognized requests are rejected locally and naming stays local                                                            |
+| `DAWG_PROVIDER=gateway\|openrouter\|codex\|claude\|xcb\|auto` | provider choice (default: the saved choice, else `auto`)                                                                                |
+| `DAWG_MODEL=<alias\|vendor/model>`                            | model for this run (unknown values are rejected)                                                                                        |
+| `AI_GATEWAY_API_KEY`, `OPENROUTER_API_KEY`                    | win over any stored key                                                                                                                 |
+| `XCB_BIN`                                                     | path to xcb for the subscription options                                                                                                |
+| `DAWG_CREDENTIAL_STORE=file`, `DAWG_CONFIG_DIR`               | skip the Keychain; move `~/.config/dawg`                                                                                                |
+| `DAWG_STEMDECK_URL`                                           | StemDeck for the media tools (default `http://127.0.0.1:8000`; else local yt-dlp, demucs, basic-pitch, whisper-cli)                     |
+| `DAWG_DAEMON=0`                                               | file-lock path, no dawgd                                                                                                                |
+| `DAWG_DEMO=1`                                                 | print one deterministic frame and exit (also `--demo`, or a non-TTY stdin); `DAWG_DEMO=1 bun run src/main.ts` is the development render |
+| `DAWG_THEME`, `DAWG_REDUCE_MOTION=1`                          | theme (`default\|high-contrast\|mono`) and static motion                                                                                |
+| `NO_COLOR`, `TERM=dumb`                                       | monochrome                                                                                                                              |
 
 ## Architecture
 
 - `core/` defines the bounded immutable `track.loop/v1` score and operations.
 - `src/session/` provides an append-only local event log, atomic snapshots, and `dawgd`: one local daemon per session (`src/daemon.ts`), started automatically by the first window. Windows connect over a Unix socket, send idempotent intents, and receive accepted changes, presence, and one shared transport clock. If the daemon cannot start, windows fall back to the file-lock path and say so in the status line. `dawg sessions` lists the workspace's sessions with revision, update time, and live daemon.
 - `src/agent/` runs the bounded streaming tool-calling agent: the SSE gateway client, the tool registry, the composition brief, and operation validation.
+- `src/agent/workspace.ts` and `src/web/` give the agent bounded project file access (writes scoped to `song.ts` and the focused `tracks/<slug>/`) and web search and fetch with injectable network.
+- `core/sdk/` and `src/project/` make a directory with `dawg.json` a project of typechecked TypeScript files (`song.ts`, `tracks/<slug>/track.ts`) kept in two-way sync with the session.
 - `src/audio/` owns the transport clock, deterministic instrument-bank WAV rendering, and per-session playback lock. When `dawgd` is running it is the only process that plays audio.
 - `tui/` owns terminal capability detection, semantic colors, animation phases, piano-roll rendering, and the multiline prompt editor.
 

package/core/diff.ts

@@ -0,0 +1,249 @@
+/**
+ * Score diff: the shortest list of `ScoreOperation`s that turns score A into
+ * score B, so a project edit commits as ordinary session operations that
+ * rebase, undo and broadcast like everything else.
+ *
+ * Order: song settings, note removals, track removals, track additions,
+ * track moves, track patches, note updates, note additions. Each track and
+ * each note appears at most once per kind. `applyScoreOperations(a,
+ * diffScores(a, b))` deep-equals `b` (notes and tracks are stored in
+ * canonical order, so insertion order never matters).
+ */
+
+import {
+  applyScoreOperation,
+  TrackScore,
+  type Note,
+  type ScoreOperation,
+  type Track,
+  type TrackPatch,
+} from "./score.ts";
+
+export class DiffError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DiffError";
+  }
+}
+
+const EFFECTS = ["filter", "delay", "reverb", "sampler"] as const;
+const LANES = [
+  "volumeAutomation",
+  "panAutomation",
+  "filterAutomation",
+  "resonanceAutomation",
+  "delayFeedbackAutomation",
+  "delayMixAutomation",
+] as const;
+
+/** Operations turning `a` into `b`; empty when they are equal. */
+export function diffScores(
+  a: TrackScore,
+  b: TrackScore,
+): readonly ScoreOperation[] {
+  if (a.ticksPerBeat !== b.ticksPerBeat)
+    throw new DiffError(
+      `ticksPerBeat differs (${a.ticksPerBeat} → ${b.ticksPerBeat}); the session resolution is fixed`,
+    );
+  const ops: ScoreOperation[] = [];
+  if (a.beatsPerBar !== b.beatsPerBar)
+    ops.push({ type: "setMeter", beatsPerBar: b.beatsPerBar });
+  if (a.bars !== b.bars) ops.push({ type: "setBars", bars: b.bars });
+  if (a.tempoBpm !== b.tempoBpm)
+    ops.push({ type: "setTempo", tempoBpm: b.tempoBpm });
+  if (a.key !== b.key) ops.push({ type: "setKey", key: b.key });
+
+  const aTracks = new Map(a.tracks.map((track) => [track.id, track]));
+  const bTracks = new Map(b.tracks.map((track) => [track.id, track]));
+  const aNotes = new Map(a.notes.map((note) => [note.id, note]));
+  const bNotes = new Map(b.notes.map((note) => [note.id, note]));
+
+  const updates: ScoreOperation[] = [];
+  const additions: ScoreOperation[] = [];
+  for (const note of a.notes) {
+    if (!bTracks.has(note.trackId)) continue; // removed with its track
+    const next = bNotes.get(note.id);
+    if (!next || next.trackId !== note.trackId) {
+      ops.push({ type: "removeNote", noteId: note.id });
+      continue;
+    }
+    const patch = notePatch(note, next);
+    if (patch) updates.push({ type: "updateNote", noteId: note.id, patch });
+  }
+  for (const note of b.notes) {
+    const previous = aNotes.get(note.id);
+    if (
+      previous &&
+      previous.trackId === note.trackId &&
+      bTracks.has(note.trackId)
+    )
+      continue;
+    if (
+      previous &&
+      previous.trackId === note.trackId &&
+      !aTracks.has(note.trackId)
+    )
+      continue;
+    additions.push({ type: "addNote", note });
+  }
+
+  for (const track of a.tracks)
+    if (!bTracks.has(track.id))
+      ops.push({ type: "removeTrack", trackId: track.id });
+  const order = a.tracks
+    .filter((track) => bTracks.has(track.id))
+    .map((t) => t.id);
+  for (const track of b.tracks)
+    if (!aTracks.has(track.id)) {
+      ops.push({ type: "addTrack", track });
+      order.push(track.id);
+    }
+  b.tracks.forEach((track, index) => {
+    if (order[index] === track.id) return;
+    const from = order.indexOf(track.id);
+    order.splice(from, 1);
+    order.splice(index, 0, track.id);
+    ops.push({ type: "moveTrack", trackId: track.id, index });
+  });
+  for (const track of b.tracks) {
+    const previous = aTracks.get(track.id);
+    if (!previous) continue;
+    const patch = trackPatch(previous, track);
+    if (patch) ops.push({ type: "updateTrack", trackId: track.id, patch });
+  }
+  ops.push(...updates, ...additions);
+  return Object.freeze(ops);
+}
+
+/** Applies operations in order; the inverse of `diffScores`. */
+export function applyScoreOperations(
+  score: TrackScore,
+  operations: readonly ScoreOperation[],
+): TrackScore {
+  return operations.reduce(applyScoreOperation, score);
+}
+
+function notePatch(
+  a: Note,
+  b: Note,
+):
+  | Readonly<
+      Partial<Pick<Note, "startTick" | "durationTicks" | "pitch" | "velocity">>
+    >
+  | undefined {
+  const patch: Record<string, number> = {};
+  for (const key of [
+    "startTick",
+    "durationTicks",
+    "pitch",
+    "velocity",
+  ] as const)
+    if (a[key] !== b[key]) patch[key] = b[key];
+  return Object.keys(patch).length > 0 ? patch : undefined;
+}
+
+function trackPatch(a: Track, b: Track): TrackPatch | undefined {
+  const patch: Record<string, unknown> = {};
+  for (const key of ["name", "instrument", "muted", "volume", "pan"] as const)
+    if (a[key] !== b[key]) patch[key] = b[key];
+  if ((a.solo ?? false) !== (b.solo ?? false)) patch.solo = b.solo ?? false;
+  for (const key of EFFECTS)
+    if (!deepEqual(a[key], b[key])) patch[key] = b[key] ?? null;
+  for (const key of LANES)
+    if (!deepEqual(a[key] ?? [], b[key] ?? [])) patch[key] = b[key] ?? [];
+  return Object.keys(patch).length > 0 ? (patch as TrackPatch) : undefined;
+}
+
+/** Structural equality for plain JSON-like data. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  )
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left).filter((key) => left[key] !== undefined);
+  const other = Object.keys(right).filter((key) => right[key] !== undefined);
+  if (keys.length !== other.length) return false;
+  return keys.every((key) => deepEqual(left[key], right[key]));
+}
+
+/**
+ * Gives the notes of `evaluated` (fresh from `song.ts`, content-hash ids)
+ * the ids of matching notes in `current` (the session, whose ids the TUI
+ * and agent may have chosen) so `diffScores(current, result)` updates
+ * notes in place instead of replacing them. A note matches by exact
+ * content first, then by track, pitch and start.
+ */
+export function adoptNoteIds(
+  current: TrackScore,
+  evaluated: TrackScore,
+): TrackScore {
+  const exact = new Map<string, Note[]>();
+  const loose = new Map<string, Note[]>();
+  for (const note of current.notes) {
+    push(exact, exactKey(note), note);
+    push(loose, looseKey(note), note);
+  }
+  const taken = new Set<string>();
+  const adopted: Note[] = [];
+  const pending: Note[] = [];
+  for (const note of evaluated.notes) {
+    const match = take(exact, exactKey(note), taken);
+    if (match) {
+      taken.add(match.id);
+      adopted.push(match.id === note.id ? note : { ...note, id: match.id });
+    } else pending.push(note);
+  }
+  for (const note of pending) {
+    const match = take(loose, looseKey(note), taken);
+    if (match) {
+      taken.add(match.id);
+      adopted.push({ ...note, id: match.id });
+    } else adopted.push(note);
+  }
+  // A fresh content id can collide with an adopted one; keep ids unique.
+  const used = new Set<string>();
+  const unique = adopted.map((note) => {
+    let id = note.id;
+    for (let n = 2; used.has(id); n += 1) id = `${note.id.slice(0, 60)}-${n}`;
+    used.add(id);
+    return id === note.id ? note : { ...note, id };
+  });
+  return new TrackScore({ ...evaluated.toJSON(), notes: unique });
+}
+
+function exactKey(note: Note): string {
+  return `${note.trackId}|${note.pitch}|${note.startTick}|${note.durationTicks}|${note.velocity}`;
+}
+
+function looseKey(note: Note): string {
+  return `${note.trackId}|${note.pitch}|${note.startTick}`;
+}
+
+function push(map: Map<string, Note[]>, key: string, note: Note): void {
+  const list = map.get(key);
+  if (list) list.push(note);
+  else map.set(key, [note]);
+}
+
+function take(
+  map: Map<string, Note[]>,
+  key: string,
+  taken: Set<string>,
+): Note | undefined {
+  const list = map.get(key);
+  if (!list) return undefined;
+  const index = list.findIndex((note) => !taken.has(note.id));
+  if (index < 0) return undefined;
+  return list.splice(index, 1)[0];
+}

package/core/key.ts

@@ -0,0 +1,43 @@
+/**
+ * Key estimation from a 12-bin pitch-class histogram. Shared by session
+ * auto-naming (`src/session/naming.ts`) and audio analysis
+ * (`src/media/analyze.ts`), so both agree on what "a minor" means.
+ */
+export const KEY_NOTE_NAMES = [
+  "c",
+  "c#",
+  "d",
+  "eb",
+  "e",
+  "f",
+  "f#",
+  "g",
+  "ab",
+  "a",
+  "bb",
+  "b",
+] as const;
+const MAJOR = [0, 2, 4, 5, 7, 9, 11];
+const MINOR = [0, 2, 3, 5, 7, 8, 10];
+
+/** Best-fitting major or minor scale for a pitch-class histogram, or null. */
+export function estimateKey(histogram: readonly number[]): string | null {
+  if (histogram.length < 12) return null;
+  const total = histogram.reduce((sum, value) => sum + value, 0);
+  if (!(total > 0)) return null;
+  let best: { key: string; score: number } | undefined;
+  for (let tonic = 0; tonic < 12; tonic += 1) {
+    for (const [mode, scale] of [
+      ["major", MAJOR],
+      ["minor", MINOR],
+    ] as const) {
+      let fit = 0;
+      for (const step of scale) fit += histogram[(tonic + step) % 12]!;
+      // Tonic and fifth weigh extra so relative keys separate.
+      fit += histogram[tonic]! * 0.75 + histogram[(tonic + 7) % 12]! * 0.25;
+      if (!best || fit > best.score + 1e-9)
+        best = { key: `${KEY_NOTE_NAMES[tonic]} ${mode}`, score: fit };
+    }
+  }
+  return best!.key;
+}

package/core/pitch.ts

@@ -0,0 +1,60 @@
+/**
+ * Pitch-name helpers shared by the command parser, the SDK and the printer.
+ *
+ * Names are scientific pitch notation: a letter `A`–`G`, an optional `#` or
+ * `b`, and an octave from -1 to 9 (`C4` = 60, `A4` = 69). Parsing is
+ * case-insensitive; printing always uses sharps so a name round-trips to the
+ * same MIDI number.
+ */
+
+const SEMITONES: Readonly<Record<string, number>> = Object.freeze({
+  c: 0,
+  d: 2,
+  e: 4,
+  f: 5,
+  g: 7,
+  a: 9,
+  b: 11,
+});
+
+const NAMES = Object.freeze([
+  "C",
+  "C#",
+  "D",
+  "D#",
+  "E",
+  "F",
+  "F#",
+  "G",
+  "G#",
+  "A",
+  "A#",
+  "B",
+] as const);
+
+/** MIDI number for a pitch name, or NaN when the name is malformed or out of range. */
+export function pitchToMidi(value: string): number {
+  if (typeof value !== "string") return Number.NaN;
+  const match = value.trim().match(/^([a-gA-G])([#b]?)(-?\d{1,2})$/);
+  if (!match) return Number.NaN;
+  const accidental = match[2] === "#" ? 1 : match[2] === "b" ? -1 : 0;
+  const midi =
+    (Number(match[3]) + 1) * 12 +
+    (SEMITONES[match[1]!.toLowerCase()] ?? 0) +
+    accidental;
+  return midi >= 0 && midi <= 127 ? midi : Number.NaN;
+}
+
+/** Pitch name with sharps for a MIDI number 0..127 (`60` → `C4`). */
+export function midiToPitch(midi: number): string {
+  if (!Number.isInteger(midi) || midi < 0 || midi > 127)
+    throw new RangeError(`MIDI pitch out of range: ${String(midi)}`);
+  return `${NAMES[midi % 12]}${Math.floor(midi / 12) - 1}`;
+}
+
+/** True when `value` is a MIDI integer 0..127 or a parseable pitch name. */
+export function isPitch(value: unknown): value is number | string {
+  if (typeof value === "number")
+    return Number.isInteger(value) && value >= 0 && value <= 127;
+  return typeof value === "string" && Number.isFinite(pitchToMidi(value));
+}