@hraness/dawg 0.4.1 → 0.5.0

package/guides/audition.md

@@ -0,0 +1,26 @@
+---
+id: audition
+title: Menu and audition loop
+parent: sound
+order: 5
+---
+
+Ctrl-K (or `/menu`) holds every edit the agent can make. Each row shows
+its value and, dimmed, the command it runs, so the menu teaches commands.
+
+## Menu keys
+
+- ↑↓ move · → or Enter open · ←→ adjust a value
+- Enter on a number opens its fader drawer (see Faders and the mouse)
+- `x` reset · `/` filter · Esc back
+- `/menu effects` opens a section (sound effects rhythm chords mix project)
+
+## Audition loop
+
+- Space loops the focused track; changes are staged, not kept
+- `a` A/B: committed sound against staged · `c` solo or in context
+- Enter keeps every staged change as one undo step · Esc reverts
+
+## Try a command
+
+- `/try fx reverb mix 0.6` · `/try synth lpf 800` stage on the loop

package/guides/automation.md

@@ -0,0 +1,26 @@
+---
+id: automation
+title: Automation
+parent: sound
+order: 3
+---
+
+A lane moves a value over beats. Every numeric effect parameter has one.
+
+## Ask
+
+- "fade the pad in over the first four bars"
+- "open the filter slowly across the loop"
+
+## Type it yourself
+
+- `automate volume at 0 0.2` · `automate volume at 4 1`
+- `automate filter points 0:400 4:6000` several points at once
+- `automate pan at 0 -1` · `automate delay-mix at 4 0`
+- `automate distort-drive points 0:1 8:6`
+- `automate filter remove 4` delete one point
+- `clear filter automation` · `clear automation`
+
+## Menu
+
+- Ctrl-K › Mix › automation: each lane, add points, ramp, clear lane

package/guides/chords.md

@@ -0,0 +1,28 @@
+---
+id: chords
+title: Chords
+parent: music
+order: 4
+---
+
+## Ask
+
+- "write a sad pop progression in A minor, two beats per chord"
+- "arpeggiate the chords upward over two octaves"
+
+## Play them
+
+- `key A minor` then Ctrl-P, `q`: every key plays a chord in the key
+- `1 2 3 4` dim min maj sus · `5 6 7 8` add 6, m7, M7, 9
+- `- =` voicing down / up · `9` perform mode · `b` bass mode
+- `n` play the suggested next chord · `0` clear the latches
+
+## Type it yourself
+
+- `/chords auto` · `/chords manual` · `/chords off`
+- `/chords voicing 2` · `/chords spread wide` · `/chords bass chords`
+- `/chords perform arp-up` · `/chords sevenths on` · `/chords`
+
+## Menu
+
+- Ctrl-K › Chords: key, voicing, bass, perform, progression, style

package/guides/effects.md

@@ -0,0 +1,27 @@
+---
+id: effects
+title: Effects
+parent: sound
+order: 2
+---
+
+Chain: filter, auto filter, distortion, tremolo, compressor, pan,
+chorus, delay, reverb, and more (phaser, bitcrush, vowel, leslie).
+
+## Ask
+
+- "add a dub delay to the snare" · "more room on the keys"
+
+## Type it yourself
+
+- `fx` list the focused track's effects
+- `fx delay mix 0.3` · `fx filter type hpf cutoff 300`
+- `fx distort drive 4 tone 5000` · `fx reverb ir hall`
+- `fx chorus on` · `fx chorus off` · `fx chorus reset`
+- `fx compressor preset <name>` load a preset
+- `filter 1200 0.6` · `delay 0.375 0.3` · `reverb 0.4 0.8` · `filter off`
+
+## Menu
+
+- Ctrl-K › Effects: core effects first, then more effects, advanced
+- `fx filter` alone opens the filter's faders, stacked

package/guides/faders.md

@@ -0,0 +1,29 @@
+---
+id: faders
+title: Faders and the mouse
+parent: sound
+order: 6
+---
+
+A fader drawer opens above the prompt to edit a value; the piano roll
+stays visible above it. Edits are staged and heard on the loop.
+
+## Open one
+
+- `volume` · `pan` · `fx filter` · `fx reverb mix` (no value)
+- Ctrl-K, then Enter on a number row · or click it twice
+
+## Keys
+
+- ←→ or `-` `+` step · Shift-←→ coarse · `[` `]` fine · PgUp PgDn big
+- Home End min max · digits type a value · `0` or `d` default
+- ↑↓ or Tab move between the device's params
+- Enter keeps all as one undo step · Esc reverts · `?` all keys
+
+## Mouse
+
+- Click [−] [+] · click or drag the bar · wheel over a fader
+- Click an option to choose it · [keep] [revert] in the title
+- Click a list row to select, again to open · wheel scrolls lists
+- Click ▶/⏸ BPM to play · the track name lists tracks · the model
+- `dawg --no-mouse` or `DAWG_MOUSE=0` turns the mouse off

package/guides/files.md

@@ -0,0 +1,28 @@
+---
+id: files
+title: Project files and SDK
+parent: project
+order: 1
+---
+
+`dawg init` writes `song.ts` and one `tracks/<slug>/track.ts` per track.
+Edit them in any editor; every open window picks up the change.
+
+## Ask
+
+- "rewrite the drums in track.ts with a euclid kick"
+
+## Shell
+
+- `dawg init` · `dawg check` typecheck and evaluate, exit 1 on problems
+- `dawg render out.wav` render the song to a WAV file
+
+## In a track.ts
+
+- `import { track, note, euclid, chord } from "dawg"`
+- `notes: [note("C4", 0, 1), ...chord("Am7", 4, 4)]`
+- `rhythm: [euclid("kick", 4, 16)]`
+
+## In the app
+
+- `/export loop.track.json` · `/import loop.track.json`

package/guides/getting-started.md

@@ -0,0 +1,26 @@
+---
+id: getting-started
+title: Getting started
+order: 1
+---
+
+Run `dawg` in a folder. The highway shows notes; the prompt is below it.
+There are three ways in: ask, play, or open the menu.
+
+## Ask
+
+- "make a four bar lo-fi loop at 85 bpm"
+- "add a bass line under the chords"
+
+## Type it yourself
+
+- `add C4 at 0 for 1` one note on beat 0, one beat long
+- `tempo 120` · `bars 8` · `play` · `pause`
+- Space on an empty prompt plays and pauses
+- `undo` · `redo` (Ctrl-Z · Ctrl-Y)
+
+## Next
+
+- Ctrl-P plays notes on the keyboard, Ctrl-K opens the menu
+- `?` shows the keys for the screen you are on
+- `/help` lists commands, `/guide` opens these guides

package/guides/index.ts

@@ -0,0 +1,75 @@
+/**
+ * The user guides: one Markdown file per feature in this directory, each with
+ * a tiny frontmatter block (`id`, `title`, `order`, optional `parent`). The
+ * TUI's `/guide` pane and the dawg.sh docs render the same files.
+ *
+ * Only `node:fs`, `node:path` and `node:url`, so the site can import it too:
+ * `listGuides(join(process.cwd(), "..", "guides"))`.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface Guide {
+  id: string;
+  title: string;
+  /** The parent guide's id; undefined for a top-level guide. */
+  parent: string | undefined;
+  /** Position among its siblings, smallest first. */
+  order: number;
+  /** Markdown after the frontmatter, without leading or trailing blank lines. */
+  body: string;
+}
+
+/** This directory, where the `.md` guides live next to this file. */
+export const GUIDES_DIR = fileURLToPath(new URL(".", import.meta.url));
+
+/** Parse one guide file; throws with the file name on a malformed header. */
+export function parseGuide(text: string, file = "guide"): Guide {
+  const match = text
+    .replace(/\r\n/g, "\n")
+    .match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) throw new Error(`${file}: missing frontmatter`);
+  const fields = new Map<string, string>();
+  for (const line of match[1]!.split("\n")) {
+    const field = line.match(/^([a-z]+):\s*(.*)$/);
+    if (!field) throw new Error(`${file}: bad frontmatter line "${line}"`);
+    fields.set(field[1]!, field[2]!.trim());
+  }
+  const id = fields.get("id");
+  const title = fields.get("title");
+  const order = Number(fields.get("order"));
+  if (!id || !/^[a-z0-9-]+$/.test(id)) throw new Error(`${file}: bad id`);
+  if (!title) throw new Error(`${file}: missing title`);
+  if (!Number.isFinite(order)) throw new Error(`${file}: bad order`);
+  return {
+    id,
+    title,
+    parent: fields.get("parent") || undefined,
+    order,
+    body: match[2]!.replace(/^\n+|\s+$/g, ""),
+  };
+}
+
+/**
+ * Every guide in tree order: each top-level guide by `order`, followed by its
+ * children by `order` (depth first).
+ */
+export function listGuides(dir: string = GUIDES_DIR): Guide[] {
+  const guides = readdirSync(dir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => parseGuide(readFileSync(join(dir, name), "utf8"), name));
+  const byOrder = (a: Guide, b: Guide) =>
+    a.order - b.order || a.id.localeCompare(b.id);
+  const out: Guide[] = [];
+  const visit = (parent: string | undefined) => {
+    for (const guide of guides
+      .filter((g) => g.parent === parent)
+      .sort(byOrder)) {
+      out.push(guide);
+      visit(guide.id);
+    }
+  };
+  visit(undefined);
+  return out;
+}

package/guides/keys.md

@@ -0,0 +1,27 @@
+---
+id: keys
+title: Keys
+order: 5
+---
+
+`?` shows the keys for the screen you are on; any key closes it.
+
+## Prompt
+
+- Enter send · Shift-Enter new line · Alt-Enter queue · Ctrl-Q queue mode
+- Space play / pause (empty prompt) · Esc cancel or close
+- Ctrl-Z undo · Ctrl-Y redo · Ctrl-O transcript · Ctrl-L redraw
+- Ctrl-P play mode · Ctrl-K menu · F1 guides · Ctrl-C exit
+
+## Lists, menus and guides
+
+- ↑↓ or `j` `k` move · Enter choose · `/` filter · Esc back
+
+## Mouse
+
+- Click rows, header pills, faders · wheel scrolls · `--no-mouse`
+
+## Window
+
+- `/theme default|high-contrast|mono` · `/motion off`
+- `/help` · `/help all` · `/help keys` · `/guide keys`

package/guides/media.md

@@ -0,0 +1,27 @@
+---
+id: media
+title: Samples and media tools
+parent: sound
+order: 6
+---
+
+Downloads land in `tracks/<slug>/downloads/`. A missing
+helper is reported with its install command; `dawg media doctor` checks.
+
+## Ask
+
+- "download <youtube url> and split it into stems"
+- "transcribe the bass stem into notes" · "make a sample of the hook"
+
+## Shell
+
+- `dawg media download <url> --name hook`
+- `dawg media stems <file>` vocals drums bass guitar piano other
+- `dawg media analyze <file>` tempo, key, beat grid
+- `dawg media notes <file> --kind bass` notes as SDK code
+- `dawg media sample <file> hook --begin 0.2 --end 0.3`
+- `dawg media wavetable <file> vox` · `dawg media lyrics <file>`
+
+## In the app
+
+- `/sample <path> as <voice>` · `/sample` lists the voices

package/guides/mix.md

@@ -0,0 +1,23 @@
+---
+id: mix
+title: Mix
+parent: sound
+order: 4
+---
+
+## Ask
+
+- "turn the hats down and pan them right"
+- "sidechain the bass to the kick"
+
+## Type it yourself
+
+- `volume 0.7` (0..1) · `pan -0.4` (-1..1)
+- `mute` · `unmute` · `solo` · `unsolo`
+- `fx orbit 2` send to a bus · `fx orbit shared on` shared reverb
+- `fx duck preset pump` on the kick: it ducks the other tracks
+
+## Menu
+
+- Ctrl-K › Mix: name, mute, solo, volume, pan, all tracks
+- `volume` or `pan` alone opens a fader to drag or step

package/guides/music.md

@@ -0,0 +1,14 @@
+---
+id: music
+title: Writing music
+order: 2
+---
+
+Tracks hold instruments and notes. Each guide below shows what to ask
+the agent and the command, key or menu row that does the same by hand.
+
+- Tracks and instruments
+- Notes and the highway
+- Play mode
+- Chords
+- Rhythm and drums

package/guides/notes.md

@@ -0,0 +1,26 @@
+---
+id: notes
+title: Notes and the highway
+parent: music
+order: 2
+---
+
+Notes stream toward the hit line; sustains stretch across beats.
+Beats count from 0. Each note has an id shown in the receipt.
+
+## Ask
+
+- "add a melody in the last two bars"
+- "make the second note longer and quieter"
+
+## Type it yourself
+
+- `add E4 at 2 for 0.5` add a note
+- `move <id> to 2.5` · `length <id> 0.25` · `velocity <id> 0.6`
+- `remove <id>` delete one note
+- `bars 8` · `extend 4 bars` loop length
+
+## View
+
+- `/view focus` one track · `/view all` every track
+- Ctrl-O or `/transcript` the history of requests and edits

package/guides/performance.md

@@ -0,0 +1,26 @@
+---
+id: performance
+title: Performance and expression
+parent: sound
+order: 7
+---
+
+How notes are played: articulation, glides, bends, pedal and feel.
+Targets are `all` (default), `bar 3`, `bars 2-4` or note ids.
+
+## Ask
+
+- "make the bass slide like a 303" · "ghost the off-beat hats"
+- "pedal the piano every bar" · "humanize the drums a little"
+
+## Type it yourself
+
+- `art staccato|legato|accent|tenuto|marcato|ghost [target]`
+- `glide 60ms legato` per track · `glide 60ms bar 2` per note
+- `bend scoop|fall|doit|-200 [target]` · `vibrato 5.5 30 0.2`
+- `pedal 0-3.5 4-7.5` (beats) · `pedal bars` · `pedal off`
+- `velcurve soft|hard|fixed 0.7` · `humanize 8 5 10 seed 3`
+
+## Menu
+
+- Ctrl-K › Sound › performance (`/menu performance`)

package/guides/play.md

@@ -0,0 +1,24 @@
+---
+id: play
+title: Play mode
+parent: music
+order: 3
+---
+
+Ctrl-P (or `/play`) turns the computer keyboard into a piano for the
+focused track. Esc (or `/play off`) leaves it.
+
+## Keys
+
+- `a s d f g h j k l ; '` white keys · `w e t y u o p` black keys
+- `z` `x` octave down / up · `c` `v` velocity down / up
+- Shift + note sustains · Tab sustain latch
+- `r` record arm · `R` record replacing · Space play (counts in)
+- `m` metronome click · `q` chord mode · `/` type a command
+
+## Commands
+
+- `/click on` · `/click off` · `/click 40%` click volume
+- `/count-in 2` bars of click before recording (0, 1 or 2)
+- `/grid 1/16` record quantize (1/4 1/8 1/8T 1/16 1/16T 1/32)
+- Ctrl-Z undoes one recorded bar

package/guides/project.md

@@ -0,0 +1,13 @@
+---
+id: project
+title: Projects and sessions
+order: 4
+---
+
+Everything is local in `.dawg`. A project adds plain TypeScript files
+you and the agent can edit; windows on one folder stay in sync.
+
+- Project files and SDK
+- Sessions and windows
+- Providers and models
+- Web search

package/guides/providers.md

@@ -0,0 +1,25 @@
+---
+id: providers
+title: Providers and models
+parent: project
+order: 3
+---
+
+Commands work offline. Plain requests go to the agent once a provider
+is set: AI Gateway, OpenRouter, or a Codex or Claude subscription.
+
+## Shell
+
+- `dawg login` finds existing setups and lets you pick
+- `dawg login gateway` · `openrouter` · `codex` · `claude`
+- `dawg model` pick a model with the cost per prompt
+- `dawg auth status --check` · `dawg logout`
+
+## In the app
+
+- `/login` · `/model` picker · `/model <alias>` · `/logout`
+- `/auth --check` provider and audio status
+
+## Environment
+
+- `DAWG_PROVIDER=gateway` · `DAWG_MODEL=<alias>` · `DAWG_AI=0` no agent

package/guides/rhythm.md

@@ -0,0 +1,26 @@
+---
+id: rhythm
+title: Rhythm and drums
+parent: music
+order: 5
+---
+
+## Ask
+
+- "give me a house beat" · "add a swung hat, seven hits in sixteen"
+
+## Type it yourself
+
+- `/pattern house` a starting groove · `/pattern` picker (previews)
+- `/kit syn909` a drum kit · `/kit` picker
+- `hit kick at 0` · `hit snare at 1 vel 0.7`
+- `pattern kick 0 1 2 3` · `pattern hat every 0.5 from 0.25`
+- `euclid hat 7 16 rotate 2` hits spread over steps
+- `euclid hat swing 0.15` · `euclid hat off` · `euclid hat freeze`
+- `grid snare ....X.......x...` explicit steps, X accents
+- `clear hat` remove one voice
+
+## Editor
+
+- `/euclid` (Ctrl-K › Rhythm): ↑↓ voice, ←→ adjust, Tab field,
+  Space loop, `x` off, Esc back

package/guides/sessions.md

@@ -0,0 +1,21 @@
+---
+id: sessions
+title: Sessions and windows
+parent: project
+order: 2
+---
+
+Open `dawg` in more than one terminal on the same folder: each window
+focuses a different track and every edit syncs to all of them.
+
+## Type it yourself
+
+- `/sessions` list · `/resume` picker · `/resume 2` or a name
+- `/rename night drive` · `/rename --auto` back to auto-naming
+- `/fork` copy the session to try an idea · `/status`
+- `/track bass` focus another track in this window
+
+## Shell
+
+- `dawg --new` new session · `dawg --session <name>` open one
+- `dawg --track bass` start focused on a track · `dawg sessions`

package/guides/sound.md

@@ -0,0 +1,15 @@
+---
+id: sound
+title: Shaping sound
+order: 3
+---
+
+Every track has an instrument, a fixed effects chain, automation lanes
+and a place in the mix. Try changes on a loop before you keep them.
+
+- Sounds and presets
+- Effects
+- Automation
+- Mix
+- Menu and audition loop
+- Samples and media tools

package/guides/sounds.md

@@ -0,0 +1,25 @@
+---
+id: sounds
+title: Sounds and presets
+parent: sound
+order: 1
+---
+
+## Ask
+
+- "make the lead brighter with a slow filter sweep"
+- "find a 909 kick in a sample pack"
+
+## Type it yourself
+
+- `instrument sawtooth` · sine square triangle supersaw pulse
+- `synth preset pluck` · pad lead bass acid keys bell organ strings
+- `synth lpf 800 lpenv 3` any parameter · `synth adsr 0.01 0.2 0.5 0.3`
+- `synth lpf off` · `synth reset` · `synth` lists what is set
+- `wt list` tables · `wt pwm` load one · `wt 0.5` position
+- `/pack list` · `/pack use <pack>/<sound> as kick` · `/pack info vcsl`
+- `/sample samples/kick.wav as kick` add a sampler voice
+
+## Menu
+
+- Ctrl-K › Sound: instrument, preset, envelope, filter, browse sounds

package/guides/tempo.md

@@ -0,0 +1,26 @@
+---
+id: tempo
+title: Tempo and meter
+parent: music
+order: 6
+---
+
+One tempo map drives playback, the click, recording and MIDI export.
+Positions are beats from 0 or `bar <n>`.
+
+## Ask
+
+- "slow down to 80 over the last four bars"
+- "switch to 7/8 at bar 5" · "hold the final chord"
+
+## Type it yourself
+
+- `tempo 90 at bar 9` step · add `ramp` or `exp` to glide into it
+- `rit 4 bars to 80` · `accel 8 bars to 174 at bar 9`
+- `fermata at 31 2` hold beat 31 for 2 extra beats
+- `meter 7/8 at bar 5` · `tempo map` show it · `tempo clear`
+- `track rate 3/2` · `track cycle 3` · `track phasing 3` · `track time off`
+
+## Menu
+
+- Ctrl-K › Project › Tempo & meter (`/menu tempo`)

package/guides/tracks.md

@@ -0,0 +1,25 @@
+---
+id: tracks
+title: Tracks and instruments
+parent: music
+order: 1
+---
+
+## Ask
+
+- "add a pad track playing long chords"
+- "make the lead a pluck and the bass a sub"
+
+## Type it yourself
+
+- `/track drums` focus a track, creating it (drums get the kit)
+- `/tracks` list every track
+- `track name lead` rename the focused track
+- `instrument piano` · `instrument supersaw` · `instrument kit`
+- `meter 3` beats per bar · `key A minor` · `key none`
+- `clear` remove the focused track's notes
+
+## Menu
+
+- Ctrl-K › Sound › instrument
+- Ctrl-K › Mix › all tracks (choosing one focuses it)

package/guides/web-search.md

@@ -0,0 +1,21 @@
+---
+id: web-search
+title: Web search
+parent: project
+order: 4
+---
+
+The agent can search the web and read public pages, for example to look
+up a song's tempo or a chord chart. Fetches never reach private hosts.
+
+## Ask
+
+- "look up the tempo and key of Teardrop by Massive Attack"
+- "read this page and copy its chord chart: <url>"
+
+## Where results come from (first match wins)
+
+- `DAWG_WEB_SEARCH=duckduckgo|openrouter|gateway|brave` pins one
+- `BRAVE_SEARCH_API_KEY` set: Brave Search
+- an AI Gateway key (Exa by default), then an OpenRouter key
+- otherwise DuckDuckGo, with no key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/dawg",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,6 +20,8 @@
     "core/sdk/**",
     "tui/**/*.ts",
     "!tui/**/*.test.ts",
+    "guides/*.md",
+    "guides/index.ts",
     "CHANGELOG.md",
     "DAWG.md"
   ],