@hraness/dawg 0.6.1 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 dawg is a local-first terminal music workstation with an agent-driven piano roll. Run `dawg` in a project directory, open it in more than one terminal window, and each window can focus on a different track in the same composition.
 
-The highway sits above a multiline prompt. Notes stream toward a hit line, sustains stretch across beats, and transport controls stay live while you ask the agent to add or reshape music. The session is stored locally in `.dawg`, so there is no account, login, hosted session, or required service for the core workflow.
+The highway sits above a multiline prompt. Notes stream toward a hit line, sustains stretch across beats, and transport controls stay live while you ask the agent to add or reshape music. The session is stored locally in `.dawg`, so there is no account, hosted session, or required service for the core workflow.
 
 ## Install
 
@@ -15,17 +15,17 @@ 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.6.1/hraness-dawg-0.6.1.tgz
+bun add -g https://github.com/hraness/dawg/releases/download/v0.8.0/hraness-dawg-0.8.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.6.1 --repo hraness/dawg
+gh release download v0.8.0 --repo hraness/dawg
 shasum -a 256 -c SHA256SUMS
-gh attestation verify hraness-dawg-0.6.1.tgz --repo hraness/dawg
-bun add -g "$PWD/hraness-dawg-0.6.1.tgz"
+gh attestation verify hraness-dawg-0.8.0.tgz --repo hraness/dawg
+bun add -g "$PWD/hraness-dawg-0.8.0.tgz"
 ```
 
 dawg is also on npm as [`@hraness/dawg`](https://www.npmjs.com/package/@hraness/dawg):
@@ -109,26 +109,28 @@ duration note <id> 0.25
 /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`).
+`/help` opens the command reference in an overlay under ten topics (sound, voice, effects, rhythm, chords, mix, arrange, project, keys, agent), with every command listed once in its bare form (`tempo 96`, `track drums`, `export loop.wav`); the slash is optional everywhere, and only `/rename`, `/fork`, `/resume`, `/auth` and `/play` (play mode; bare `play` is the transport) keep it. The same topic ids work in `/guide` and `/menu`. 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.
+A track named `drums` (or `kit`) starts with the `kit` instrument; `instrument kit` turns any track into a drum track. Drums 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 `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.
+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. Below 60×16 the screen shows `terminal too small · W×H · need ≥ 60×16`, centered and updating as you resize; playback, the daemon and the agent keep going, space plays and stops, q and ctrl-c quit, other keys are dropped, and the real UI comes back unchanged once the terminal is big enough.
 
 | 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 |
+| Enter                 | send now (NOW) or run after the agent turn (NEXT)                            |
+| Shift-Enter, Ctrl-J   | newline                                                                      |
+| Alt-Enter             | run this prompt next, after the agent turn                                   |
+| Ctrl-Q                | toggle the NOW / NEXT 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                                                                         |
+| Ctrl-L                | full redraw                                                                  |
+| Ctrl-C                | exit                                                                         |
 
-A STEER submit runs ahead of queued work. Bracketed paste preserves multiline input.
+Ctrl-T opens TAPE: every track across the bars, one row each, with sections and the loop bracket on top. Each key runs one typed command and echoes it on the prompt (`c` copies the range, `v` pastes it, `\` loops the section here), so the screen teaches the typed form. The same edits as commands: `loop 5-6`, `copy bass 5-6 to 7 x2`, `move bass 5-6 to 9`, `clear bass 5-6`, `reverse bass 5-6`, `bars insert 2 at 9`, `jump 5.3`, `section split chorus at 13`, `form print`. `knobs` turns four knobs (● ▲ ■ ◆) on the sound, `mix`, master, tempo or an effect. Several terminals can share one session as panes: `panes` lists them, `pane tape` turns this one into a tape pane, `pin` keeps the drawer on one parameter and `follow b` mirrors pane B. `undo` undoes this pane's last edit; `undo all` anyone's. `audio out <name>` and `audio in <name>` pick devices on this machine (`audio test` plays a tone; `dawg doctor` shows the choice). `/help arrange`, `/help panes` and `/guide tape` teach each of these.
+
+A NOW send runs ahead of work waiting as NEXT. 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 `▶`/`⏸`.
 
@@ -138,18 +140,18 @@ A STEER submit runs ahead of queued work. Bracketed paste preserves multiline in
 
 ## Auth
 
-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]`.
+Run `dawg model key` (or just `dawg` the first time) to give the agent a model; `dawg login` is an alias. 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                                                                                                                                                                                                                        |
+| Option                     | Detected from                                                        | Setup                                                                                                                                                                                                                          |
 | -------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 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.                                                                                                                            |
+| ChatGPT/Codex subscription | [xcb](https://github.com/hraness/xcb) accounts with provider `codex` | Lists ready accounts and their models; runs `xcb setup codex` (in the browser) when none is ready.                                                                                                                             |
 | Claude subscription        | xcb accounts with provider `claude`                                  | Same, with `xcb setup claude`.                                                                                                                                                                                                 |
 
-- 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.
+- Shortcuts: `dawg model key gateway|openrouter|codex|claude` (`--account <id> --model <id>` for subscriptions), `dawg model key --xcb` for any xcb account (Devin too), `dawg model key --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 model key` without asking. `dawg model key <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.
+- `model key` 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`).
@@ -159,9 +161,9 @@ Run `dawg login` (or just `dawg` the first time) to give the agent a model. dawg
 
 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.
+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 NOW message that the agent reads at its next step. A NEXT submit (Ctrl-Q toggles now / next) 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=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`).
+Playback renders deterministic stereo PCM with sine, piano, pluck, bass, saw, square, and triangle voices plus a synthesized 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. Live keys play through the native sink (a small Rust library with a real audio callback, about 17 ms key to heard on macOS) when a verified prebuilt ships for the platform; otherwise playback falls back to the stdin players, and `dawg doctor` says which and why. Playback is gapless: one long-lived player (the native sink, else `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)).
 
@@ -170,7 +172,9 @@ The agent can download a YouTube reference, split stems, analyze tempo and key,
 | 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_BACKEND=native\|ffplay\|sox\|afplay`              | force a player (`none` is still accepted and means the same as `DAWG_AUDIO=0`)                                                          |
+| `DAWG_AUDIO_DEVICE`, `DAWG_AUDIO_BUFFER`, `DAWG_PLAY_LEAD_MS` | native sink output device name, device buffer frames (128) and play-mode lead (15 ms; 60 ms on stdin players)                           |
+| `DAWG_SINK_LIB`                                               | load this native sink library instead of the verified prebuilt (development; no sha256 check)                                           |
 | `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`)                                                                                |