feat(rivet): storyboard composition with flexible lengths and meters

Rivet 0.4.0 tells a motif as a story. A timeline of blocks with roles
(statement, answer, departure, return, rest) replaces tasks, pins and
branches. Rivet writes each block from a motif and joins the seams with
a cut, breath, pickup or approach.

- Motifs of 1-8 bars in a bin of 16; storyboards up to 32 bars.
- Meters 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 and 12/8 for import, writing,
  audition and export. Phrygian, harmonic minor and Mixolydian scales.
- Per-block options, Another take and Keep; templates for new boards.
- Editor rebuilt: motif bin, timeline, large piano roll, inspector,
  tabs for generation, harmony and sound roles, 32-step undo/redo.
- Sessions from 0.1-0.3 open as a storyboard from their source motif.

docs/rivet/CHANGELOG.md

@@ -1,8 +1,20 @@
 # Rivet changelog
 
-## Unreleased
+## 0.4.0
 
-- New dark metallic look with a single accent colour, shared with Patina.
+- Storyboard: a timeline of blocks with roles (statement, answer, departure,
+  return, rest). Rivet writes each block from a motif and joins the seams with a
+  cut, breath, pickup or approach. Templates start a storyboard in one click.
+- Flexible lengths: motifs of 1–8 bars, storyboards up to 32 bars, and the
+  meters 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 and 12/8 for import, writing and export.
+- A motif bin holds up to 16 motifs; locks live on each motif's notes.
+- Per-block options with Another take and Keep replace proposals and pins.
+- Undo/redo for every edit (32 steps) replaces kept history and branches.
+- New editor: motif bin, timeline, one large piano roll, inspector, and tabs
+  for generation, harmony and sound roles. Dark metallic look shared with Patina.
+- Three more scales: Phrygian, harmonic minor and Mixolydian.
+- Queued auditions switch at the next bar line of the session's meter.
+- Sessions from 0.1–0.3 open as a storyboard built from their source motif.
 
 ## 0.3.0
 

docs/rivet/README.md

@@ -1,52 +1,61 @@
 # Rivet
 
 Rivet joins short motifs into connected musical phrases, like a fastener joining
-individual pieces. Formerly **Motif Storyboard**; current version **0.3.0**.
+individual pieces. Formerly **Motif Storyboard**; current version **0.4.0**.
 
 
-A Rust composition companion for an experienced producer developing their own
-melodic ideas. Version 0.3 explores rhythm, space, contour, harmonic arrivals, and
-returns, with reusable gestures, branching ideas, and two sound roles.
+A Rust composition companion for a producer developing their own melodic ideas.
+Version 0.4 is built around a **storyboard**: a timeline of blocks that tell one
+short idea as a story. Each block has a role (statement, answer, departure,
+return, rest) and a length; Rivet writes each block from your motif and joins the
+seams so the result plays as one phrase.
 
 ![Rivet editor](assets/editor.png)
 
 ## Write with it
 
-1. Import a monophonic MIDI motif of up to two bars in 4/4, or load the demo.
-2. Choose a task: **Develop the motif**, **Write an answer**, **Make room**, or
-   **Find a return**. Choose a settled or open ending and a four/eight-bar length.
-3. Decide what defines the idea. **Keep groove** fixes note positions and lengths;
-   **Keep contour** protects the direction of movement, allowing flattened steps
-   at register limits. Click source notes to lock the whole note, pitch only, or
-   rhythm only. Clicking uses the currently selected lock mode. Locks
-   and identity constraints take precedence over the proposed transformations.
-4. Optionally open **Harmony** and import a chord/bass MIDI track (up to eight
-   bars), or create and edit a four-chord progression. Imported overlapping notes
-   become pitch-class regions with the actual lowest held pitch; the tool does
-   not guess chord roots or chord names. Empty regions remain gaps, and short
-   contexts repeat. Harmony guides strong notes and arrivals; the preview plays
-   the melody only. Supplied chord tones may extend beyond the selected scale.
-5. Explore alternatives. A deterministic pool of eight transformation families
-   supplies up to three distinct proposals, selected for the task and differences
-   in rhythm, density, duration, and pitch. Fully constrained motifs may yield
-   fewer than three; cosmetic velocity differences do not count as new ideas.
-6. Select a proposal and pin its two-bar sections. Select another to fill the
-   remaining sections, or explore another take. Preview and export the combined
-   phrase from the fixed bottom toolbar. Keep a combined result to retain it
-   independently of new proposals; undo/redo switches the kept result and its
-   previous value. Individual proposals and kept results can also be exported.
+1. **Bring in a motif.** Import a monophonic MIDI clip of one to eight bars, or
+   press **Demo**. The bin on the left holds up to 16 motifs. When the bin is
+   empty, the file's time signature and tempo become the session's.
+2. **Lock what defines it.** Select the motif; the big roll shows it. Click notes
+   to lock the whole note, its pitch only, or its rhythm only. Locked notes
+   survive into every block.
+3. **Lay out the story.** A new motif starts as an arc: statement, answer,
+   departure, return. **Build from this motif** applies other templates
+   (question and answer, breathe with rests, build with two departures).
+   **Add block** inserts any role after the selected block. Blocks are 1–8 bars;
+   a storyboard holds up to 32 bars in 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 or 12/8.
+4. **Shape each block.** Click a block in the timeline or the roll. The inspector
+   on the right sets its role, motif, length and how it hands over to the next
+   block. It also lists up to three options written for that role; click one to
+   use it, or **Audition** it alone. **Another take** writes three new options
+   for that block only. **Keep** freezes a block so later changes to key, reach
+   or harmony leave it alone.
+5. **Join the seams.** Click the small circle between two blocks to cycle its
+   join: **Cut** (as written), **Breath** (the last note ends early to leave
+   air), **Pickup** (two short notes lead into the next block) or **Approach**
+   (the last note steps next to the next block's first note).
+6. **Play and export.** **Play** (or Space) loops the whole storyboard. While it
+   plays, edits are heard from the next bar line. **Export MIDI…** writes the
+   storyboard to drag into FL Studio. **Undo**/**Redo** (Ctrl+Z, Ctrl+Shift+Z)
+   step back through the last 32 edits.
 
-The opening quotation stays intact. Later sections use displaced entries,
-repeated pickups, fragments, subtraction, short/long answers, changed endings,
-register contrast, and returns. These are compositional suggestions, not promises
-of an emotion or of commercial originality. Different seeds choose structured
-alternatives; they do not independently randomize every pitch.
+The tabs under the roll hold the less frequent settings:
 
-Pins survive task/seed/harmony changes and regeneration. Changing the motif,
-its locks, or the phrase length clears pins. Pinned sections override newly
-proposed material. Unsafe boundaries in legacy candidates are rejected instead
-of truncating sustained notes. Changing generation inputs clears current
-proposals while retaining kept work.
+- **Generation**: reach (how far options move from the motif), keep groove,
+  keep contour, a settled or open ending for the last block, the register, the
+  seed, and the audition output.
+- **Harmony**: import a chord or bass MIDI track, or start from an editable
+  progression. Harmony guides strong notes and arrivals; audition plays the
+  melody only. Imported voicings keep their pitch classes; Rivet does not guess
+  chord names.
+- **Sound roles**: split the phrase between two synth parts (see below).
+
+Options come from eight transformation families: displaced groove, fragment,
+room to breathe, short call and long answer, familiar return, changed ending,
+higher peak and held back. Each role prefers the families that fit it, and the
+statement always offers the motif as written. Options are deterministic for a
+given seed, take and position; they are suggestions, not promises of an emotion.
 
 ## Audition and commit
 
@@ -54,8 +63,7 @@ proposals while retaining kept work.
 notes and optional CC curves on the configured channels to routed external synths
 and mutes the internal voice. Solo defaults to channel 1.
 Looping is optional and enabled for new sessions. When audition is already
-running, another selection waits until the next two-bar boundary or current
-phrase end. Note-offs precede repeated same-pitch note-ons; stop, replacement,
+running, another selection waits until the next bar line. Note-offs precede repeated same-pitch note-ons; stop, replacement,
 loop boundaries, reset, restoration, and mode changes release active output notes
 on the processing thread. Queued auditions are canceled by Stop.
 
@@ -66,15 +74,7 @@ Exported MIDI is in musical ticks and carries the local BPM as its tempo event.
 Native OS MIDI drag-out is not implemented; export files to commit a phrase.
 See [FL Studio setup and acceptance checks](fl-studio.md).
 
-Open **Gestures, moves, and branches** to save a source or selected two-bar
-section with its performance choices. Export/import a gesture library between
-projects. Save a branch before experimenting; restore any branch and make a new
-child with subtraction, a delayed entry, longer gates, or transposition.
-Moves respect pins and locks, reject unsafe overlaps, and report when constraints
-leave nothing to change. Libraries and histories each hold up to 16 entries;
-remove a gesture or a leaf branch to make room.
-
-Open **Sound roles and expressive gestures** to pass existing notes between two
+Open **Sound roles** to pass existing notes between two
 patches: alternate events, alternate question/answer bars, or divide strong beats
 from replies. These modes distribute a monophonic phrase rather than generate
 a second independent melody. Assign separate MIDI channels and explicitly map
@@ -91,12 +91,12 @@ names, channels, and CC curves. Stop resets mapped controllers to their chosen
 stop values. Internal audition does not reproduce mapped timbre.
 See [the theory and producer workflow](theory/README.md).
 
-Sessions save inside the host project and can be saved/loaded as JSON. Version-1/2
-sessions and the original host field identifier remain supported; older sessions
-retain one-shot audition. New sessions persist harmony, task, lock modes on notes,
-pins, proposals, kept history, gestures, branches, patch profiles, CC curves, and
-audition settings. JSON state is bounded at 16 MiB; gesture libraries at 2 MiB. File export/save refuses to
-silently overwrite an existing file.
+Sessions save inside the host project and can be saved/loaded as JSON. Sessions
+from versions 0.1–0.3 open as a storyboard: the old source motif becomes the
+first motif in the bin, a kept phrase and saved gestures follow it, and an
+eight-bar phrase becomes an arc (a four-bar phrase becomes statement and return).
+Branch history is not carried over; undo replaces it. JSON state is bounded at
+16 MiB. File export/save refuses to silently overwrite an existing file.
 
 ## Build and offline preview
 
@@ -110,8 +110,9 @@ cargo run -p rivet-preview -- session saved-session.json /tmp/rendered-session
 python scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu
 ```
 
-The preview writes source/candidate MIDI, a session JSON, and WAV using the same
-engine as the plugin. Track indices exclude conductor-only tracks and start at
+The preview builds an arc storyboard from the motif and writes the motif and
+storyboard as MIDI, a session JSON, a WAV render using the same engine as the
+plugin, and a table of blocks with their chosen options. Track indices exclude conductor-only tracks and start at
 zero. Optional harmony arguments accept a separate polyphonic MIDI file.
 See [development](../development.md) for checks, dependencies, architecture, and
 [releases](../releases.md) for independent release tags.
@@ -124,8 +125,9 @@ choices. [Devath reference measurements](research/devath.md) document
 analysis of the seven supplied FLACs, with reproducible plots and explicit limits.
 Original reference audio is excluded from source distribution.
 
-- `rivet-core`: musical model, harmonic context, structured proposals, section
-  composition, session migration, and bounded playback clips.
+- `rivet-core`: meters, motifs, the storyboard (blocks, roles, joins, templates),
+  role-aware option writing, harmonic context, session migration, and bounded
+  playback clips.
 - `rivet-midi`: bounded SMF 0/1 import/export. Rejects SMPTE, unsupported meters,
   incomplete notes, and timing not exactly representable at 960 PPQ. Reports
   ignored controllers/pitch bends. Polyphonic tracks work as harmonic context;
@@ -134,7 +136,8 @@ Original reference audio is excluded from source distribution.
   preview/MIDI scheduling, and Windows/Zenity dialogs.
 - `rivet`: CLAP wrapper, host persistence, editor, and standalone.
 
-Tests cover musical constraints/diversity, harmony, legacy state, section seams,
+Tests cover musical constraints/diversity, harmony, every meter, storyboard
+limits, joins, kept blocks, legacy state migration,
 MIDI round trips, sample timing, looping, queued switches, note releases, and
 zero allocation/deallocation during rendering and queued clip replacement. The
 CLAP ABI test verifies discovery, note-output port exposure, state restoration,

docs/rivet/fl-studio.md

@@ -18,21 +18,23 @@ against FL Studio in this environment.
 
 - Open and close the editor repeatedly; verify keyboard input and controls work
   at 100%, 150%, and 200% Windows display scaling, with no clipped content.
-- Load the demo, generate three continuations, and audition each. The opening
-  must match the source; candidates should be audibly related and differ later.
-- Lock a source note, regenerate, and verify pitch, velocity, start, and duration
-  are unchanged at each repeated position. Locks may override register/scale.
-- Try four/eight bars, all scales, different seeds, and rhythm preservation.
-- Accept candidate A; accept B; undo/redo. Regenerate with a different seed and
-  confirm accepted work remains available.
-- Export selected and accepted MIDI separately. Import each into the piano roll
-  of an existing synth and compare note timing, duration, velocity, and length.
+- Load the demo. The storyboard must show statement, answer, departure and
+  return; Play must loop all eight bars. The statement should quote the motif.
+- Lock a motif note and confirm it appears unchanged (pitch, start, length) in
+  every block that develops the motif. Locks may override register/scale.
+- Change a block's role, length (1–8 bars) and motif; try Another take and Keep.
+  Change the key: kept blocks must not change, the others must.
+- Cycle each seam through Cut, Breath, Pickup and Approach and listen at the seam.
+- Try 3/4, 6/8 and 12/8, all scales, and storyboards up to 32 bars.
+- Undo and redo a series of edits, including a template rebuild and a meter change.
+- Export the storyboard. Import it into the piano roll of an existing synth and
+  compare note timing, duration, velocity, length and time signature.
 
 ## Import and files
 
 - Import a monophonic MIDI file exported from FL Studio at 96/480/960 PPQ.
 - Import multitrack MIDI and select the intended note track.
-- Verify useful errors for chords/overlaps, motifs longer than two bars,
+- Verify useful errors for chords/overlaps, motifs longer than eight bars, a full bin,
   unsupported meters, malformed files, and inaccessible paths.
 - Cancel native dialogs. Try Unicode paths and the manual file-path controls.
 - Export to an existing filename; confirm it is refused and the file is intact.
@@ -46,7 +48,7 @@ against FL Studio in this environment.
   local tempo controls audition speed. Host start must never trigger audition.
 - At 44.1/48/96 kHz and several buffer sizes, confirm stable timing and no clicks
   at ordinary note boundaries, dropouts, or non-finite output.
-- Save a project containing locks, candidates, an accepted result, and history.
+- Save a project containing locks, several motifs, kept blocks and joins.
   Reopen it, confirm all state is restored and preview remains stopped.
 - Save/load a JSON session; reject unsupported versions without changing the
   current session. Test multiple plugin instances for independent state.
@@ -64,7 +66,7 @@ piano roll. Native MIDI drag-out is outside this release.
   installed FL Studio version. Keep the MIDI-file export path as fallback.
 - Audition through the actual production patch with the surrounding project loop.
   Host tempo follows BPM only; start audition at the desired point manually.
-  Switching a running audition waits for the next local two-bar boundary or end.
+  Switching a running audition waits for the next bar line.
 - Test Loop on/off, same-pitch repeated notes, changing Internal/MIDI mode while
   playing, rapid queued selections, Stop before a queued switch, host transport
   stop, and project reload. There must be no hanging external notes.
@@ -73,22 +75,14 @@ piano roll. Native MIDI drag-out is outside this release.
 - Test whole-note, pitch-only, and rhythm-only locks. Keep groove must retain
   onset/duration; keep contour must prevent direction reversals except that a
   register limit can flatten a step. Locks override other targets.
-- Pin bars 3–4 from proposal A, select B, and preview/export the combined phrase.
-  Regenerate with another seed: pinned notes must remain exact. Change the motif
-  or phrase length: pins clear. Restore a version-1 session and a version-2
-  project with harmony, pins, and kept history.
+- Restore a version-1 session and a version-2/3 project with harmony, pins and
+  kept history: each must open as a storyboard built from its source motif.
 - Evaluate artistic usefulness through the real patch: can the producer choose
-  a meaningful alternative, retain just its useful section, and make it his own?
+  a meaningful option per block, keep just the useful ones, and make it their own?
   Automated diversity metrics do not replace that evaluation.
 
-## Version 0.3: gestures, branches, roles, and controllers
+## Version 0.3: sound roles and controllers
 
-- Save a named source gesture and a developed two-bar gesture. Export the library
-  and import it into another instance: notes, locks, and performance choices
-  should survive; recalling keeps the destination harmony.
-- Save a branch, apply Subtract to bars 3–4, restore the parent, and try Longer
-  gates instead. Both children should remain available. Restore each after
-  saving/reopening the host project. Remove leaves without losing their parent.
 - Try each role mode. Route channels 1 and 2 to separate patch parts (or choose
   other distinct channels). Verify every original note belongs to one role.
   A host configuration must preserve channels; MIDI file export provides named
@@ -109,6 +103,6 @@ piano roll. Native MIDI drag-out is outside this release.
 - Locks protect musical note attributes; attack/release compensation adjusts
   MIDI trigger scheduling for the patch. Judge the audible onset against the
   surrounding groove rather than expecting every trigger to stay on the grid.
-- Evaluate whether a saved gesture still feels like the same idea with another
-  patch, and whether branching makes it easy to retain useful exceptions.
+- Evaluate whether the storyboard still feels like the same idea with another
+  patch.
   The internal voices and the automated checks cannot establish artistic quality.

docs/rivet/implementation.md

@@ -1,54 +1,64 @@
-# Rivet 0.2 implementation plan
+# Rivet 0.4 implementation notes
 
 ## Musical intent
-Develop a producer's own motif through audible choices about recognition, space,
-contrast, and return. Offer three distinct compositional proposals rather than
-three randomly shifted versions. Emotional interpretation stays with the producer.
+Tell a producer's own motif as a story. The unit of work is a storyboard of
+blocks; each block has a role that says what it does for the story, and Rivet
+writes the notes for that role from the motif. Emotional interpretation stays
+with the producer.
 
-## Engine
-- Keep an exact opening quotation. Build subsequent two-bar sections as statement,
-  answer, departure, and return (four-bar phrases use statement and return).
-- Add tasks Develop, Answer, Make space, and Return. Generate a deterministic pool
-  using rhythmic displacement, fragmentation, call/response, sparse subtraction,
-  a later register peak, changed endings, and harmonic returns; remove duplicates
-  and choose three candidates by task fit and musical distance. Return fewer if
-  locks make three distinct outcomes impossible.
-- Preserve groove and contour independently. Per-note locks protect pitch, rhythm,
-  or every attribute. Locked events survive subtraction; rhythm locks keep exact
-  timing and duration. Global constraints and locks take precedence over transforms.
-- Optional harmony consists of bounded time regions with pitch-class masks and
-  bass pitch. Accept polyphonic MIDI without claiming chord-root detection. Also
-  provide editable per-bar chord progressions. Guide metrically strong notes and
-  ending targets using the actual harmony at that time. Open endings prefer an
-  available scale tone outside the ending chord; closed endings use chord tones.
-- Candidate generation changes note count, spacing, duration, and articulation
-  when constraints allow. Preserve recognizable fragments; avoid overlaps and
-  clipping MIDI values. Keep generated notes within two-bar section boundaries so
-  sections can be combined safely.
+## Model
+- **Meter.** One time signature per session: 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 or
+  12/8. Bar length is `PPQ * 4 * beats / unit`. Compound meters (6/8, 12/8) pulse
+  in dotted quarters; strong positions, pickups and breaths use that pulse.
+- **Motif.** A monophonic phrase of 1–8 whole bars with per-note locks (whole
+  note, pitch, rhythm). The bin holds 16 motifs.
+- **Block.** Motif, role, 1–8 bars, the join into the next block, a take number,
+  up to three realized options, the chosen option, and a keep flag. A storyboard
+  holds 32 blocks and 32 bars.
+- **Roles.** Statement, Answer, Departure, Return and Rest. Each role ranks the
+  transformation families that suit it (statement: quote, displaced groove,
+  changed ending; answer: call/response, changed ending, held back; departure:
+  higher peak, displaced groove, fragment; return: familiar return, quote, room
+  to breathe). The quote is always in the pool, so a statement can play the
+  motif as written. Rest yields one silent option.
+- **Realizing a block.** The motif is tiled to the block length (notes crossing
+  the end are shortened, or dropped when rhythm-locked), then developed. The seed
+  mixes the session seed, the block's take and its position, so options are
+  deterministic and differ between blocks. Harmony is read at the block's
+  absolute position. The last sounding block follows the ending setting; other
+  statements prefer an open last note.
+- **Joins.** Applied when the storyboard is composed, never stored in options.
+  Breath ends the last note at least half a beat before the seam. Approach moves
+  the last note one scale step next to the following first note. Pickup writes
+  two half-beat notes in the last beat that move toward the following first note;
+  it is skipped when anchors occupy that beat. Defaults follow the roles: into a
+  departure a pickup, into a return an approach, around rests a cut, otherwise a
+  breath.
+- **Keep.** Kept blocks are not rewritten when settings, harmony or neighbours
+  change, unless their stored options no longer fit (for example after a meter
+  change).
 
-## Producer workflow
-Import motif -> choose identity/locks -> optionally import or enter harmony ->
-choose task -> audition alternatives -> pin two-bar sections -> export combined
-MIDI or accept a complete candidate. Retain accepted work during regeneration.
-Pins survive changes to task and seed, and clear when source or phrase length
-changes. Pinned material overrides regenerated sections. Reject unsafe seams
-rather than silently truncate a sustained note.
+## Editor
+Header (key, scale, meter, tempo, play, loop, undo/redo, export), motif bin,
+timeline with role-coloured blocks and clickable seams, one large roll (the
+storyboard, or the selected motif for lock editing), inspector (block or motif),
+and tabs for generation, harmony and sound roles. Edits are synchronous; file
+dialogs run on a worker. Undo keeps the last 32 session states in the editor;
+continuous drags and typing collapse into one step. While the storyboard plays,
+an edit queues the new composition for the next bar line.
 
-## Audition
-Keep the internal voice and add a MIDI output mode. Preview is explicitly started,
-optionally loops, and switches pending selections at the next two-bar boundary or
-current clip end. Stop, replacement, mode changes, reset, and state restoration
-release emitted notes. Host transport start never auto-starts audition. All clips,
-queues, scheduling, and MIDI event emission remain bounded and allocation-free
-on the audio thread. Validate FL Studio routing manually; retain MIDI file export
-as the reliable commit path. Native OS MIDI drag-out is outside this release.
+## Compatibility
+State version 4. Versions 1–3 are read leniently and upgraded: the source motif,
+a kept phrase and saved gestures enter the bin; an eight-bar phrase becomes an
+arc, a four-bar phrase statement and return. Branch history is dropped. Future
+versions are rejected without changing the current session. The CLAP ID and the
+`story-session-v1` host field are unchanged.
 
-## Compatibility and verification
-Write state version 2; migrate version-1 JSON and host fields with serde defaults,
-retain legacy strategy names for old candidates, and keep the persisted host field
-identifier. New controls/harmony/pins/audition choices persist. Test timing, locks,
-contour, harmonic targets, candidate diversity, section composition, migration,
-loop boundaries, sample-accurate note events, queued switches, and RT allocation.
-Run existing core/ABI tests and Clippy, render the updated editor, and package
-Windows CLAP plus Linux CLAP/standalone. Do not claim Devath-derived algorithms or
-FL Studio validation without direct evidence.
+## Verification
+Core tests cover role options and diversity, locks, a fully locked motif,
+harmony and endings, all meters, keys and lengths, templates, limits, joins,
+kept blocks, compound meters, motif removal, and v1/v3 migration. MIDI tests
+cover time signatures and compound-meter round trips. App tests cover queued
+switches at the meter's bar line. The CLAP ABI test restores a 6/8 storyboard
+session through host state. FL Studio routing and musical usefulness still need
+checks in the host (see [FL Studio](fl-studio.md)).

docs/rivet/theory/README.md

@@ -35,12 +35,14 @@ returns; Petals retains more consistent activity through much of its early span.
 These observations motivate exploring both contrast and continuous development.
 They do not identify exact notes, chords, emotional meaning, or melodic roles.
 
-## Implemented creative model (0.3)
+## Implemented creative model (0.4)
 
-- A reusable gesture stores a short musical phrase and its explicit performance
-  choices. A name records the producer's interpretation; it is not inferred emotion.
-- A bounded branching history stores working ideas, ancestry, context, and pinned
-  decisions. Composable moves create children rather than overwrite their parent.
+- A storyboard tells one motif through roles: statement (recognition), answer
+  (reply), departure (contrast: register, rhythm, fragments), return (arrival),
+  and rest (space). This puts the recognition/space/contrast/return findings
+  directly on the timeline instead of hiding them in a task menu.
+- Seams between blocks carry explicit joins (breath, pickup, approach), so
+  connection is a visible decision rather than an accident of concatenation.
 - Two sound roles can share or answer a motif through explicit routing. Each role
   has a separate MIDI channel, gate, velocity response, octave offset, and patch
   timing profile. The roles are user-assigned, not separated from mixed audio.
@@ -56,9 +58,10 @@ They do not identify exact notes, chords, emotional meaning, or melodic roles.
 
 ## Producer workflow and evaluation
 
-Import or recall a gesture -> choose context and what to preserve -> explore a
-proposal -> save a branch -> apply a move -> distribute sound roles -> map an
-expressive controller -> audition through real patches -> keep or branch again.
+Import a motif -> lock what defines it -> lay out roles on the storyboard ->
+pick an option per block and set the joins -> keep what works, take again where
+it does not -> distribute sound roles and map controllers -> audition through
+real patches -> export.
 Compare alternatives against the same surrounding loop and listening level.
 The useful outcome is a section the producer can own and develop further.
 
@@ -68,12 +71,10 @@ universal quality scoring, or a verified melodic transcription of Devath's track
 
 ## Concrete limits and implementation
 
-A gesture is at most two bars; a working phrase is four or eight bars.
-Libraries and branch histories each retain up to sixteen entries. A branch
-stores musical settings, source, harmony, the composed phrase, pinned sections,
-and performance choices without recursively copying the history. Importing a
-library merges validated entries with new identifiers. State versions 1 and 2
-migrate to version 3; controller output is disabled by default.
+A motif is 1–8 bars; a storyboard is up to 32 blocks and 32 bars in one of
+seven meters. The bin holds 16 motifs. Each block stores up to three options.
+Sessions from versions 1–3 migrate to version 4; controller output stays
+disabled by default.
 
 Role assignment partitions existing notes, so it preserves a readable motif
 before sound design. It is not source separation or independent counterpoint.
@@ -85,7 +86,7 @@ Negative attack triggers receive a warmup and a separate repeated-loop schedule.
 
 Composition and performance compilation run away from the audio callback.
 The callback uses fixed event storage and bounded control queues. Regression
-checks cover history forks, migration, locks, two-role event identity, MIDI
+checks cover storyboard limits and joins, migration, locks, two-role event identity, MIDI
 channels/controller export, warmup/loop timing, mapping resets, and allocation-free
 rendering. Actual patch perception, FL Studio routing, and producer usefulness
 still require listening in the target workflow.