@hraness/dawg 0.6.0 → 0.7.0

package/guides/audition.md

@@ -1,26 +1,32 @@
 ---
 id: audition
 title: Menu and audition loop
-parent: sound
-order: 5
+parent: keys
+order: 1
 ---
 
-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.
+Each menu row shows its value and, dimmed, the command it runs, so the
+menu teaches the commands. Changes are staged on a loop until you keep.
 
-## Menu keys
+## Ask
 
-- ↑↓ 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)
+- "try a darker filter on the lead before keeping it"
 
-## Audition loop
+## Type it yourself
 
-- Space loops the focused track; changes are staged, not kept
-- `a` A/B: committed sound against staged · `c` solo or in context
+- `menu effects` opens a topic · `try fx reverb mix 0.6` stages one
+
+## Menu
+
+- Ctrl-K opens Sound, Voice, Effects, Rhythm, Chords and key, Mix,
+  Arrange and Project: the same topics as `help` and `guide`
+
+## Keys
+
+- ↑↓ move · → or Enter open · ←→ adjust a value · `x` reset · Esc back
+- Space loops the track · `a` A/B · `c` solo or in context
 - Enter keeps every staged change as one undo step · Esc reverts
 
-## Try a command
+## Next
 
-- `/try fx reverb mix 0.6` · `/try synth lpf 800` stage on the loop
+- `guide faders` · `guide keys`

package/guides/automation.md

@@ -1,8 +1,8 @@
 ---
 id: automation
 title: Automation
-parent: sound
-order: 3
+parent: mix
+order: 1
 ---
 
 A lane moves a value over beats. Every numeric effect parameter has one.
@@ -16,11 +16,17 @@ A lane moves a value over beats. Every numeric effect parameter has one.
 
 - `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
+- `automate delay-mix at 4 0` · `automate filter remove 4`
 - `clear filter automation` · `clear automation`
 
 ## Menu
 
-- Ctrl-K › Mix › automation: each lane, add points, ramp, clear lane
+- Ctrl-K › Mix › automation: each lane, add points, ramp, clear
+
+## Keys
+
+- In a lane row ←→ moves the point · `x` clears the lane
+
+## Next
+
+- `guide mix` · `guide resample`

package/guides/chords.md

@@ -1,8 +1,7 @@
 ---
 id: chords
-title: Chords
-parent: music
-order: 4
+title: Chords and key
+order: 7
 ---
 
 ## Ask
@@ -10,19 +9,22 @@ order: 4
 - "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`
+- `key A minor` · `scale D hijaz` · `progression i7 IV7 each 8`
+- `chords auto` · `chords voicing 2` · `chords perform arp-up`
+- `strum G D Em C folk` · `guitar tune dadgad` · `guitar capo 2`
 
 ## Menu
 
-- Ctrl-K › Chords: key, voicing, bass, perform, progression, style
+- Ctrl-K › Chords and key › key · play · progression · idiom
+
+## Keys
+
+- Ctrl-P play mode, `q`: every key plays a chord in the key
+- `1 2 3 4` dim min maj sus · `5 6 7 8` 6, m7, M7, 9
+- `- =` voicing · `9` perform · `b` bass · `n` next chord · `0` clear
+
+## Next
+
+- `guide tuning` · `guide play`

package/guides/effects.md

@@ -1,29 +1,31 @@
 ---
 id: effects
 title: Effects
-parent: sound
-order: 2
+order: 5
 ---
 
-Chain: filter, auto filter, distortion, tremolo, compressor, pan,
-chorus, delay, reverb, and more (phaser, bitcrush, vowel, leslie).
+Each track has a fixed chain: filter, auto filter, distortion, tremolo,
+compressor, chorus, delay, reverb, and more (phaser, bitcrush, vowel).
 
 ## Ask
 
-- "add a dub delay to the snare" · "more room on the keys"
-- "give the guitar a crunchy amp"
+- "add a dub delay to the snare" · "give the guitar a crunchy amp"
 
 ## 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
-- `rig crunch` guitar rig · `head lead` · `cab 4x12` · `stomp fuzz`
-- `filter 1200 0.6` · `delay 0.375 0.3` · `reverb 0.4 0.8` · `filter off`
+- `fx` lists the focused track's effects · `fx delay mix 0.3`
+- `fx filter type hpf cutoff 300` · `fx chorus on` · `fx chorus reset`
+- `rig crunch` · `rig shoegaze` · `head lead` · `stomp fuzz`
+- `filter 1200 0.6` · `delay 0.375 0.3` · `reverb 0.4 0.8`
 
 ## Menu
 
-- Ctrl-K › Effects: core effects, Guitar rig, more effects, advanced
-- `fx filter` alone opens the filter's faders, stacked
+- Ctrl-K › Effects › Delay · Reverb · Guitar rig · Shoegaze
+
+## Keys
+
+- `fx filter` alone opens its faders, stacked · Tab next param
+
+## Next
+
+- `guide mix` · `guide automation`

package/guides/faders.md

@@ -1,29 +1,33 @@
 ---
 id: faders
 title: Faders and the mouse
-parent: sound
-order: 6
+parent: keys
+order: 2
 ---
 
-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.
+A fader drawer opens above the prompt; edits are heard on the loop.
 
-## Open one
+## Ask
 
-- `volume` · `pan` · `fx filter` · `fx reverb mix` (no value)
-- Ctrl-K, then Enter on a number row · or click it twice
+- "turn the reverb up a little and let me hear it"
+
+## Type it yourself
+
+- `volume` · `pan` · `fx filter` · `fx reverb mix` (no value opens it)
+
+## Menu
+
+- Ctrl-K, then Enter on a number row · or click the row 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
+- ←→ or `-` `+` step · Shift-←→ coarse · `[` `]` fine · Home End
+- digits type · `0` default · Tab next · Enter keeps · Esc reverts
 
 ## 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
+- Click [−] [+] · drag the bar · wheel · `dawg --no-mouse` turns it off
+
+## Next
+
+- `guide audition` · `guide mix`

package/guides/files.md

@@ -12,17 +12,21 @@ Edit them in any editor; every open window picks up the change.
 
 - "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
+## Type it yourself
 
+- `dawg init` · `dawg check` · `dawg render out.wav`
 - `import { track, note, euclid, chord } from "dawg"`
 - `notes: [note("C4", 0, 1), ...chord("Am7", 4, 4)]`
-- `rhythm: [euclid("kick", 4, 16)]`
+- `export loop.track.json` · `import loop.track.json`
+
+## Menu
+
+- Ctrl-K › Project › export
+
+## Keys
+
+- Edits land as one undo step · Ctrl-Z undoes a file change
 
-## In the app
+## Next
 
-- `/export loop.track.json` · `/import loop.track.json`
+- `guide sessions` · `guide project`

package/guides/getting-started.md

@@ -4,23 +4,27 @@ 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.
+Run `dawg` in a folder: notes fall toward the hit line, the prompt is
+below, and every change is one undo step.
 
 ## Ask
 
-- "make a four bar lo-fi loop at 85 bpm"
-- "add a bass line under the chords"
+- "make a four bar lo-fi loop at 85 BPM" (needs an agent: `guide agent`)
+- The pill by the prompt: NOW sends at once, NEXT waits for the agent
 
 ## 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)
+- `track drums` · `pattern house` · `add C4 at 0 for 1` · `tempo 120`
+- `play` · `pause` · `undo` · `redo` · Space on an empty prompt
+
+## Menu
+
+- Ctrl-K: Sound, Voice (sung audio), Effects, Rhythm, Chords and key…
+
+## Keys
+
+- Ctrl-P play mode · Ctrl-K menu · `?` keys · F1 guides · Ctrl-Q next
 
 ## 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
+- `help` start here · `guide sound` · `guide voice` · `guide rhythm`

package/guides/keys.md

@@ -1,27 +1,31 @@
 ---
 id: keys
-title: Keys
-order: 5
+title: Using dawg
+order: 2
 ---
 
-`?` shows the keys for the screen you are on; any key closes it.
+The same keys work on every screen: arrows move, Enter chooses, Esc goes
+back, `?` lists the keys for the screen you are on.
 
-## Prompt
+## Ask
 
-- 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
+- "show me how to make the reverb wetter" (the agent types it for you)
 
-## Lists, menus and guides
+## Type it yourself
 
-- ↑↓ or `j` `k` move · Enter choose · `/` filter · Esc back
+- `theme default|high-contrast|mono` · `motion off` · `view all`
+- `help keys` every key of every screen · `transcript` (Ctrl-O)
 
-## Mouse
+## Menu
 
-- Click rows, header pills, faders · wheel scrolls · `--no-mouse`
+- Ctrl-K › Project › help and guides: help, guides, keys
 
-## Window
+## Keys
 
-- `/theme default|high-contrast|mono` · `/motion off`
-- `/help` · `/help all` · `/help keys` · `/guide keys`
+- Enter send · Shift-Enter new line · Alt-Enter run next · Esc cancel
+- Ctrl-Z undo · Ctrl-Y redo · Ctrl-L redraw · Ctrl-C exit
+- Lists: ↑↓ or `j` `k` move · Enter choose · `/` filter · Esc back
+
+## Next
+
+- `guide audition` · `guide faders` · `guide play`

package/guides/media.md

@@ -2,26 +2,31 @@
 id: media
 title: Samples and media tools
 parent: sound
-order: 6
+order: 4
 ---
 
-Downloads land in `tracks/<slug>/downloads/`. A missing
-helper is reported with its install command; `dawg media doctor` checks.
+Downloads land in `tracks/<slug>/downloads/`. A missing helper prints
+its install command; `dawg media doctor` checks them all.
 
 ## Ask
 
-- "download <youtube url> and split it into stems"
-- "transcribe the bass stem into notes" · "make a sample of the hook"
+- "download <url> and split it into stems" · "make a sample of the hook"
 
-## Shell
+## Type it yourself
 
-- `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 analyze <file>` · `dawg media notes <file> --kind bass`
 - `dawg media sample <file> hook --begin 0.2 --end 0.3`
-- `dawg media wavetable <file> vox` · `dawg media lyrics <file>`
+- `sample <path> as <sample>` · `sample` lists the track's samples
 
-## In the app
+## Menu
 
-- `/sample <path> as <voice>` · `/sample` lists the voices
+- Ctrl-K › Sound › instruments › use a sample · sample packs
+
+## Keys
+
+- Enter on a sample auditions it · Esc back
+
+## Next
+
+- `guide resample` · `guide voice`

package/guides/mix.md

@@ -1,23 +1,29 @@
 ---
 id: mix
 title: Mix
-parent: sound
-order: 4
+order: 8
 ---
 
 ## Ask
 
 - "turn the hats down and pan them right"
-- "sidechain the bass to the kick"
+- "sidechain the bass to the kick" · "master it for streaming"
 
 ## 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
+- `fx orbit 2` send to a bus · `fx duck preset pump` on the kick
+- `master streaming` · `master target -14` · `master measure`
 
 ## Menu
 
-- Ctrl-K › Mix: name, mute, solo, volume, pan, all tracks
+- Ctrl-K › Mix › volume · pan · all tracks · automation · master
+
+## Keys
+
 - `volume` or `pan` alone opens a fader to drag or step
+
+## Next
+
+- `guide automation` · `guide faders`

package/guides/music.md

@@ -1,14 +1,29 @@
 ---
 id: music
 title: Writing music
-order: 2
+parent: arrange
+order: 5
 ---
 
-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.
+A loop grows into a song in four moves: notes, tracks, sections, form.
 
-- Tracks and instruments
-- Notes and the highway
-- Play mode
-- Chords
-- Rhythm and drums
+## Ask
+
+- "start a lo-fi loop, then grow it into verse and chorus"
+
+## Type it yourself
+
+- `add C4 at 0 for 1` · `track pad` · `progression ii V I each 4`
+- `section verse 1-8` · `section chorus 9-16` · `form verse chorus*2`
+
+## Menu
+
+- Ctrl-K › Arrange › sections · form
+
+## Keys
+
+- Ctrl-P play mode plays your idea in · Ctrl-Z undoes any step
+
+## Next
+
+- `guide notes` · `guide chords` · `guide styles`

package/guides/notes.md

@@ -1,12 +1,12 @@
 ---
 id: notes
 title: Notes and the highway
-parent: music
-order: 2
+parent: arrange
+order: 1
 ---
 
-Notes stream toward the hit line; sustains stretch across beats.
-Beats count from 0. Each note has an id shown in the receipt.
+Notes stream toward the hit line; sustains stretch across beats. Beats
+count from 0. Each note has an id shown in the receipt.
 
 ## Ask
 
@@ -15,12 +15,18 @@ Beats count from 0. Each note has an id shown in the receipt.
 
 ## Type it yourself
 
-- `add E4 at 2 for 0.5` add a note
+- `add E4 at 2 for 0.5` · `remove <id>`
 - `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
+## Menu
 
-- `/view focus` one track · `/view all` every track
-- Ctrl-O or `/transcript` the history of requests and edits
+- Ctrl-K › Project › loop length
+
+## Keys
+
+- `view focus` one track · `view all` · Ctrl-O the transcript
+
+## Next
+
+- `guide play` · `guide tracks`

package/guides/performance.md

@@ -2,25 +2,30 @@
 id: performance
 title: Performance and expression
 parent: sound
-order: 7
+order: 2
 ---
 
-How notes are played: articulation, glides, bends, pedal and feel.
-Targets are `all` (default), `bar 3`, `bars 2-4` or note ids.
+How notes are played. Targets: `all`, `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"
+- "make the bass slide like a 303" · "pedal the piano every bar"
 
 ## 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`
+- `glide 60ms legato` · `bend scoop` · `vibrato 5.5 30 0.2`
+- `pedal 0-3.5 4-7.5` · `pedal bars` · `pedal soft 0-8` · `pedal off`
+- `velcurve soft` · `humanize 8 5 10 seed 3`
 
 ## Menu
 
-- Ctrl-K › Sound › performance (`/menu performance`)
+- Ctrl-K › Sound › performance
+
+## Keys
+
+- Shift + note in play mode sustains · Tab latches the sustain
+
+## Next
+
+- `guide sounds` · `guide play`

package/guides/play.md

@@ -1,24 +1,32 @@
 ---
 id: play
 title: Play mode
-parent: music
+parent: keys
 order: 3
 ---
 
-Ctrl-P (or `/play`) turns the computer keyboard into a piano for the
-focused track. Esc (or `/play off`) leaves it.
+Ctrl-P turns the computer keyboard into a piano for the focused track.
+Esc leaves it.
+
+## Ask
+
+- "record what I play over four bars, quantized to sixteenths"
+
+## Type it yourself
+
+- `play on` · `play off` · `play degrees` · `play in-key`
+- `click 40%` · `count-in 2` bars · `grid 1/16` record quantize
+
+## Menu
+
+- Ctrl-K › Project › click · count-in bars · grid
 
 ## 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
+- `a s d f g h j k l` white keys · `w e t y u o p` black keys
+- `z` `x` octave · `c` `v` velocity · Shift + note sustains · Tab latch
+- `r` record · `R` replace · Space play · `m` click · `q` chord mode
 
-## Commands
+## Next
 
-- `/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
+- `guide chords` (chord mode) · `guide notes`

package/guides/project.md

@@ -1,13 +1,30 @@
 ---
 id: project
-title: Projects and sessions
-order: 4
+title: Project
+order: 10
 ---
 
-Everything is local in `.dawg`. A project adds plain TypeScript files
-you and the agent can edit; windows on one folder stay in sync.
+Everything is local in `.dawg`. The transport, tempo, files and undo
+live here; windows on one folder stay in sync.
 
-- Project files and SDK
-- Sessions and windows
-- Providers and models
-- Web search
+## Ask
+
+- "export the song as MIDI" · "what changed since the last save?"
+
+## Type it yourself
+
+- `play` · `pause` · `tempo 120` · `meter 3` · `click on`
+- `export loop.mid` · `import loop.track.json` · `status`
+- `undo` · `redo` · `calibration latest`
+
+## Menu
+
+- Ctrl-K › Project › play · tempo · export · session · agent
+
+## Keys
+
+- Space plays on an empty prompt · Ctrl-Z · Ctrl-Y
+
+## Next
+
+- `guide files` · `guide sessions` · `guide agent`